338 lines
13 KiB
Markdown
338 lines
13 KiB
Markdown
# FusionAGI
|
||
|
||
The world's most advanced **agentic AGI system**—Artificial General Intelligence, not narrow AI. A modular, composable intelligence framework that supports reasoning, planning, execution, memory, and tool use through coordinated agents, with built-in **self-improvement**, **self-correction**, **auto-recommend/suggest**, and **auto-training**.
|
||
|
||
## System at a Glance
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph users [Users & Clients]
|
||
UI[Multi-Modal UI]
|
||
API_Client[API / Cursor Composer]
|
||
end
|
||
|
||
subgraph fusion [FusionAGI]
|
||
subgraph interfaces [Interfaces]
|
||
Admin[Admin Control Panel]
|
||
API[FastAPI / Dvādaśa API]
|
||
end
|
||
subgraph core [Core]
|
||
Orch[Orchestrator]
|
||
EB[Event Bus]
|
||
SM[State Manager]
|
||
end
|
||
subgraph agents [Agents]
|
||
P[Planner]
|
||
R[Reasoner]
|
||
E[Executor]
|
||
C[Critic]
|
||
H[12 Heads + Witness]
|
||
end
|
||
subgraph support [Support]
|
||
Mem[Memory]
|
||
Tools[Tools]
|
||
Gov[Governance]
|
||
SI[Self-Improvement]
|
||
end
|
||
end
|
||
|
||
UI --> Admin
|
||
UI --> API
|
||
API_Client --> API
|
||
Admin --> Orch
|
||
API --> Orch
|
||
Orch --> EB
|
||
Orch --> SM
|
||
Orch --> P
|
||
Orch --> R
|
||
Orch --> E
|
||
Orch --> C
|
||
Orch --> H
|
||
P --> Mem
|
||
E --> Tools
|
||
E --> Gov
|
||
C --> SI
|
||
```
|
||
|
||
## Features
|
||
|
||
- **AGI-first:** General intelligence across domains via composable agents, not single-task AI.
|
||
- **Native reasoning:** When no LLM adapter is configured, FusionAGI runs with built-in symbolic reasoning—no external API calls. Heads use pattern analysis, domain logic, and persona-driven synthesis.
|
||
- **Self-improvement:** Learns from outcomes; reflection and heuristic updates improve behavior over time.
|
||
- **Self-correction:** Detects failures, runs critique loops, validates outputs, and retries with feedback.
|
||
- **Auto recommend / suggest:** Produces actionable recommendations (next actions, training targets, tool additions) from lessons and evaluations.
|
||
- **Auto training:** Suggests and applies heuristic updates, prompt refinements, and training targets from execution traces and reflection.
|
||
- **Modularity:** Reasoning, planning, memory, tooling, and governance are independent, replaceable modules.
|
||
- **Agent-oriented:** Agents have roles, goals, and constraints; they communicate via structured messages.
|
||
- **Model-agnostic:** LLMs are abstracted behind adapters (OpenAI, Anthropic, local).
|
||
- **Determinism:** Explicit state transitions, logged decisions, and replayable execution traces.
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
pip install -e .
|
||
# With LLM adapters (optional; MAA and core are built-in):
|
||
pip install -e ".[openai]" # OpenAIAdapter
|
||
pip install -e ".[anthropic]"
|
||
pip install -e ".[local]"
|
||
pip install -e ".[all]" # openai + anthropic + local
|
||
pip install -e ".[dev]" # pytest
|
||
```
|
||
|
||
- **MAA** (Manufacturing Authority Add-On) is built-in; no extra dependency.
|
||
- **Optional extras:** `openai`, `anthropic`, `local` are for LLM providers; `dev` is for tests (`pytest`).
|
||
- **OpenAIAdapter** requires `fusionagi[openai]`; use `from fusionagi.adapters import OpenAIAdapter` (or `from fusionagi.adapters.openai_adapter import OpenAIAdapter` if the optional import is not used).
|
||
- **CachedAdapter** wraps any `LLMAdapter` and caches `complete()` responses; no extra dependency. Use `from fusionagi.adapters import CachedAdapter` (or `from fusionagi.adapters.cache import CachedAdapter`).
|
||
|
||
## Project Layout
|
||
|
||
```
|
||
fusionagi/
|
||
├── core/ # Orchestrator, event bus, state manager, persistence, run_dvadasa
|
||
├── agents/ # Planner, Reasoner, Executor, Critic, heads, Witness
|
||
├── reasoning/ # Chain-of-thought and tree-of-thought
|
||
├── planning/ # Plan graph, dependency resolution, strategies
|
||
├── memory/ # Working, episodic, reflective, semantic, procedural, trust, consolidation
|
||
├── tools/ # Tool registry, safe runner, builtins, connectors
|
||
├── governance/ # Guardrails, rate limiting, access control, SafetyPipeline, PolicyEngine
|
||
├── reflection/ # Post-task reflection and heuristic updates
|
||
├── self_improvement/ # Self-correction, auto-recommend/suggest, auto-training, FusionAGILoop
|
||
├── interfaces/ # Admin panel, multi-modal UI, voice, conversation
|
||
├── adapters/ # LLM adapters (OpenAI, stub, cache, native)
|
||
├── schemas/ # Task, message, plan, recommendation, head, witness schemas
|
||
├── api/ # FastAPI app, Dvādaśa routes, OpenAI bridge, WebSocket
|
||
├── maa/ # Manufacturing Authority Add-On (gate, MPC, gap detection)
|
||
├── multi_agent/ # Pool, delegation, supervisor, consensus
|
||
├── config/ # Head personas and voices
|
||
├── prompts/ # Head prompts
|
||
├── skills/ # Skill library, induction, versioning
|
||
├── telemetry/ # Tracer and event subscription
|
||
├── verification/ # Outcome verifier, contradiction detector, validators
|
||
├── world_model/ # World model and rollout
|
||
├── tests/
|
||
└── docs/
|
||
```
|
||
|
||
## Usage
|
||
|
||
```python
|
||
from fusionagi import Orchestrator, EventBus, StateManager
|
||
from fusionagi.agents import PlannerAgent
|
||
|
||
bus = EventBus()
|
||
state = StateManager()
|
||
orch = Orchestrator(event_bus=bus, state_manager=state)
|
||
planner_agent = PlannerAgent()
|
||
orch.register_agent("planner", planner_agent)
|
||
task_id = orch.submit_task(goal="Summarize the project README")
|
||
```
|
||
|
||
With self-improvement (FusionAGILoop): self-correction, auto-recommend, auto-training:
|
||
|
||
```python
|
||
from fusionagi import Orchestrator, EventBus, StateManager, FusionAGILoop
|
||
from fusionagi.memory import ReflectiveMemory
|
||
from fusionagi.agents import CriticAgent
|
||
|
||
bus = EventBus()
|
||
state = StateManager()
|
||
orch = Orchestrator(event_bus=bus, state_manager=state)
|
||
reflective = ReflectiveMemory()
|
||
critic = CriticAgent(identity="critic")
|
||
orch.register_agent("critic", critic)
|
||
|
||
agi_loop = FusionAGILoop(
|
||
event_bus=bus,
|
||
state_manager=state,
|
||
orchestrator=orch,
|
||
critic_agent=critic,
|
||
reflective_memory=reflective,
|
||
auto_retry_on_failure=False,
|
||
on_recommendations=lambda recs: print("Recommendations:", len(recs)),
|
||
on_training_suggestions=lambda sugs: print("Training suggestions:", len(sugs)),
|
||
)
|
||
# On task_state_changed(FAILED) and reflection_done, AGI loop runs correction, recommend, and training.
|
||
```
|
||
|
||
With native reasoning (default when no adapter):
|
||
|
||
```python
|
||
from fusionagi import Orchestrator, EventBus, StateManager
|
||
from fusionagi.agents import WitnessAgent
|
||
from fusionagi.agents.heads import create_all_content_heads
|
||
from fusionagi.core import run_dvadasa
|
||
from fusionagi.schemas.head import HeadId
|
||
|
||
bus = EventBus()
|
||
state = StateManager()
|
||
orch = Orchestrator(event_bus=bus, state_manager=state)
|
||
# adapter=None uses NativeReasoningProvider + NativeAdapter—no external LLM
|
||
heads = create_all_content_heads(adapter=None)
|
||
for hid, agent in heads.items():
|
||
orch.register_agent(hid.value, agent)
|
||
orch.register_agent(HeadId.WITNESS.value, WitnessAgent(adapter=None))
|
||
task_id = orch.submit_task(goal="Analyze security tradeoffs")
|
||
final = run_dvadasa(orch, task_id, "Analyze security tradeoffs", event_bus=bus)
|
||
```
|
||
|
||
With an LLM adapter (optional):
|
||
|
||
```python
|
||
from fusionagi.adapters import StubAdapter, CachedAdapter
|
||
# OpenAIAdapter requires: pip install "fusionagi[openai]"
|
||
# from fusionagi.adapters import OpenAIAdapter
|
||
adapter = CachedAdapter(StubAdapter("response"), max_entries=100)
|
||
```
|
||
|
||
With admin control panel and multi-modal UI:
|
||
|
||
```python
|
||
from fusionagi.interfaces import AdminControlPanel, MultiModalUI
|
||
from fusionagi.interfaces import VoiceInterface, VoiceLibrary, ConversationManager
|
||
|
||
# Admin panel for system management
|
||
admin = AdminControlPanel(
|
||
orchestrator=orch,
|
||
event_bus=bus,
|
||
state_manager=state,
|
||
)
|
||
|
||
# Add voice profiles
|
||
from fusionagi.interfaces.voice import VoiceProfile
|
||
voice = VoiceProfile(name="Assistant", language="en-US", style="friendly")
|
||
admin.add_voice_profile(voice)
|
||
|
||
# Multi-modal user interface
|
||
voice_interface = VoiceInterface(stt_provider="whisper", tts_provider="elevenlabs")
|
||
ui = MultiModalUI(
|
||
orchestrator=orch,
|
||
conversation_manager=ConversationManager(),
|
||
voice_interface=voice_interface,
|
||
)
|
||
|
||
# Create user session with text and voice
|
||
from fusionagi.interfaces.base import ModalityType
|
||
session_id = ui.create_session(
|
||
preferred_modalities=[ModalityType.TEXT, ModalityType.VOICE]
|
||
)
|
||
|
||
# Interactive task submission with real-time feedback
|
||
task_id = await ui.submit_task_interactive(session_id, goal="Analyze data")
|
||
```
|
||
|
||
## Interfaces
|
||
|
||
FusionAGI provides comprehensive interface layers:
|
||
|
||
### Admin Control Panel
|
||
- Voice library management (TTS/STT configuration)
|
||
- Conversation style tuning (personality, formality, verbosity)
|
||
- Agent configuration and monitoring
|
||
- System health and performance metrics
|
||
- Governance policies and audit logs
|
||
- Manufacturing authority (MAA) oversight
|
||
|
||
### Multi-Modal User Interface
|
||
Supports multiple sensory modalities:
|
||
- **Text**: Chat, commands, structured input
|
||
- **Voice**: Speech-to-text, text-to-speech
|
||
- **Visual**: Images, video, AR/VR (extensible)
|
||
- **Haptic**: Touch feedback (extensible)
|
||
- **Gesture**: Motion control (extensible)
|
||
- **Biometric**: Emotion detection (extensible)
|
||
|
||
See `docs/interfaces.md` and `examples/` for detailed usage.
|
||
|
||
**Task lifecycle (high-level):**
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as User/API
|
||
participant O as Orchestrator
|
||
participant P as Planner
|
||
participant E as Executor
|
||
participant C as Critic
|
||
|
||
U->>O: submit_task(goal)
|
||
O->>P: plan
|
||
P->>O: plan graph
|
||
O->>E: execute_step (×N)
|
||
E->>O: results
|
||
O->>C: evaluate
|
||
C->>O: reflection_done
|
||
O->>U: task complete / recommendations
|
||
```
|
||
|
||
### Dvādaśa 12-Head Mode
|
||
|
||
Multi-agent orchestration with 12 specialized heads (Logic, Research, Strategy, Security, etc.) and a Witness meta-controller for consensus and transparency:
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph heads [12 Content Heads]
|
||
H1[Logic]
|
||
H2[Research]
|
||
H3[Strategy]
|
||
H4[Security]
|
||
H5[Safety]
|
||
H6[+ 7 more]
|
||
end
|
||
subgraph witness [Witness]
|
||
W[Witness]
|
||
end
|
||
heads --> W
|
||
W --> Answer[final_answer]
|
||
```
|
||
|
||
```bash
|
||
pip install -e ".[api]" # For REST + WebSocket API
|
||
```
|
||
|
||
```python
|
||
from fusionagi import Orchestrator, EventBus, StateManager
|
||
from fusionagi.agents import WitnessAgent
|
||
from fusionagi.agents.heads import create_all_content_heads
|
||
from fusionagi.core import run_dvadasa
|
||
from fusionagi.adapters import StubAdapter # or OpenAIAdapter
|
||
|
||
bus = EventBus()
|
||
state = StateManager()
|
||
orch = Orchestrator(event_bus=bus, state_manager=state)
|
||
heads = create_all_content_heads(adapter=StubAdapter())
|
||
for hid, agent in heads.items():
|
||
orch.register_agent(hid.value, agent)
|
||
orch.register_agent("witness", WitnessAgent(adapter=StubAdapter()))
|
||
|
||
task_id = orch.submit_task(goal="Analyze architecture tradeoffs")
|
||
final = run_dvadasa(orch, task_id, "What are the tradeoffs?", event_bus=bus)
|
||
print(final.final_answer)
|
||
```
|
||
|
||
Run the API: `uvicorn fusionagi.api.app:app --reload` and open the frontend: `cd frontend && pnpm dev`.
|
||
|
||
**API port:** By default the frontend proxies `/v1` to `http://localhost:8000`. If your API runs on another port (e.g. 8002), set `VITE_API_URL=http://localhost:8002` in `frontend/.env` and restart the dev server. See `frontend/.env.example`.
|
||
|
||
### OpenAI Bridge (Cursor Composer)
|
||
|
||
Use FusionAGI as a custom model in Cursor Composer and other OpenAI API consumers. The API exposes `GET /v1/models` and `POST /v1/chat/completions` in OpenAI format. See `docs/openai_bridge.md` for setup and configuration.
|
||
|
||
## Development
|
||
|
||
- **Frontend** uses [pnpm](https://pnpm.io/) as the package manager. From the project root: `pnpm dev` or `cd frontend && pnpm dev`.
|
||
- **Documentation:** See **[docs/README.md](docs/README.md)** for a documentation map and quick reference. Key docs:
|
||
- `docs/architecture.md` — high-level components, data flow, self-improvement (with Mermaid diagrams)
|
||
- `docs/interfaces.md` — Admin Control Panel and Multi-Modal UI
|
||
- `docs/openai_bridge.md` — OpenAI-compatible API for Cursor Composer
|
||
- `docs/api_middleware_interface_spec.md` — Dvādaśa API, SafetyPipeline, interface layer spec
|
||
- `docs/multi_agent_acceleration.md` — parallel execution, pool, delegation, supervisor
|
||
- `docs/maa_activation.md` and `docs/maa_compliance_mapping.md` — Manufacturing Authority Add-On
|
||
- `docs/ui_ux_implementation.md` — interface implementation summary
|
||
- `docs/interface_architecture_diagram.md` — system and data flow diagrams (ASCII + Mermaid)
|
||
- Use `.cursor/rules` for coding standards.
|
||
- Run tests: `pytest tests/`
|
||
- Examples: `python examples/admin_panel_example.py`
|
||
|
||
## License
|
||
|
||
MIT
|