# 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](./docs/guide_architecture.md):** Deep-dive into thread synchronization, the task pipeline, and the decoupled state machine.
*   **[Tooling & IPC Reference](./docs/guide_tools.md):** Specification of the Hook API, MCP bridge, and the HITL communication protocol.
*   **[Verification & Simulation Framework](./docs/guide_simulations.md):** Detailed breakdown of the live GUI testing infrastructure and simulation lifecycle.

---

## 3. Setup & Environment

### Prerequisites
*   Python 3.11+
*   [`uv`](https://github.com/astral-sh/uv) for high-speed package management.

### Installation
1.  Clone the repository.
2.  Install dependencies:
    ```powershell
    uv sync
    ```
3.  Configure credentials in `credentials.toml`:
    ```toml
    [gemini]
    api_key = "YOUR_KEY"
    [anthropic]
    api_key = "YOUR_KEY"
    ```

### Running the Engine
Launch the main GUI application:
```powershell
uv run gui_2.py
```

To enable the Hook API for external telemetry or testing:
```powershell
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.