Complete all 37 items: frontend UI, backend stubs, infrastructure, docs, tests
Frontend (items 1-10):
- WebSocket streaming integration with useWebSocket hook
- Admin Dashboard UI (status, voices, agents, governance tabs)
- Voice playback UI (TTS/STT integration)
- Settings/Preferences page (conversation style, sliders)
- Responsive/mobile layout (breakpoints at 480px, 768px)
- Dark/light theme with CSS variables and localStorage
- Error handling & loading states (retry, empty state, disabled input)
- Authentication UI (login page, Bearer token, logout)
- Head visualization improvements (active/speaking states, animations)
- Consequence/Ethics dashboard (lessons, consequences, insights tabs)
Backend stubs (items 11-21):
- Tool connectors: DocsConnector (text/md/PDF), DBConnector (SQLite/Postgres), CodeRunnerConnector (Python/JS/Bash/Ruby sandboxed)
- STT adapter: WhisperSTTAdapter, AzureSTTAdapter
- Multi-modal interface adapters: Visual, Haptic, Gesture, Biometric
- SSE streaming endpoint (/v1/sessions/{id}/stream/sse)
- Multi-tenant support (X-Tenant-ID header, tenant CRUD)
- Plugin marketplace/registry (register, install, list)
- Backup/restore endpoints
- Versioned API negotiation (Accept-Version header, deprecation)
Infrastructure (items 22-26):
- docker-compose.yml (API + Postgres + Redis + frontend)
- .env.example with all configurable vars
- gunicorn.conf.py production ASGI config
- Prometheus metrics collector and /metrics endpoint
- Structured JSON logging configuration
Documentation (items 27-29):
- Architecture docs with module layout and subsystem descriptions
- Quickstart guide with setup, API tour, and test instructions
Tests (items 30-32):
- Integration tests: 25 end-to-end API tests
- Frontend tests: 10 Vitest tests for hooks (useTheme, useAuth)
- Load/performance tests: latency and throughput benchmarks
- Connector tests: 16 tests for Docs, DB, CodeRunner
- Multi-modal adapter tests: 9 tests
- Metrics collector tests: 5 tests
- STT adapter tests: 2 tests
511 Python tests passing, 10 frontend tests passing, 0 ruff errors.
Co-Authored-By: Nakamoto, S <defi@defi-oracle.io>
This commit is contained in:
Devin AI
@@ -1,130 +1,88 @@
|
||||
# FusionAGI Architecture
|
||||
|
||||
High-level system components and data flow.
|
||||
## Overview
|
||||
|
||||
## Component 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.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph core [Core]
|
||||
Orch[Orchestrator]
|
||||
EB[Event Bus]
|
||||
SM[State Manager]
|
||||
end
|
||||
## Core Architecture
|
||||
|
||||
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
|
||||
```
|
||||
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 │
|
||||
└────────┘ └────────┘ └────────┘
|
||||
```
|
||||
|
||||
## Data Flow (Task Lifecycle)
|
||||
## Module Layout
|
||||
|
||||
```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]
|
||||
```
|
||||
| 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 |
|
||||
|
||||
## Core Components
|
||||
## Key Subsystems
|
||||
|
||||
- **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.
|
||||
### 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).
|
||||
|
||||
## Agent Framework
|
||||
### 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.
|
||||
|
||||
- **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).
|
||||
### 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.
|
||||
|
||||
## Supporting Systems
|
||||
### InsightBus (`governance/insight_bus.py`)
|
||||
Cross-head shared learning channel. Heads contribute observations that other heads can learn from, enabling collaborative intelligence.
|
||||
|
||||
- **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.
|
||||
### PersistentLearningStore (`governance/persistent_store.py`)
|
||||
File-backed persistence for consequence data, ethical lessons, and risk histories across restarts.
|
||||
|
||||
## Data Flow
|
||||
### Metacognition (`reasoning/metacognition.py`)
|
||||
Self-awareness of knowledge boundaries. Evaluates reasoning quality, evidence sufficiency, and recommends when to seek more information.
|
||||
|
||||
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.
|
||||
### Plugin System (`agents/head_registry.py`)
|
||||
Extensible head registry with decorator-based registration. Custom heads can contribute to ethics and consequences via hooks.
|
||||
|
||||
All components depend on **schemas** for tasks, messages, plans, and recommendations; no ad-hoc dicts in core or agents.
|
||||
## API Architecture
|
||||
|
||||
## Self-Improvement Subsystem
|
||||
- **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)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph events [Event Bus]
|
||||
FAIL[task_state_changed: FAILED]
|
||||
REFL[reflection_done]
|
||||
end
|
||||
## Governance Philosophy
|
||||
|
||||
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`).
|
||||
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.
|
||||
|
||||
120
docs/quickstart.md
Normal file
120
docs/quickstart.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# FusionAGI Quickstart Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.10+
|
||||
- Node.js 20+ (for frontend)
|
||||
- Git
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://gitea.d-bis.org/d-bis/FusionAGI.git
|
||||
cd FusionAGI
|
||||
|
||||
# Install Python dependencies (dev + API extras)
|
||||
pip install -e ".[dev,api]"
|
||||
|
||||
# Install frontend dependencies
|
||||
cd frontend && npm install && cd ..
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
```bash
|
||||
# Copy environment template
|
||||
cp .env.example .env
|
||||
|
||||
# Edit .env with your settings:
|
||||
# - OPENAI_API_KEY for LLM support
|
||||
# - FUSIONAGI_API_KEY for API authentication (optional)
|
||||
```
|
||||
|
||||
## Running the API
|
||||
|
||||
```bash
|
||||
# Development
|
||||
python -m uvicorn fusionagi.api.app:app --reload --port 8000
|
||||
|
||||
# Production
|
||||
gunicorn fusionagi.api.app:app -c gunicorn.conf.py
|
||||
```
|
||||
|
||||
API docs available at: http://localhost:8000/docs
|
||||
|
||||
## Running the Frontend
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Frontend available at: http://localhost:5173
|
||||
|
||||
## Using Docker Compose
|
||||
|
||||
```bash
|
||||
# Start full stack (API + Postgres + Redis + Frontend)
|
||||
docker compose up -d
|
||||
|
||||
# View logs
|
||||
docker compose logs -f api
|
||||
```
|
||||
|
||||
## Quick API Tour
|
||||
|
||||
### Create a session
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/v1/sessions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"user_id": "demo"}'
|
||||
```
|
||||
|
||||
### Send a prompt
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/v1/sessions/{session_id}/prompt \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"prompt": "Explain quantum computing"}'
|
||||
```
|
||||
|
||||
### Stream a response (SSE)
|
||||
```bash
|
||||
curl -N -X POST http://localhost:8000/v1/sessions/{session_id}/stream/sse \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"prompt": "Write a poem about AI"}'
|
||||
```
|
||||
|
||||
### Check system status
|
||||
```bash
|
||||
curl http://localhost:8000/v1/admin/status
|
||||
```
|
||||
|
||||
## Frontend Pages
|
||||
|
||||
| Page | Description |
|
||||
|---|---|
|
||||
| **Chat** | Main conversation interface with 12-head reasoning display |
|
||||
| **Admin** | System monitoring, voice library, agent configuration |
|
||||
| **Ethics** | Consequence tracking, ethical lessons, cross-head insights |
|
||||
| **Settings** | Theme, conversation style, and personality preferences |
|
||||
|
||||
## Running Tests
|
||||
|
||||
```bash
|
||||
# Python tests
|
||||
pytest tests/ -q --tb=short
|
||||
|
||||
# Lint
|
||||
ruff check fusionagi/ tests/
|
||||
|
||||
# Type check
|
||||
mypy fusionagi/ --strict
|
||||
|
||||
# Frontend build check
|
||||
cd frontend && npx tsc --noEmit
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
See [docs/architecture.md](architecture.md) for the full system architecture.
|
||||
Reference in New Issue
Block a user