Update README/install/setup docs and changelog

rwilliamspbg-ops · web-flow · commit 17c1080c0dbc · 2026-07-11T01:39:19.000Z
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,43 @@
 
 All notable changes to the project will be documented in this file.
 
+## [2.1.1] - 2026-07-11
+
+### 🔧 Devcontainer and Setup Reliability
+
+- Updated `.devcontainer/devcontainer.json`:
+	- workspace path compatibility for Codespaces
+	- docker-outside-of-docker feature enablement
+	- Python and Docker VS Code extension recommendations
+	- explicit bash post-create invocation
+- Updated `.devcontainer/Dockerfile` with missing runtime and diagnostics packages.
+- Reworked `.devcontainer/post_create.sh` to be idempotent, root-safe, and configurable with:
+	- `MOHAWK_SKIP_LIBOQS_BUILD=1`
+	- `MOHAWK_SKIP_PY_DEPS=1`
+
+### 🖥️ Full-Stack Desktop GUI Launch Improvements
+
+- Fixed startup ordering in `mohawk_gui/main_window.py`:
+	- initialize status bar before tab refresh paths
+	- start background health thread only after UI widget initialization
+- Added environment-based backend URL overrides for desktop GUI runtime.
+- Added reusable desktop GUI launcher flow in `launch.py` for both native and Docker orchestration.
+- Updated `launch.sh` dependency probe to include `PyQt6`.
+- Added `mohawk-desktop-gui` service to `docker-compose.yml`.
+- Added full-stack parity services to `docker-compose.dev.yml` and adjusted conflicting host port mapping.
+
+### 📚 Documentation Updates
+
+- Updated `README.md` quick-start and documentation index.
+- Updated `QUICKSTART.md` with launcher/devcontainer paths and focused model/chat smoke checks.
+- Updated `DOCKER_SETUP.md` desktop GUI behavior notes and skip flag usage.
+- Added `INSTALL.md` and `SETUP.md` for clear install/runtime guidance.
+
+### ✅ Validation
+
+- End-to-end functional test executed: `python test_user_functions.py`.
+- Result: `33/33 passed (100.0%)` including model list/load and chat inference paths.
+
 ## [2.1.0] - 2024-01-15
 
 ### 🎉 Major Release: Professional Dashboard with LM Studio Features
diff --git a/DOCKER_SETUP.md b/DOCKER_SETUP.md
@@ -71,8 +71,21 @@ The GUI window will open and connect to the Docker-based backend services.
 |---------|------|----------|---------|
 | mohawk-gui | 8003 | Docker Container | Backend API & health endpoints |
 | mohawk-worker | 8004 | Docker Container | Inference worker service |
+| mohawk-desktop-gui | n/a | Docker Container | Desktop GUI launcher (display-dependent) |
 | PyQt6 GUI | (Local) | Your Machine | Desktop application interface |
 
+## Desktop GUI Launch Behavior
+
+- `docker compose up -d --build` includes `mohawk-desktop-gui` for one-click full-stack startup.
+- If `DISPLAY` is not set, the desktop GUI service exits cleanly and backend APIs continue running.
+- `launch.py` sets `MOHAWK_SKIP_DESKTOP_GUI=1` when orchestrating compose to avoid duplicate GUI instances, then launches host desktop GUI directly when supported.
+
+Skip container desktop GUI explicitly:
+
+```bash
+MOHAWK_SKIP_DESKTOP_GUI=1 docker compose up -d --build
+```
+
 ## Container Management
 
 ### View Container Logs
diff --git a/INSTALL.md b/INSTALL.md
@@ -0,0 +1,66 @@
+# Mohawk Inference Engine - Install Guide
+
+## Prerequisites
+
+- Python 3.10+
+- Git
+- Docker + Docker Compose (recommended for full stack)
+- Linux/macOS shell or PowerShell on Windows
+
+For desktop GUI launch on Linux, ensure display libraries and `DISPLAY` are available.
+
+## Clone
+
+```bash
+git clone https://github.com/rwilliamspbg-ops/Mohawk-Inference-Engine.git
+cd Mohawk-Inference-Engine
+```
+
+## Python Environment
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+## Optional: Devcontainer
+
+In VS Code:
+- Dev Containers: Rebuild and Reopen in Container
+
+Then run:
+
+```bash
+bash .devcontainer/post_create.sh
+```
+
+Fast smoke mode:
+
+```bash
+MOHAWK_SKIP_LIBOQS_BUILD=1 MOHAWK_SKIP_PY_DEPS=1 bash .devcontainer/post_create.sh
+```
+
+## Verify Install
+
+```bash
+python - <<'PY'
+import fastapi, uvicorn, requests, psutil
+print('Core dependencies OK')
+PY
+```
+
+## Next
+
+- Go to `SETUP.md` for runtime startup options.
+- Go to `QUICKSTART.md` for API smoke tests.
diff --git a/QUICKSTART.md b/QUICKSTART.md
@@ -15,7 +15,17 @@ Mohawk is a production-grade AI inference engine with:
 
 ---
 
-## Quick Start (Docker)
+## Quick Start Paths
+
+### A) One-Click Launcher
+
+```bash
+./launch.sh
+```
+
+Use menu option 1 (Docker stack) or option 2 (Native host processes). The launcher now attempts to auto-open the desktop GUI when the runtime supports display output.
+
+### B) Docker Full Stack
 
 ### 1. Start All Services
 
@@ -27,6 +37,12 @@ docker compose up -d
 docker ps
 ```
 
+Optional: skip container desktop GUI service when running from raw compose.
+
+```bash
+MOHAWK_SKIP_DESKTOP_GUI=1 docker compose up -d --build
+```
+
 **Expected Output:**
 ```
 CONTAINER ID   IMAGE                        STATUS           PORTS
@@ -47,6 +63,21 @@ curl http://localhost:8004/health
 # {"status":"healthy","service":"...","timestamp":"2026-06-24T..."}
 ```
 
+### C) Devcontainer
+
+```bash
+# In VS Code:
+# Dev Containers: Rebuild and Reopen in Container
+
+bash .devcontainer/post_create.sh
+```
+
+Fast smoke setup without expensive rebuild steps:
+
+```bash
+MOHAWK_SKIP_LIBOQS_BUILD=1 MOHAWK_SKIP_PY_DEPS=1 bash .devcontainer/post_create.sh
+```
+
 ### 3. List Available Models
 
 ```bash
@@ -179,6 +210,23 @@ python test_user_functions.py
 # SUMMARY: 33/33 passed (100.0%)
 ```
 
+### Validate Model Select + Chat Inference Only
+
+```bash
+# List models
+curl http://localhost:8003/api/models
+
+# Load model
+curl -X POST http://localhost:8003/api/models/load \
+  -H "Content-Type: application/json" \
+  -d '{"model": "Llama-3-8B-Instruct-Q4_K_M"}'
+
+# Run chat inference
+curl -X POST http://localhost:8003/api/inference/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message":"Hello from smoke test","temperature":0.7,"top_p":0.9,"max_tokens":128}'
+```
+
 ### View Logs
 
 ```bash
diff --git a/README.md b/README.md
@@ -71,36 +71,51 @@ A secure, scalable GUI for managing multi-device inference sessions with **enter
 
 ## 📦 Quick Start
 
-### Installation (3 minutes)
+### Option A: One-Click Launcher (Recommended)
 
 ```bash
-# Clone repository
-cd C:\Users\rwill\Mohawk-Inference-Engine
+./launch.sh
+```
+
+This bootstraps a local virtual environment, installs missing dependencies, and opens the interactive launcher for native or Docker full-stack modes.
+
+### Option B: Docker Full Stack
+
+```bash
+docker compose up -d --build
+```
 
-# Create virtual environment
-python -m venv venv
-venv\Scripts\activate  # Windows: venv\Scripts\activate
+Services:
+- GUI backend: `http://localhost:8003`
+- Worker service: `http://localhost:8004`
 
-# Install dependencies
+Desktop GUI auto-launches when the display environment supports it. To skip container desktop GUI launch:
+
+```bash
+MOHAWK_SKIP_DESKTOP_GUI=1 docker compose up -d --build
+```
+
+### Option C: Native API + Desktop GUI
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
 pip install -r requirements.txt
 
-# Generate auth key (first run only)
-mkdir -p certs
-python mohawk_gui/main.py --key-file certs/auth_key.pem
+# Start full stack from launcher
+python launch.py
 ```
 
-### Running the Dashboard
+### Validate Inference + Model Selection End-to-End
 
 ```bash
-# Development mode
-python mohawk_gui/main.py
-
-# Production mode with SSL
-python mohawk_gui/main.py \
-    --host 0.0.0.0 \
-    --port 8003 \
-    --ssl-enabled \
-    --key-file certs/auth_key.pem
+python test_user_functions.py
+```
+
+Expected summary:
+
+```text
+SUMMARY: 33/33 passed (100.0%)
 ```
 
 ### Building Executable (Windows)
@@ -266,8 +281,12 @@ docker run -d \
 
 ## 📚 Documentation
 
+- **[📦 Install Guide](INSTALL.md)** - prerequisites and environment setup
+- **[🛠️ Setup Guide](SETUP.md)** - local, Docker, and devcontainer run paths
 - **[📖 Dashboard Features Guide](mohawk_gui/DASHBOARD_FEATURES.md)** - Complete feature documentation
 - **[⚡ Quick Start Guide](mohawk_gui/QUICK_START.md)** - 3-minute setup guide
+- **[⚡ API Quick Start](QUICKSTART.md)** - endpoint-focused smoke flow
+- **[🐳 Docker Setup](DOCKER_SETUP.md)** - container runtime details and troubleshooting
 - **[🏗️ Implementation Plan](GUI_IMPLEMENTATION_PLAN.md)** - Architecture details
 - **[✅ Production Readiness](GUI_PRODUCTION_READINESS.md)** - Quality checklist
 
diff --git a/SETUP.md b/SETUP.md
@@ -0,0 +1,76 @@
+# Mohawk Inference Engine - Setup Guide
+
+## Setup Options
+
+## 1) One-Click Launcher (recommended)
+
+```bash
+./launch.sh
+```
+
+What it does:
+- Creates/uses local virtual environment
+- Installs missing dependencies
+- Offers native and Docker full-stack launch modes
+- Auto-launches desktop GUI when environment supports it
+
+## 2) Docker Full Stack
+
+```bash
+docker compose up -d --build
+```
+
+Services:
+- GUI backend: `http://localhost:8003`
+- Worker: `http://localhost:8004`
+
+Desktop GUI container behavior:
+- Starts when display is available
+- Exits cleanly if `DISPLAY` is missing
+
+Skip desktop GUI container explicitly:
+
+```bash
+MOHAWK_SKIP_DESKTOP_GUI=1 docker compose up -d --build
+```
+
+## 3) Native Backend + GUI
+
+```bash
+source .venv/bin/activate
+python launch.py
+```
+
+Or run API services manually:
+
+```bash
+python -m uvicorn prototype.worker:app --host 127.0.0.1 --port 8004
+python -m uvicorn prototype.gui_backend:app --host 127.0.0.1 --port 8003
+```
+
+## Health Checks
+
+```bash
+curl http://localhost:8003/health
+curl http://localhost:8004/health
+```
+
+## Functional Validation
+
+Run end-to-end checks for model selection and chat inference:
+
+```bash
+python test_user_functions.py
+```
+
+Expected summary:
+
+```text
+SUMMARY: 33/33 passed (100.0%)
+```
+
+## Troubleshooting
+
+- If GUI does not open in Docker mode, verify `DISPLAY` and X11 access.
+- If ports are busy (`8003`, `8004`), stop conflicting processes before launch.
+- If `docker` is unavailable in devcontainer, rebuild container to apply `.devcontainer/devcontainer.json` features.
