133 lines
4.8 KiB
Markdown
133 lines
4.8 KiB
Markdown
# Sloppy
|
|
|
|
|
|
|
|
A GUI orchestrator for local LLM-driven coding sessions. Manual Slop bridges high-latency AI reasoning with a low-latency ImGui render loop via a thread-safe asynchronous pipeline, ensuring every AI-generated payload passes through a human-auditable gate before execution.
|
|
|
|
**Tech Stack**: Python 3.11+, Dear PyGui / ImGui, FastAPI, Uvicorn
|
|
**Providers**: Gemini API, Anthropic API, DeepSeek, Gemini CLI (headless)
|
|
**Platform**: Windows (PowerShell) — single developer, local use
|
|
|
|
|
|
|
|
---
|
|
|
|
## Architecture at a Glance
|
|
|
|
Four thread domains operate concurrently: the ImGui main loop, an asyncio worker for AI calls, a `HookServer` (HTTP on `:8999`) for external automation, and transient threads for model fetching. Background threads never write GUI state directly — they serialize task dicts into lock-guarded lists that the main thread drains once per frame ([details](./docs/guide_architecture.md#the-task-pipeline-producer-consumer-synchronization)).
|
|
|
|
The **Execution Clutch** suspends the AI execution thread on a `threading.Condition` when a destructive action (PowerShell script, sub-agent spawn) is requested. The GUI renders a modal where the user can read, edit, or reject the payload. On approval, the condition is signaled and execution resumes ([details](./docs/guide_architecture.md#the-execution-clutch-human-in-the-loop)).
|
|
|
|
The **MMA (Multi-Model Agent)** system decomposes epics into tracks, tracks into DAG-ordered tickets, and executes each ticket with a stateless Tier 3 worker that starts from `ai_client.reset_session()` — no conversational bleed between tickets ([details](./docs/guide_mma.md)).
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
| Guide | Scope |
|
|
|---|---|
|
|
| [Architecture](./docs/guide_architecture.md) | Threading model, event system, AI client multi-provider architecture, HITL mechanism, comms logging |
|
|
| [Tools & IPC](./docs/guide_tools.md) | MCP Bridge security model, all 26 native tools, Hook API endpoints, ApiHookClient reference, shell runner |
|
|
| [MMA Orchestration](./docs/guide_mma.md) | 4-tier hierarchy, Ticket/Track data structures, DAG engine, ConductorEngine execution loop, worker lifecycle |
|
|
| [Simulations](./docs/guide_simulations.md) | `live_gui` fixture, Puppeteer pattern, mock provider, visual verification patterns, ASTParser / summarizer |
|
|
|
|
---
|
|
|
|
## Module Map
|
|
|
|
| File | Lines | Role |
|
|
|---|---|---|
|
|
| `gui_2.py` | ~3080 | Primary ImGui interface — App class, frame-sync, HITL dialogs |
|
|
| `ai_client.py` | ~1800 | Multi-provider LLM abstraction (Gemini, Anthropic, DeepSeek, Gemini CLI) |
|
|
| `mcp_client.py` | ~870 | 26 MCP tools with filesystem sandboxing and tool dispatch |
|
|
| `api_hooks.py` | ~330 | HookServer — REST API for external automation on `:8999` |
|
|
| `api_hook_client.py` | ~245 | Python client for the Hook API (used by tests and external tooling) |
|
|
| `multi_agent_conductor.py` | ~250 | ConductorEngine — Tier 2 orchestration loop with DAG execution |
|
|
| `conductor_tech_lead.py` | ~100 | Tier 2 ticket generation from track briefs |
|
|
| `dag_engine.py` | ~100 | TrackDAG (dependency graph) + ExecutionEngine (tick-based state machine) |
|
|
| `models.py` | ~100 | Ticket, Track, WorkerContext dataclasses |
|
|
| `events.py` | ~89 | EventEmitter, AsyncEventQueue, UserRequestEvent |
|
|
| `project_manager.py` | ~300 | TOML config persistence, discussion management, track state |
|
|
| `session_logger.py` | ~200 | JSON-L + markdown audit trails (comms, tools, CLI, hooks) |
|
|
| `shell_runner.py` | ~100 | PowerShell execution with timeout, env config, QA callback |
|
|
| `file_cache.py` | ~150 | ASTParser (tree-sitter) — skeleton and curated views |
|
|
| `summarize.py` | ~120 | Heuristic file summaries (imports, classes, functions) |
|
|
| `outline_tool.py` | ~80 | Hierarchical code outline via stdlib `ast` |
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.11+
|
|
- [`uv`](https://github.com/astral-sh/uv) for package management
|
|
|
|
### Installation
|
|
|
|
```powershell
|
|
git clone <repo>
|
|
cd manual_slop
|
|
uv sync
|
|
```
|
|
|
|
### Credentials
|
|
|
|
Configure in `credentials.toml`:
|
|
|
|
```toml
|
|
[gemini]
|
|
api_key = "YOUR_KEY"
|
|
|
|
[anthropic]
|
|
api_key = "YOUR_KEY"
|
|
|
|
[deepseek]
|
|
api_key = "YOUR_KEY"
|
|
```
|
|
|
|
### Running
|
|
|
|
```powershell
|
|
uv run gui_2.py # Normal mode
|
|
uv run gui_2.py --enable-test-hooks # With Hook API on :8999
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```powershell
|
|
uv run pytest tests/ -v
|
|
```
|
|
|
|
---
|
|
|
|
## Project Configuration
|
|
|
|
Projects are stored as `<name>.toml` files. The discussion history is split into a sibling `<name>_history.toml` to keep the main config lean.
|
|
|
|
```toml
|
|
[project]
|
|
name = "my_project"
|
|
git_dir = "./my_repo"
|
|
system_prompt = ""
|
|
|
|
[files]
|
|
base_dir = "./my_repo"
|
|
paths = ["src/**/*.py", "README.md"]
|
|
|
|
[screenshots]
|
|
base_dir = "./my_repo"
|
|
paths = []
|
|
|
|
[output]
|
|
output_dir = "./md_gen"
|
|
|
|
[gemini_cli]
|
|
binary_path = "gemini"
|
|
|
|
[agent.tools]
|
|
run_powershell = true
|
|
read_file = true
|
|
# ... 26 tool flags
|
|
```
|