thoth-coder 0.1.0

Stateful proxy for the Thoth Persistent Coder

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_KEYs.
• 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.
   • 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.

   "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.