manual_slop/Readme.md

Manual Slop

An experimental, high-density AI orchestration engine designed for expert developers. Manual Slop provides a strictly controlled environment for executing complex, multi-tier AI workflows with deterministic human-in-the-loop (HITL) overrides.

---

1. Technical Philosophy

Manual Slop is not a chat interface. It is a Decoupled State Machine built on the principle that AI reasoning should be observable, mutable, and interruptible. It bridges high-latency AI execution with a low-latency, retained-mode GUI via a thread-safe asynchronous pipeline.

Core Features

• Hierarchical MMA (4-Tier Architecture): Orchestrate complex tracks using a tiered model (Orchestrator -> Tech Lead -> Worker -> QA) with explicit token firewalling.
• The Execution Clutch: A deterministic "gear-shifting" mechanism that pauses execution for human inspection and mutation of AI-generated payloads.
• MCP-Bridge & Tooling: Integrated filesystem sandboxing and native search/fetch tools with project-wide security allowlists.
• Live Simulation Framework: A robust verification suite using API hooks for automated visual and state assertions.

---

2. Deep-Dive Documentation

For expert-level technical details, refer to our specialized guides:

• Architectural Technical Reference: Deep-dive into thread synchronization, the task pipeline, and the decoupled state machine.
• Tooling & IPC Reference: Specification of the Hook API, MCP bridge, and the HITL communication protocol.
• Verification & Simulation Framework: Detailed breakdown of the live GUI testing infrastructure and simulation lifecycle.

---

3. Setup & Environment

Prerequisites

• Python 3.11+
• uv for high-speed package management.

Installation

1. Clone the repository.
2. Install dependencies:

   uv sync
   

3. Configure credentials in credentials.toml:

   [gemini]
   api_key = "YOUR_KEY"
   [anthropic]
   api_key = "YOUR_KEY"
   

Running the Engine

Launch the main GUI application:

uv run gui_2.py

To enable the Hook API for external telemetry or testing:

uv run gui_2.py --enable-test-hooks

---

4. Feature Roadmap (2026)

• DAG-Based Task Execution: Real-time visual tracking of multi-agent ticket dependencies.
• Token Budgeting & Throttling: Granular control over cost and context accumulation per tier.
• Advanced Simulation Suite: Expanded visual verification for multi-modal reasoning tracks.