ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

docs(gemini): refresh to reflect current providers (5), entry point (sloppy.py), and key modules

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-06-02 20:48:56 -04:00
parent 6c5b6fb76d
commit 291e838705
1 changed files with 54 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
GEMINI.md
+54 -23
View File
@@ -1,22 +1,42 @@
# Project Overview
# GEMINI.md
**Manual Slop** is a local GUI application designed as an experimental, "manual" AI coding assistant. It allows users to curate and send context (files, screenshots, and discussion history) to AI APIs (Gemini and Anthropic). The AI can then execute PowerShell scripts within the project directory to modify files, requiring explicit user confirmation before execution.
This file covers Gemini-CLI-specific operational notes for the Manual Slop project. The primary toolchain is Gemini CLI; for general agent orientation, see `AGENTS.md`.
## Project Overview
**Manual Slop** is a local GUI orchestrator for LLM-driven coding sessions. It bridges high-latency AI reasoning with a low-latency ImGui render loop via a thread-safe async pipeline; every AI-generated payload passes through a human-auditable gate before execution.
**Main Technologies:**
* **Language:** Python 3.11+
* **Package Management:** `uv`
* **GUI Framework:** ImGui Bundle (`imgui-bundle`)
* **AI SDKs:** `google-genai` (Gemini), `anthropic`
* **AI SDKs:** `google-genai` (Gemini), `anthropic` (Claude), `openai` (DeepSeek + MiniMax via OpenAI-compatible endpoints), `GeminiCliAdapter` (headless gemini CLI subprocess)
* **Configuration:** TOML (`tomli-w`)
**Architecture:**
* **`gui_legacy.py`:** The main entry point and Dear PyGui application logic. Handles all panels, layouts, user input, and confirmation dialogs.
* **`ai_client.py`:** A unified wrapper for both Gemini and Anthropic APIs. Manages sessions, tool/function-call loops, token estimation, and context history management.
* **`aggregate.py`:** Responsible for building the `file_items` context. It reads project configurations, collects files and screenshots, and builds the context into markdown format to send to the AI.
* **`mcp_client.py`:** Implements MCP-like tools (e.g., `read_file`, `list_directory`, `search_files`, `web_search`) as native functions that the AI can call. Enforces a strict allowlist for file access.
* **`shell_runner.py`:** A sandboxed subprocess wrapper that executes PowerShell scripts (`powershell -NoProfile -NonInteractive -Command`) provided by the AI.
* **`project_manager.py`:** Manages per-project TOML configurations (`manual_slop.toml`), serializes discussion entries, and integrates with git (e.g., fetching current commit).
* **`session_logger.py`:** Handles timestamped logging of communication history (JSON-L) and tool calls (saving generated `.ps1` files).
**Providers Supported (as of 2026-06-02):**
- **Gemini SDK** — Primary; uses server-side CachedContent
- **Gemini CLI** — Headless adapter with full functional parity
- **Anthropic** — Ephemeral prompt caching (4-breakpoint system)
- **DeepSeek** — Code-optimized reasoning
- **MiniMax** — OpenAI-compatible alternative
**Entry Point:** `sloppy.py` (was `gui_legacy.py` before the rename; `gui_2.py` is now the active ImGui application module).
**Architecture (key modules):**
* **`src/gui_2.py`:** Primary ImGui application; App class, frame-sync, HITL dialogs, event system. ~260K lines.
* **`src/ai_client.py`:** Multi-provider LLM abstraction (Gemini, Anthropic, DeepSeek, Gemini CLI, MiniMax). Module-level singleton with state.
* **`src/mcp_client.py`:** 45 MCP tools (file I/O, AST inspection, C/C++ tree-sitter, analysis, network, runtime, Beads). Three-layer security model.
* **`src/multi_agent_conductor.py`:** ConductorEngine + WorkerPool. 4-Tier MMA orchestration with DAG execution.
* **`src/dag_engine.py`:** TrackDAG (cycle detection, topological sort) + ExecutionEngine (tick-based state machine).
* **`src/aggregate.py`:** Context aggregation pipeline.
* **`src/app_controller.py`:** Main controller; bridges GUI and async AI workers.
* **`src/api_hooks.py`:** HTTP API on `:8999` for external automation and IPC.
* **`src/rag_engine.py`:** RAG subsystem (ChromaDB + embedding providers).
* **`src/personas.py`:** Unified agent profile management.
* **`src/workspace_manager.py`:** Workspace profile save/load.
* **`src/hot_reloader.py`:** State-preserving module reloading.
Full module list: `src/*.py`. See `docs/guide_architecture.md` for the threading model and event system.
# Building and Running
@@ -27,22 +47,33 @@
api_key = "****"
[anthropic]
api_key = "****"
[deepseek]
api_key = "****"
[minimax]
api_key = "****"
```
The `credentials.toml` is **blacklisted** by the MCP allowlist — AI tools cannot read it.
* **Run the Application:**
```powershell
uv run .\gui_2.py
uv run sloppy.py # Normal mode
uv run sloppy.py --enable-test-hooks # With Hook API on :8999
```
# Development Conventions
# Gemini-CLI-Specific Conventions
* **Configuration Management:** The application uses two tiers of configuration:
* `config.toml`: Global settings (UI theme, active provider, list of project paths).
* `manual_slop.toml`: Per-project settings (files to track, discussion history, specific system prompts).
* **Tool Execution:** The AI acts primarily by generating PowerShell scripts. These scripts MUST be confirmed by the user via a GUI modal before execution. The AI also has access to read-only MCP-style file exploration tools and web search capabilities.
* **Context Refresh:** After every tool call that modifies the file system, the application automatically refreshes the file contents in the context using the files' `mtime` to optimize reads.
* **Sequential Tooling:** Tools that rely on line numbers (e.g., `py_region_wrap`, `get_file_slice`, `set_file_slice`) MUST be executed sequentially across multiple turns. Never batch multiple line-dependent operations in a single turn, as preceding edits will cause line drift and corrupt subsequent operations.
* **UI State Persistence:** Window layouts and docking arrangements are automatically saved to and loaded from `dpg_layout.ini`.
* **Conductor Extension:** Gemini CLI uses the conductor extension, which reads `./conductor/` for task tracking, workflow, and product context. Tracks live in `conductor/tracks/<name>_<YYYYMMDD>/` with `spec.md`, `plan.md`, and `metadata.json`.
* **Skill Activation:** Use `activate_skill mma-orchestrator` to load the orchestrator skill, then activate the tier-specific skill (e.g., `activate_skill mma-tier1-orchestrator`).
* **The Conductor Convention:** Read `conductor/workflow.md` for the TDD protocol. Treat `conductor/tracks.md` as the task registry. Track implementation follows per-file atomic commits with git notes.
* **Tool Execution:** AI-generated PowerShell scripts and tool calls pass through the Execution Clutch (HITL). Scripts are saved to `scripts/generated/<ts>_<seq>.ps1`.
* **Context Refresh:** After every tool call that modifies the file system, the application automatically refreshes file contents in the context using `mtime` checks.
* **Fuzzy Anchor Resilience:** Line-based operations (`get_file_slice`, `set_file_slice`, `py_update_definition`, fuzzy anchor slices) use FuzzyAnchor to survive file modifications. They can be batched in a single turn without line drift.
* **Layout Persistence:** Window layouts are saved to `manualslop_layout.ini` (was `dpg_layout.ini`).
* **Logging:** All API communications are logged to `logs/sessions/<id>/comms.log`. Tool calls to `toolcalls.log`. Generated scripts to `scripts/generated/`.
* **Code Style:**
* Use type hints where appropriate.
* Internal methods and variables are generally prefixed with an underscore (e.g., `_flush_to_project`, `_do_generate`).
* **Logging:** All API communications are logged to `logs/comms_<ts>.log`. All executed scripts are saved to `scripts/generated/`.
* Use exactly 1-space indentation for Python (NO EXCEPTIONS). See `conductor/product-guidelines.md`.
* Use the manual-slop MCP tools (`manual-slop_edit_file`, `manual-slop_py_update_definition`) for surgical edits — native edit tools destroy indentation.
* Internal methods and variables are prefixed with an underscore (e.g., `_flush_to_project`, `_do_generate`).
# Human-Facing Documentation
For understanding, using, and maintaining the tool, see `docs/Readme.md` and the 14 deep-dive guides it indexes. See `conductor/product.md` for the product vision.