FusionAGI/docs/architecture.md

# FusionAGI Architecture

## Overview

FusionAGI is a modular AGI orchestration framework built on the **Dvādaśa** (12-headed) architecture. Multiple specialized reasoning heads analyze each prompt independently, and a Witness agent synthesizes their outputs into a consensus response.

## Core Architecture

```
User Prompt
    │
    ▼
┌─────────────────────────────────────────┐
│           Orchestrator (core/)           │
│  Decompose → Fan-out → Synthesize       │
├─────────────────────────────────────────┤
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐      │
│  │Logic│ │Creat│ │Resrch│ │Safety│ ...  │
│  │Head │ │Head │ │Head  │ │Head  │      │
│  └──┬──┘ └──┬──┘ └──┬──┘ └──┬──┘      │
│     └───────┴───────┴───────┘           │
│              Witness Agent               │
│         (consensus synthesis)            │
└──────────────┬──────────────────────────┘
               │
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌────────┐ ┌────────┐ ┌────────┐
│Advisory│ │Conseq. │ │Adaptive│
│Governce│ │Engine  │ │Ethics  │
└────────┘ └────────┘ └────────┘
```

## Module Layout

| Module | Responsibility |
|---|---|
| `core/` | Orchestrator, event bus, state manager, persistence |
| `agents/` | HeadAgent, WitnessAgent, Planner, Critic, Reasoner |
| `adapters/` | LLM providers (OpenAI, TTS, STT), caching |
| `schemas/` | Pydantic models — Task, Message, Plan, etc. |
| `tools/` | Built-in tools (file, HTTP, shell) + connectors (docs, DB, code runner) |
| `memory/` | InMemory and Postgres backends |
| `governance/` | SafetyPipeline, PolicyEngine, AdaptiveEthics, ConsequenceEngine |
| `reasoning/` | NativeReasoning, Metacognition, Interpretability |
| `world_model/` | CausalWorldModel with self-modification prediction |
| `verification/` | ClaimVerifier for output validation |
| `interfaces/` | Multi-modal adapters (visual, haptic, gesture, biometric) |
| `maa/` | Manufacturing Assurance Authority (geometry, physics, embodiment) |
| `api/` | FastAPI app, routes, middleware, metrics |

## Key Subsystems

### Consequence Engine (`governance/consequence_engine.py`)
Every decision is a choice with alternatives, risk/reward estimates, and actual outcomes. The system learns from surprise (difference between predicted and actual outcomes).

### Adaptive Ethics (`governance/adaptive_ethics.py`)
Consequentialist ethical framework that learns from experience rather than static rules. Lessons evolve weights based on observed outcomes. Advisory mode — observations, not enforcement.

### Causal World Model (`world_model/causal.py`)
Predicts action→effect relationships from execution history. Includes self-modification prediction — the system models how its own capabilities change from self-improvement actions.

### InsightBus (`governance/insight_bus.py`)
Cross-head shared learning channel. Heads contribute observations that other heads can learn from, enabling collaborative intelligence.

### PersistentLearningStore (`governance/persistent_store.py`)
File-backed persistence for consequence data, ethical lessons, and risk histories across restarts.

### Metacognition (`reasoning/metacognition.py`)
Self-awareness of knowledge boundaries. Evaluates reasoning quality, evidence sufficiency, and recommends when to seek more information.

### Plugin System (`agents/head_registry.py`)
Extensible head registry with decorator-based registration. Custom heads can contribute to ethics and consequences via hooks.

## API Architecture

- **FastAPI** with async support and lifespan management
- **Bearer token auth** (optional, via `FUSIONAGI_API_KEY`)
- **Advisory rate limiting** (logs, doesn't block)
- **Version negotiation** via `Accept-Version` header
- **SSE streaming** for token-by-token responses
- **WebSocket** for real-time bidirectional communication
- **Multi-tenant** isolation via `X-Tenant-ID` header
- **Prometheus metrics** at `/metrics` (when enabled)

## Governance Philosophy

All governance is **advisory by default** (`GovernanceMode.ADVISORY`). The system observes, logs, and advises — but does not prevent action. Mistakes are learning opportunities. Every decision, its alternatives, and its consequences are tracked for the ethical learning loop.