LLM Agent Orchestrator

System Architecture

Core Components

1. AgentSimulation (agent_logic.py)

Central orchestration engine managing conversation state, chat history, retry logic, JSON validation, and file system operations.

2. LLM Provider Layer (llm_providers.py)

Data Flow

1. User Input → Prompt
2. Select Agent (Round-Robin / QUESTION TO)
3. Load Context (Architect plan + current/ files)
4. LLM API Call (with bounded retry/backoff)
5. Parse Response (validate JSON if Programmer)
6. Save Files (current/ + versions/)
7. Update UI → Next Turn

File System Structure

output/project_name_20240115_143022/
├── logs/
│   ├── conversation.log      # JSON-lines
│   └── agents.json            # Config snapshot
├── current/                   # EXECUTABLE
│   ├── main.py
│   └── src/
│       ├── __init__.py        # Auto-generated
│       └── main.py
└── versions/                  # HISTORY
    ├── main.py.v001
    └── main.py.v002

Communication Protocols

JSON Self-Healing

1. Parser detects syntax error in Programmer response
2. Error message constructed with original attempt
3. Correction prompt sent back to Programmer (no turn increment)
4. Loop until valid JSON or retry limit is reached
5. Valid JSON → Files saved → Flow continues

Agent System

1. Strategist (Konrad) - Optional

2. Project Manager (Klaus)

3. Software Architect (Eva)

4. Programmer (Ben)

JSON Format:

{"files": [
  {"file_path": "main.py", "content": "..."},
  {"file_path": "engine.py", "content": "..."}
]}

5. Bug-Hunter (Findus)

6. Consensus Finder (Judge)

Communication Patterns

Round-Robin:
  PM → Architect → Programmer → Bug-Hunter → Consensus

Question-Based:
  Bug-Hunter finds error → QUESTION TO Programmer
  Programmer fixes → Back to Bug-Hunter
  Bug-Hunter approves → Continue to Consensus

Configuration System

Agent Parameters

Recommended Configs by Role

Environment Variables

Best Practices

• System Prompts: Use ALL-CAPS for critical rules (NEVER, MUST, ALWAYS)
• Temperature: Code generation: 0.1-0.3, Design: 0.5-0.7, Brainstorming: 0.8-1.0
• Tokens: 1 token ≈ 4 characters. Account for context overhead
• Ordering: Architect MUST come before Programmer (plan cached for context injection)

Simulation Workflow

1. Initialization

1. Launch the web application
2. Load default agent config
3. Check API key environment variables
4. Detect available LLM providers

2. Configuration

3. Orchestration Loop

Round N:
  Turn 1-5: Agents respond in sequence

  If APPROVAL → Advance Round / End
  If QUESTION TO → Jump to target agent
  Else → Next agent

4. Multi-Pass Refinement

Pass 1: Programmer delivers → Bug-Hunter finds issue
 Pass 2: Programmer fixes → Bug-Hunter approves
 Pass 3: Consensus checks → Missing file found
 Pass 4: Programmer adds → Consensus → APPROVAL

5. Completion

Project Resume

1. Select existing project folder
2. System creates backup: backup_pre_resume_TIMESTAMP/
3. Load logs/conversation.log into histories
4. Inject all files from current/
5. Add continuity mandate to prompts
6. Enter new task or "Continue"

Troubleshooting Guide

API Issues

Immediate Red Error

Gemini 400 Error

Local LLM Refused

JSON Errors

Infinite Healing Loop

Import Errors

ModuleNotFoundError

Circular Import

Known Limitations

• Binary Assets: Binary assets and native GUI dependencies may require explicit requirements, approval, and manual review
• Large Projects: 50+ files may exceed context. Workaround: Split into modules
• GUI/game frameworks: Dependencies such as pygame can be installed into .sandbox_deps after approval. Long-running startup probes are treated as acceptable for games and event loops.