Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
127 lines (110 loc) · 3.83 KB

ARCHITECTURE.md

File metadata and controls

127 lines (110 loc) · 3.83 KB

Architecture

Module Relationships

flowchart TB
    subgraph Entry["Entry Points"]
        CLI[cli.py<br/>Click CLI]
    end

    subgraph Core["Core"]
        Agent[ProductionAgent<br/>agent/agent.py]
        Builder[AgentBuilder<br/>agent/builder.py]
        Registry[ToolRegistry<br/>tools/registry.py]
        Loop[ExecutionLoop<br/>core/loop.py]
    end

    subgraph Providers["LLM Providers"]
        Anthropic[Anthropic]
        OpenRouter[OpenRouter]
        OpenAI[OpenAI]
        ZAI[ZAI]
    end

    subgraph Tools["Built-in Tools"]
        FileOps[File Operations]
        BashTool[Bash Executor]
        SearchTools[Search Tools]
        SpawnAgent[Spawn Agent]
    end

    subgraph Integrations["Integrations"]
        Session[SQLiteStore<br/>Session Persistence]
        MCP[MCPClient<br/>External Tools]
        Context[ContextEngineering<br/>Compaction]
        Perms[PolicyEngine<br/>Approval System]
        Budget[Economics<br/>Budget Management]
        Recording[SessionGraph<br/>Recording]
        Skills[SkillLoader<br/>Skills System]
    end

    subgraph TUI["TUI Layer"]
        TUIApp[AttocodeApp<br/>Textual App]
        Bridges[ApprovalBridge<br/>BudgetBridge]
    end

    CLI --> Builder
    Builder --> Agent
    CLI --> TUIApp
    Agent --> Loop
    Agent --> Registry
    Agent --> Providers
    Registry --> Tools
    Registry --> Perms
    Agent --> Integrations
    TUIApp --> Bridges
    Bridges --> Perms
    MCP --> Registry
Loading

Data Flow

sequenceDiagram
    participant User
    participant TUI as AttocodeApp
    participant Agent as ProductionAgent
    participant LLM as LLM Provider
    participant Tools as ToolRegistry
    participant Perms as PolicyEngine
    participant Store as SessionStore

    User->>TUI: Enter prompt
    TUI->>Agent: run(prompt)
    Agent->>Store: create_session()
    Agent->>LLM: chat(messages)
    LLM-->>Agent: tool_calls[]

    loop For each tool call
        Agent->>Tools: execute(tool, args)
        Tools->>Perms: evaluate(tool, args)
        alt Needs approval
            Perms->>TUI: requestApproval()
            User-->>TUI: Y/N
            TUI-->>Perms: response
        end
        Tools-->>Agent: result
        Agent->>Store: record_tool_call()
    end

    Agent->>LLM: chat(messages + results)
    LLM-->>Agent: response
    Agent->>Store: save_checkpoint()
    Agent-->>TUI: AgentResult
    TUI-->>User: Display response
Loading

Directory Structure

Directory Purpose Key Files
agent/ Agent core orchestration agent.py, builder.py, context.py
core/ Execution engine, LoopDeps protocol loop.py, loop_deps.py, subagent_spawner.py
tools/ Tool implementations 12 tool modules
providers/ LLM adapters, ProcessBackend/AgentExecutor base.py, adapters/, backend.py
integrations/ Feature modules 12 subdirectories
tui/ Terminal UI app.py, 52+ widgets
tracing/ Execution traces JSONL event recording
tricks/ Context engineering Recitation, failure tracking
types/ Shared type definitions agent.py, messages.py

Integration Domains

Domain Module Count Lines Purpose
budget/ 6 ~2,200 Token economics, loop detection
context/ 8 ~3,500 Compaction, codebase analysis
safety/ 8 ~2,000 Sandboxes, policies, validators
persistence/ 1 ~1,100 SQLite session store
agents/ 5 ~1,500 Multi-agent coordination
tasks/ 6 ~2,000 Planning, decomposition
skills/ 4 ~450 Skill loading, deps, state
mcp/ 4 ~800 MCP client integration
recording/ 5 ~1,400 Session graph, playback
swarm/ 12 ~10,300 Multi-agent orchestration
utilities/ 27 ~4,000 Helper modules
streaming/ 1 ~300 PTY shell