FusionAGI/docs/architecture.md

# FusionAGI Architecture

High-level system components and data flow.

## Component Overview

```mermaid
flowchart LR
    subgraph core [Core]
        Orch[Orchestrator]
        EB[Event Bus]
        SM[State Manager]
    end

    subgraph agents [Agents]
        Planner[Planner]
        Reasoner[Reasoner]
        Executor[Executor]
        Critic[Critic]
        Heads[Heads + Witness]
    end

    subgraph support [Supporting Systems]
        Reasoning[Reasoning]
        Planning[Planning]
        Memory[Memory]
        Tools[Tools]
        Gov[Governance]
    end

    Orch --> EB
    Orch --> SM
    Orch --> Planner
    Orch --> Reasoner
    Orch --> Executor
    Orch --> Critic
    Orch --> Heads
    Planner --> Planning
    Reasoner --> Reasoning
    Executor --> Tools
    Executor --> Gov
    Critic --> Memory
```

## Data Flow (Task Lifecycle)

```mermaid
flowchart TB
    A[User submits task] --> B[Orchestrator]
    B --> C[Planner: plan graph]
    C --> D[Reasoner: reason on steps]
    D --> E[Executor: run tools via Governance]
    E --> F[State + Events drive next steps]
    F --> G{Complete?}
    G -->|No| D
    G -->|Yes| H[Critic evaluates]
    H --> I[Reflection updates memory]
    I --> J[FusionAGILoop: recommendations + training]
    J --> K[Task done / retry / recommendations]
```

## Core Components

- **Orchestrator (Fusion Core):** Global task lifecycle, agent scheduling, state propagation. Holds task graph, event bus, agent registry.
- **Event bus:** In-process pub/sub for task lifecycle and agent messages.
- **State manager:** In-memory (or persistent) store for task state and execution traces.

## Agent Framework

- **Base agent:** identity, role, objective, memory_access, tool_permissions. Handles messages via `handle_message(envelope)`.
- **Agent types:** Planner, Reasoner, Executor, Critic, AdversarialReviewer, HeadAgent, WitnessAgent (`fusionagi.agents`). Supervisor, Coordinator, PooledExecutorRouter (`fusionagi.multi_agent`). Communication via structured envelopes (schemas).

## Supporting Systems

- **Reasoning engine:** Chain-of-thought (and later tree/graph-of-thought); trace storage.
- **Planning engine:** Goal decomposition, plan graph, dependency resolution, checkpoints.
- **Execution & tooling:** Tool registry, permission scopes, safe runner, result normalization.
- **Memory:** Short-term (working), episodic (task history), reflective (lessons).
- **Governance:** Guardrails, rate limiting, tool access control, human override hooks.

## Data Flow

1. User/orchestrator submits a task (goal, constraints).
2. Orchestrator assigns work; Planner produces plan graph.
3. Reasoner reasons on steps; Executor runs tools (through governance).
4. State and events drive next steps; on completion, Critic evaluates and reflection updates memory/heuristics.
5. **Self-improvement (FusionAGILoop):** On `task_state_changed` (FAILED), self-correction runs reflection and optionally prepares retry. On `reflection_done`, auto-recommend produces actionable recommendations and auto-training suggests/applies heuristic updates and training targets.

All components depend on **schemas** for tasks, messages, plans, and recommendations; no ad-hoc dicts in core or agents.

## Self-Improvement Subsystem

```mermaid
flowchart LR
    subgraph events [Event Bus]
        FAIL[task_state_changed: FAILED]
        REFL[reflection_done]
    end

    subgraph loop [FusionAGILoop]
        SC[SelfCorrectionLoop]
        AR[AutoRecommender]
        AT[AutoTrainer]
    end

    FAIL --> SC
    REFL --> AR
    REFL --> AT
    SC --> |retry| PENDING[FAILED → PENDING]
    AR --> |on_recommendations| Recs[Recommendations]
    AT --> |heuristic updates| Reflective[Reflective Memory]
```

- **SelfCorrectionLoop:** On failed tasks, runs Critic reflection and can transition FAILED → PENDING with correction context for retry.
- **AutoRecommender:** From lessons and evaluations, produces recommendations (next_action, training_target, strategy_change, etc.).
- **AutoTrainer:** Suggests heuristic updates, prompt tuning, and fine-tune datasets; applies heuristic updates to reflective memory.
- **FusionAGILoop:** Subscribes to event bus, wires correction + recommender + trainer into a single AGI self-improvement pipeline. Event handlers are best-effort: exceptions are logged and do not break other subscribers.

## AGI Stack

- **Executive:** GoalManager, Scheduler, BlockersAndCheckpoints (`fusionagi.core`).
- **Memory:** WorkingMemory, EpisodicMemory, ReflectiveMemory, SemanticMemory, ProceduralMemory, TrustMemory, ConsolidationJob, MemoryService, VectorMemory (`fusionagi.memory`).
- **Verification:** OutcomeVerifier, ContradictionDetector, FormalValidators (`fusionagi.verification`).
- **World model:** World model base and rollout (`fusionagi.world_model`).
- **Skills:** SkillLibrary, SkillInduction, SkillVersioning (`fusionagi.skills`).
- **Multi-agent:** CoordinatorAgent, SupervisorAgent, AgentPool, PooledExecutorRouter, consensus_vote, arbitrate, delegate_sub_tasks (`fusionagi.multi_agent`). AdversarialReviewerAgent in `fusionagi.agents`.
- **Governance:** Guardrails, RateLimiter, AccessControl, OverrideHooks, PolicyEngine, AuditLog, SafetyPipeline, IntentAlignment (`fusionagi.governance`).
- **Tooling:** Tool registry, runner, builtins; DocsConnector, DBConnector, CodeRunnerConnector (`fusionagi.tools`).
- **API:** FastAPI app factory, Dvādaśa sessions, OpenAI bridge, WebSocket (`fusionagi.api`).
- **MAA:** MAAGate, MPCAuthority, ManufacturingProofCertificate, check_gaps (`fusionagi.maa`).