docs(conductor): Expert-level architectural documentation refresh
This commit is contained in:
86
Readme.md
86
Readme.md
@@ -1,54 +1,66 @@
|
||||
# Manual Slop
|
||||
|
||||
Vibe coding.. but more manual
|
||||
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.
|
||||
|
||||
|
||||
---
|
||||
|
||||
This tool is designed to work as an auxiliary assistant that natively interacts with your codebase via PowerShell and MCP-like file tools, supporting both Anthropic and Gemini APIs.
|
||||
## 1. Technical Philosophy
|
||||
|
||||
Features:
|
||||
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.
|
||||
|
||||
* Multi-provider support (Anthropic & Gemini).
|
||||
* Multi-project workspace management via TOML configuration.
|
||||
* Rich discussion history with branching and timestamps.
|
||||
* Real-time file context aggregation and summarization.
|
||||
* Integrated tool execution:
|
||||
* PowerShell scripting for file modifications.
|
||||
* MCP-like filesystem tools (read, list, search, summarize).
|
||||
* Web search and URL fetching.
|
||||
* Extensive UI features:
|
||||
* Word-wrap toggles.
|
||||
* Popup text viewers for large script/output inspection.
|
||||
* Color theming and UI scaling.
|
||||
### 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.
|
||||
|
||||
## Session-Based Logging and Management
|
||||
---
|
||||
|
||||
Manual Slop organizes all communications and tool interactions into session-based directories under `logs/`. This ensures a clean history and easy debugging.
|
||||
## 2. Deep-Dive Documentation
|
||||
|
||||
* **Organized Storage:** Each session is assigned a unique ID and its own sub-directory containing communication logs (`comms.log`) and metadata.
|
||||
* **Log Management Panel:** The GUI includes a dedicated 'Log Management' panel where you can view session history, inspect metadata (message counts, errors, size), and protect important sessions.
|
||||
* **Automated Pruning:** To keep the workspace clean, the application automatically prunes insignificant logs. Sessions older than 24 hours that are not "whitelisted" and are smaller than 2KB are automatically deleted.
|
||||
* **Whitelisting:** Sessions containing errors, high activity, or significant changes are automatically whitelisted. Users can also manually whitelist sessions via the GUI to prevent them from being pruned.
|
||||
For expert-level technical details, refer to our specialized guides:
|
||||
|
||||
## Documentation
|
||||
* **[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.
|
||||
|
||||
* [docs/Readme.md](docs/Readme.md) for the interface and usage guide
|
||||
* [docs/guide_tools.md](docs/guide_tools.md) for information on the AI tooling capabilities
|
||||
* [docs/guide_architecture.md](docs/guide_architecture.md) for an in-depth breakdown of the codebase architecture
|
||||
---
|
||||
|
||||
## Instructions
|
||||
## 3. Setup & Environment
|
||||
|
||||
1. Make a credentials.toml in the immediate directory of your clone:
|
||||
### Prerequisites
|
||||
* Python 3.11+
|
||||
* [`uv`](https://github.com/astral-sh/uv) for high-speed package management.
|
||||
|
||||
```toml
|
||||
[gemini]
|
||||
api_key = "****"
|
||||
[anthropic]
|
||||
api_key = "****"
|
||||
### 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
|
||||
```
|
||||
|
||||
2. Have fun. This is experiemntal slop.
|
||||
|
||||
```ps1
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user