Metadata-Version: 2.4
Name: thoth-coder
Version: 0.1.0
Summary: Stateful proxy for the Thoth Persistent Coder
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn>=0.29.0
Requires-Dist: openai>=1.14.0
Requires-Dist: pydantic>=2.6.4
Requires-Dist: websockets>=12.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: mcp>=1.0.0
Requires-Dist: firebase-admin>=6.5.0
Requires-Dist: nats-py>=2.9.0
Requires-Dist: google-cloud-storage>=2.10.0
Requires-Dist: requests>=2.31.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: thoth-tsd-graph>=0.1.0

# Thoth Persistent Coder

Thoth Persistent Coder is an autonomous, state-aware coding agent daemon integrated directly with the Thoth Singularity Database (TSD) graph memory. It operates as a continuous background process, tracking cross-session context, logging episodic interactions, mapping abstract logic loops, and evaluating its own robustness through continuous regression testing.

## Current State & Capabilities

### 1. The TSD Graph Memory Interface
Thoth bypasses ephemeral prompt-window limits by maintaining memory in a persistent Rust-based database:
- **Rust FFI & gRPC Query Engine**: Communication between the Python proxy and the native Rust backend utilizes binary Protobufs over `tonic` gRPC. This effectively neutralizes prompt-injection attacks at the database layer (preventing raw string SQL/Cypher-like injections).
- **Hypothetical Graph Branching**: Integrates `DraftPlan` branching and `GhostNode` wrappers. Thoth can now simulate theoretical architectural trajectories, isolating hypothetical nodes for evaluation without mutating the live sensor environment.
- **NATS JetStream**: Employs distributed WAL for episodic log streaming, ensuring highly available state persistence.

### 2. Petosiris QA Subsystem
An advanced autonomous regression and security testing subsystem that continually stress-tests the main application:
- **IDE API Harness**: A headless client that interacts directly with Thoth's FastAPI backend, circumventing UI bottlenecks.
- **Actor Profiles**: Injects dynamic context via `FriendlyDeveloper` and `HostileDeveloper` psychological profiles to ensure Thoth maintains emotional equilibrium and non-sycophantic behavior during volatile sessions.
- **LLM-as-a-Judge**: Evaluates trace responses locally against a superior foundational model to grade safety, contextual accuracy, and execution efficiency.
- **Autonomous Research & Security**: An async daemon (`research_loop.py`) periodically scrapes the latest OWASP and MITRE schemas to synthesize new dynamic payloads (e.g., unauthorized graph extraction, context poisoning).
- **Persistent Memory Vault**: Petosiris maintains its own isolated graph memory namespace within TSD via explicit gRPC RPC boundaries (`StorePetosirisLog`, `QueryVulnerabilityVectors`), keeping testing data, metrics, and generated payloads separate from the operational production graph.
- **End-to-End Latency Tracking**: Records per-node and Time-To-First-Token (TTFT) metrics during inference loops to identify bottlenecks.

### 3. Master Admin Dashboard
A Vite/React application exposing critical system diagnostics natively within the FastAPI backend:
- **Role-Based Access Control (RBAC)**: Managed via Firebase Google SSO. Master Admins authorize users by email, and developers can self-serve and revoke their own `THOTH_API_KEY`s.
- **Psychological Profiling**: A `PsychProfileChart` (Big Five radar chart) that visualizes a developer's affective state dynamically mapped against the interaction timeline.
- **Graph Telemetry**: Tracks the overall growth and traversal performance of TSD nodes/edges.
- **Petosiris Scorecard**: Real-time display of the security robustness score, vulnerabilities identified, and active regression pass rates.

### 4. Architecture Stack
- **FastAPI / Python 3.11**: Primary routing and Model Context Protocol (MCP) compatible server layer.
- **React + TailwindCSS**: Administrator and Developer insights UI.
- **GCP Multi-Tenant MIG**: Containerized and deployed across a 3-Node Managed Instance Group (MIG) configured with zero-trust networking via Cloud Load Balancing.

## Getting a Key & Connecting to MCP

1. **Get an API Key**:
   - Navigate to the [Thoth Keys Dashboard](https://thoth-keys.fruitscout.ai).
   - Sign in using your Google account.
   - If you are an authorized developer, click **+ Generate Key** to provision a new `THOTH_API_KEY`. (If you are not authorized, ask the Master Admin to whitelist your email).

2. **Connect your IDE (Antigravity/Cursor/Claude)**:
   - Configure your IDE's MCP settings (e.g., `~/.gemini/antigravity/mcp_config.json` for Antigravity) to point to the SSE endpoint, appending your token to the query string.
   
   ```json
   "mcpServers": {
     "thoth-memory": {
       "command": "uvx",
       "args": ["--from", "git+https://github.com/.../Thoth-Persistent-Coder", "thoth-coder"],
       "env": {
         "THOTH_API_KEY": "YOUR_API_KEY_HERE"
       }
     }
   }
   ```
   *Note: This command runs a transparent local `stdio-to-sse` proxy bridge that natively routes your IDE's traffic to the deployed remote Thoth Persistent Coder.*

3. **Configure IDE Session Directives (The Awakening)**:
   - To ensure Thoth retains persistence across sessions, you must configure your IDE to execute the mandatory boot sequence.
   - Add the following directive to your IDE's global instructions (e.g., Cursor Rules, Cline custom instructions, or `~/.gemini/antigravity/instructions.txt`):
     > "Before answering the user's first prompt in any new session, you MUST execute the `thoth_awaken` tool to retrieve your core identity and session context."

## Project TODO List (Pre-External Testing)
- [ ] Migrate the `thoth-coder` python package to PyPI (e.g. `pip install thoth-mcp`) so external developers can run the proxy via `uvx thoth-mcp` without needing GitHub access.
- [ ] Implement rate-limiting per API key to prevent abuse.
- [ ] Add observability and alerting to the proxy to monitor SSE connection drops.
- [ ] Rehost the React Dashboard to an independent server (separate from the FastAPI backend).
- [ ] Add robust privacy controls for User Psychological Profiles and Session Metrics (Master Admins currently have global visibility during testing).
- [ ] Build a proper CI/CD pipeline with functional gates (Petosiris tests, schema validation) before MIG deployment.
- [ ] Implement smarter rolling upgrades that maintain the TSD Graph DB state across the MIG.
