diff --git a/conductor/tracks.md b/conductor/tracks.md index dba983c..e1b9772 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -38,3 +38,9 @@ This file tracks all major tracks for the project. Each track has its own detail - [ ] **Track: Support gemini cli headless as an alternative to the raw client_api route. So that they user may use their gemini subscription and gemini cli features within manual slop for a more discliplined and visually enriched UX.** *Link: [./tracks/gemini_cli_headless_20260224/](./tracks/gemini_cli_headless_20260224/)* + +--- + +- [ ] **Track: Support headless manual_slop for making an unraid gui docker frontend and a unraid server backend down the line.** +*Link: [./tracks/manual_slop_headless_20260225/](./tracks/manual_slop_headless_20260225/)* + diff --git a/conductor/tracks/manual_slop_headless_20260225/index.md b/conductor/tracks/manual_slop_headless_20260225/index.md new file mode 100644 index 0000000..55501c5 --- /dev/null +++ b/conductor/tracks/manual_slop_headless_20260225/index.md @@ -0,0 +1,5 @@ +# Track manual_slop_headless_20260225 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) \ No newline at end of file diff --git a/conductor/tracks/manual_slop_headless_20260225/metadata.json b/conductor/tracks/manual_slop_headless_20260225/metadata.json new file mode 100644 index 0000000..2481e76 --- /dev/null +++ b/conductor/tracks/manual_slop_headless_20260225/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "manual_slop_headless_20260225", + "type": "feature", + "status": "new", + "created_at": "2026-02-25T12:00:00Z", + "updated_at": "2026-02-25T12:00:00Z", + "description": "Support headless manual_slop for making an unraid gui docker frontend and a unraid server backend down the line." +} \ No newline at end of file diff --git a/conductor/tracks/manual_slop_headless_20260225/plan.md b/conductor/tracks/manual_slop_headless_20260225/plan.md new file mode 100644 index 0000000..38eec2b --- /dev/null +++ b/conductor/tracks/manual_slop_headless_20260225/plan.md @@ -0,0 +1,49 @@ +# Implementation Plan: Manual Slop Headless Backend + +## Phase 1: Project Setup & Headless Scaffold +- [ ] Task: Update dependencies + - [ ] Add `fastapi` and `uvicorn` to `pyproject.toml` (and sync `requirements.txt` via `uv`). +- [ ] Task: Implement headless startup + - [ ] Modify `gui_2.py` (or create `headless.py`) to parse a `--headless` CLI flag. + - [ ] Update config parsing in `config.toml` to support headless configuration sections. + - [ ] Bypass Dear PyGui initialization if headless mode is active. +- [ ] Task: Create foundational API application + - [ ] Set up the core FastAPI application instance. + - [ ] Implement `/health` and `/status` endpoints for Docker lifecycle checks. +- [ ] Task: Conductor - User Manual Verification 'Project Setup & Headless Scaffold' (Protocol in workflow.md) + +## Phase 2: Core API Routes & Authentication +- [ ] Task: Implement API Key Security + - [ ] Create a dependency/middleware in FastAPI to validate `X-API-KEY`. + - [ ] Configure the API key validator to read from environment variables or `manual_slop.toml` (supporting Unraid template secrets). + - [ ] Add tests for authorized and unauthorized API access. +- [ ] Task: Implement AI Generation Endpoint + - [ ] Create a `/api/v1/generate` POST endpoint. + - [ ] Map request payloads to `ai_client.py` unified wrappers. + - [ ] Return standard JSON responses with the generated text and token metrics. +- [ ] Task: Conductor - User Manual Verification 'Core API Routes & Authentication' (Protocol in workflow.md) + +## Phase 3: Remote Tool Confirmation Mechanism +- [ ] Task: Refactor Execution Engine for Async Wait + - [ ] Modify `shell_runner.py` and tool-call loops to support a non-blocking "Pending Confirmation" state instead of launching a GUI modal. +- [ ] Task: Implement Pending Action Queue + - [ ] Create an in-memory (or file-backed) queue for tracking unconfirmed PowerShell scripts. +- [ ] Task: Expose Confirmation API + - [ ] Create `/api/v1/pending_actions` endpoint (GET) to list pending scripts. + - [ ] Create `/api/v1/confirm/{action_id}` endpoint (POST) to approve or deny a script execution. + - [ ] Ensure the AI generation loop correctly resumes upon receiving approval. +- [ ] Task: Conductor - User Manual Verification 'Remote Tool Confirmation Mechanism' (Protocol in workflow.md) + +## Phase 4: Session & Context Management via API +- [ ] Task: Expose Session History + - [ ] Create endpoints to list, retrieve, and delete session logs from the `project_history.toml`. +- [ ] Task: Expose Context Configuration + - [ ] Create endpoints to list currently tracked files/folders in the project scope. +- [ ] Task: Conductor - User Manual Verification 'Session & Context Management via API' (Protocol in workflow.md) + +## Phase 5: Dockerization +- [ ] Task: Create Dockerfile + - [ ] Write a `Dockerfile` using `python:3.11-slim` as a base. + - [ ] Configure `uv` inside the container for fast dependency installation. + - [ ] Expose the API port (e.g., 8000) and set the container entrypoint. +- [ ] Task: Conductor - User Manual Verification 'Dockerization' (Protocol in workflow.md) \ No newline at end of file diff --git a/conductor/tracks/manual_slop_headless_20260225/spec.md b/conductor/tracks/manual_slop_headless_20260225/spec.md new file mode 100644 index 0000000..dc03e72 --- /dev/null +++ b/conductor/tracks/manual_slop_headless_20260225/spec.md @@ -0,0 +1,48 @@ +# Specification: Manual Slop Headless Backend + +## Overview +Transform Manual Slop into a decoupled, container-friendly backend service. This track enables the core AI orchestration and tool execution logic to run without a GUI, exposing its capabilities via a secured REST API optimized for an Unraid Docker environment. + +## Goals +- Decouple the GUI logic (`Dear PyGui`, `ImGui`) from the core AI and Tool logic. +- Implement a lightweight REST API server (FastAPI) to handle AI interactions. +- Ensure full compatibility with Unraid Docker networking and configuration patterns. +- Maintain the "Human-in-the-Loop" safety model through a remote confirmation mechanism. + +## Functional Requirements + +### 1. Headless Mode Lifecycle +- **Startup**: Provide a `--headless` flag or `[headless]` section in `manual_slop.toml` to skip GUI initialization. +- **Dependencies**: Ensure the app can start in environments without an X11/Wayland display or GPU. +- **Service Mode**: Support running as a persistent background daemon/service. + +### 2. REST API (FastAPI) +- **Status/Health**: `/status` and `/health` endpoints for Docker/Unraid monitoring. +- **AI Interface**: `/generate` and `/stream` endpoints to interact with configured AI providers. +- **Tool Management**: Endpoints to list and execute tools (PowerShell/MCP). +- **Session Support**: Manage conversation history and project context via API. + +### 3. Security & Authentication +- **API Key**: Require a `X-API-KEY` header for all sensitive endpoints. +- **Unraid Integration**: API keys should be configurable via Environment Variables (standard for Unraid templates). + +### 4. Remote Confirmation Mechanism +- **Challenge/Response**: When a tool requires execution, the API should return a "Pending Confirmation" state. +- **Webhook/Poll**: Support a mechanism (e.g., a `/confirm/{id}` endpoint) for the future frontend to approve/deny actions. + +## Non-Functional Requirements +- **Performance**: Headless mode should use significantly less memory/CPU than the GUI version. +- **Logging**: Use standard Python `logging` for Docker-compatible stdout/stderr output. +- **Portability**: Must run reliably inside a standard `python:3.11-slim` or similar Docker image. + +## Acceptance Criteria +- [ ] Manual Slop starts successfully with `--headless` and no display environment. +- [ ] API is accessible via a configurable port (e.g., 8000). +- [ ] All API requests are rejected without a valid API Key. +- [ ] AI generation works via REST endpoints, returning structured JSON or a stream. +- [ ] Tool execution is successfully blocked until a separate "Confirm" API call is made. + +## Out of Scope +- Building the actual Unraid GUI frontend (React/Vue/etc.). +- Multi-user authentication (OIDC/OAuth2). +- Native Unraid `.plg` plugin development (focusing on Docker). \ No newline at end of file