FusionAGI/docs/architecture.md

FusionAGI Architecture

High-level system components and data flow.

Component Overview

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)

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

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