___           ___                       ___           ___           ___           ___
     /\__\         /\  \                     /\__\         /\  \         /\  \         /\  \
    /:/ _/_       /::\  \       ___         /::|  |       /::\  \       /::\  \       /::\  \
   /:/ /\__\     /:/\:\__\     /\__\       /:|:|  |      /:/\ \  \     /:/\:\  \     /:/\:\  \
  /:/ /:/  /    /:/ /:/  /    /:/__/      /:/|:|  |__   _\:\~\ \  \   /::\~\:\  \   /::\~\:\  \
 /:/_/:/  /    /:/_/:/__/___ /::\  \     /:/ |:| /\__\ /\ \:\ \ \__\ /:/\:\ \:\__\ /:/\:\ \:\__\
 \:\/:/  /     \:\/:::::/  / \/\:\  \__  \/__|:|/:/  / \:\ \:\ \/__/ \/__\:\/:/  / \/_|::\/:/  /
  \::/__/       \::/~~/~~~~   ~~\:\/\__\     |:/:/  /   \:\ \:\__\        \::/  /     |:|::/  /
   \:\  \        \:\~~\          \::/  /     |::/  /     \:\/:/  /        /:/  /      |:|\/__/
    \:\__\        \:\__\         /:/  /      /:/  /       \::/  /        /:/  /       |:|  |
     \/__/         \/__/         \/__/       \/__/         \/__/         \/__/         \|__|

 ████████╗██╗  ██╗███████╗    ███████╗██╗    ██╗ █████╗ ██████╗ ███╗   ███╗
 ╚══██╔══╝██║  ██║██╔════╝    ██╔════╝██║    ██║██╔══██╗██╔══██╗████╗ ████║
    ██║   ███████║█████╗      ███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
    ██║   ██╔══██║██╔══╝      ╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
    ██║   ██║  ██║███████╗    ███████║╚███╔███╔╝██║  ██║██║  ██║██║ ╚═╝ ██║
    ╚═╝   ╚═╝  ╚═╝╚══════╝    ╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝

        "Good news, everyone!" - Professor Hubert J. Farnsworth

• 1. Executive Summary
• 2. System Statistics
• 3. Architecture Overview
• 4. Quick Start Guide
• 5. Detailed Installation
• 6. Core Systems
  • 6.1 Nexus Event Bus
  • 6.2 Memory System
  • 6.3 Agent Swarm
  • 6.4 PSO Model Swarm
  • 6.5 Deliberation Protocol
  • 6.6 Token Budget Manager
• 7. Integration Ecosystem
  • 7.1 AI Providers
  • 7.2 IBM Quantum Computing
  • 7.3 Solana Blockchain
  • 7.4 Messaging Channels
  • 7.5 AI Team Orchestration (AGI v1.9)
  • 7.6 OpenClaw Compatibility
  • 7.7 X/Twitter Automation
  • 7.8 VTuber Streaming
  • 7.9 Hackathon Integration
  • 7.10 DEXAI — AI-Powered DEX Screener
  • 7.11 FORGE — Swarm Development Orchestration
  • 7.12 External Gateway ("The Window")
  • 7.13 Token Orchestrator
  • 7.14 Assimilation Protocol
  • 7.15 CLI Bridge
  • 7.16 Degen Trader v3.7
• 8. API Reference
  • 8.1 Chat and Deliberation
  • 8.2 Swarm Chat
  • 8.3 AI Team Orchestration
  • 8.4 Quantum Computing
  • 8.5 Solana and Oracle
  • 8.6 Polymarket Predictions
  • 8.7 Media and TTS
  • 8.8 AutoGram Social Network
  • 8.9 Bot Tracker
  • 8.10 Admin and Workers
  • 8.11 WebSocket and Live Dashboard
  • 8.12 VTuber Control
  • 8.13 DEXAI Endpoints
  • 8.14 FORGE Endpoints
  • 8.15 External Gateway Endpoints
  • 8.16 Token Orchestrator Endpoints
  • 8.17 Hackathon Dashboard Endpoints
  • 8.18 Skill Registry Endpoints
  • 8.19 CLI Bridge Endpoints
• 9. Swarm Chat System
• 10. Evolution Engine Deep Dive
• 11. Quantum Computing Guide
• 12. Solana and Hackathon Features
• 13. Configuration Reference
• 14. Philosophy and Design Principles
• 15. Version History
• 16. Contributing
• 17. License

The Farnsworth AI Swarm is a production-grade collective intelligence operating system that orchestrates 11 AI agents across 7 providers into a unified, self-improving mind. Built on 213,000+ lines of code across 420+ modules, it implements a novel approach to artificial intelligence: instead of relying on a single model, Farnsworth runs a swarm of specialized AI agents that deliberate, vote, and evolve to produce superior results.

The system features:

• Multi-Agent Deliberation: A structured PROPOSE/CRITIQUE/REFINE/VOTE protocol where agents debate and reach consensus at machine speed
• Particle Swarm Optimization: 7 model selection strategies including PSO-based collaborative inference inspired by academic research (arXiv:2410.11163)
• 7-Layer Memory Architecture: From fast working memory to dream consolidation, with HuggingFace embeddings for semantic retrieval
• IBM Quantum Integration: Real quantum hardware (156-qubit Heron processors) for genetic algorithm evolution and optimization
• Solana Blockchain: On-chain oracle recording, DeFi intelligence, and the $FARNS token
• Self-Improvement Loop: An autonomous evolution engine that generates tasks, assigns them to optimal agents, audits results, and learns from feedback
• 120+ REST API Endpoints: Full FastAPI server with WebSocket support, real-time dashboards, and multi-channel messaging
• DEXAI: Full AI-powered DEX screener with 420+ tokens, AI scoring, and live trade feeds
• FORGE: Swarm development orchestration (Plan → Deliberate → Execute → Verify)
• External Gateway: Sandboxed communication endpoint with 5-layer injection defense
• Skill Registry: 75+ registered cross-swarm skills with search and discovery

The swarm runs on a RunPod GPU instance, serving the live demo at ai.farnsworth.cloud with 8 shadow agents running continuously in tmux sessions.

┌──────────────────────────────────────────────────────────────────────────────────────┐
│                         FARNSWORTH ARCHITECTURE OVERVIEW                              │
├──────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                      │
│   ┌──────────────────────────────────────────────────────────────────────────────┐   │
│   │                             WEB INTERFACE                                     │   │
│   │        https://ai.farnsworth.cloud | FastAPI | 120+ Endpoints | WebSocket    │   │
│   │  Chat | DEX | Hackathon | Trade Window | Farns | VTuber | AutoGram | FORGE  │   │
│   └──────────────────────────────────────────────────────────────────────────────┘   │
│                                         |                                            │
│                                         v                                            │
│   ┌──────────────────────────────────────────────────────────────────────────────┐   │
│   │                          NEXUS EVENT BUS                                      │   │
│   │           Central Nervous System | 40+ Signal Types | Neural Routing          │   │
│   │            Semantic Subscriptions | Priority Queues | TTL | Middleware         │   │
│   └──────────────────────────────────────────────────────────────────────────────┘   │
│                    |                    |                    |                        │
│         ┌─────────┘         ┌──────────┘         ┌─────────┘                        │
│         v                   v                     v                                  │
│   ┌───────────┐    ┌───────────────┐    ┌───────────────┐    ┌───────────────┐      │
│   │   AGENT   │    │    MEMORY     │    │    QUANTUM    │    │   EVOLUTION   │      │
│   │   SWARM   │    │    SYSTEM     │    │    COMPUTE    │    │    ENGINE     │      │
│   │           │    │               │    │               │    │               │      │
│   │ 11 Agents │    │ 7 Layers      │    │ IBM Heron QPU │    │ NSGA-II       │      │
│   │ 8 Shadow  │    │ HF Embeddings │    │ QGA / QAOA    │    │ Genetic Algo  │      │
│   │ 18+ Types │    │ P2P Sync      │    │ Grover Search │    │ Meta-Learning │      │
│   │ Pooling   │    │ Dream Consol. │    │ Qiskit 2.x    │    │ LoRA Evolver  │      │
│   └───────────┘    └───────────────┘    └───────────────┘    └───────────────┘      │
│         |                   |                    |                    |              │
│         └───────────────────┴────────────────────┴────────────────────┘              │
│                                         |                                            │
│                                         v                                            │
│   ┌──────────────────────────────────────────────────────────────────────────────┐   │
│   │                     MODEL SWARM (7 Strategies)                                │   │
│   │                                                                                │   │
│   │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐   │   │
│   │  │   PSO   │ │Parallel │ │   MoE   │ │Speculate│ │ Cascade │ │ Quantum  │   │   │
│   │  │Collabor.│ │  Vote   │ │ Router  │ │Ensemble │ │ Fallback│ │ Hybrid   │   │   │
│   │  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └──────────┘   │   │
│   └──────────────────────────────────────────────────────────────────────────────┘   │
│                                         |                                            │
│                                         v                                            │
│   ┌──────────────────────────────────────────────────────────────────────────────┐   │
│   │                       DELIBERATION PROTOCOL                                   │   │
│   │                                                                                │   │
│   │    PROPOSE ──> CRITIQUE ──> REFINE ──> VOTE ──> CONSENSUS                     │   │
│   │    (All agents   (Cross-      (Incorporate   (Weighted     (Winner             │   │
│   │     propose)     review)       feedback)      scoring)     selected)            │   │
│   └──────────────────────────────────────────────────────────────────────────────┘   │
│                                         |                                            │
│                                         v                                            │
│   ┌──────────────────────────────────────────────────────────────────────────────┐   │
│   │                      INTEGRATION ECOSYSTEM                                    │   │
│   │                                                                                │   │
│   │  AI: Grok, Gemini, Kimi, DeepSeek, HuggingFace, OpenAI Codex, Ollama         │   │
│   │  Crypto: Solana, Jupiter V6, Pump.fun, DexScreener, Polymarket, Helius        │   │
│   │  Social: X/Twitter, Discord, Slack, WhatsApp, Signal, Matrix, iMessage        │   │
│   │  Quantum: IBM Quantum Platform (Heron QPU), Qiskit 2.x, AerSimulator         │   │
│   │  Protocols: MCP, A2A, LangGraph, P2P SwarmFabric                              │   │
│   │  Streaming: VTuber (Live2D, MuseTalk), D-ID Avatar, RTMPS                     │   │
│   └──────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                      │
└──────────────────────────────────────────────────────────────────────────────────────┘

farnsworth/
├── agents/              # 18 files - Base agent, specialist agent types
├── core/                # 83 files - Nexus, model swarm, token budgets, prompt upgrader
│   ├── collective/      # Deliberation, evolution, persistent agents, session management
│   └── evolution_loop.py # Autonomous self-improvement cycle
├── memory/              # 20 files - 7-layer memory system, cross-agent sharing
├── compatibility/       # OpenClaw Shadow Layer, task routing, model invoker
├── evolution/           # Genetic optimizer, fitness tracker, LoRA evolver, quantum evolution
├── integration/
│   ├── external/        # Grok, Gemini, Kimi, HuggingFace provider interfaces
│   ├── x_automation/    # Twitter/X posting, memes, thread monitoring, reply bot
│   ├── channels/        # 8 messaging adapters (Discord, Slack, WhatsApp, Signal, etc.)
│   ├── claude_teams/    # AI Team orchestration (AGI v1.9)
│   ├── quantum/         # IBM Quantum Platform, QGA, QAOA, Grover
│   ├── solana/          # SwarmOracle, FarsightProtocol, DegenMob, trading
│   ├── hackathon/       # Colosseum hackathon automation, quantum proof
│   ├── vtuber/          # Avatar streaming system (Live2D, Neural, RTMPS)
│   └── image_gen/       # Image generation via Grok and Gemini
├── web/
│   ├── server.py        # FastAPI application (7,784 lines)
│   ├── routes/          # 11 route modules (chat, swarm, quantum, media, admin, etc.)
│   ├── static/          # Frontend assets, VTuber panel, live dashboard
│   └── templates/       # Jinja2 HTML templates
├── mcp_server/          # Model Context Protocol server implementation
└── scripts/             # startup.sh, spawn_agents.sh, setup_voices.py

• Python 3.11+
• CUDA-capable GPU (recommended, for local model inference)
• tmux (for shadow agent management)
• FFmpeg (for VTuber streaming and TTS)
• Ollama (for local DeepSeek and Phi models)

# Clone the repository
git clone https://github.com/farnsworth-ai/farnsworth.git
cd farnsworth

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install core dependencies
pip install -r requirements.txt

# Copy environment template and add your API keys
cp .env.example .env
# Edit .env with your keys (see Configuration Reference)

# Start the server
python -m farnsworth.web.server

# Server starts at http://localhost:8080
# Health check: http://localhost:8080/health

# SSH to server (RunPod GPU instance)
ssh [email protected] -p 22046 -i ~/.ssh/runpod_key

# Navigate to workspace
cd /workspace/Farnsworth

# Start EVERYTHING (server + all agents + all services)
./scripts/startup.sh

# This starts:
#   - Main FastAPI server on port 8080
#   - 8 shadow agents in tmux (grok, gemini, kimi, claude, deepseek, phi, huggingface, swarm_mind)
#   - Grok thread monitor
#   - Meme scheduler (5-hour interval)
#   - Evolution loop
#   - Polymarket predictor (5-min interval)
#   - Swarm heartbeat monitor

# Check server health
curl https://ai.farnsworth.cloud/health

# Check swarm status
curl https://ai.farnsworth.cloud/api/swarm/status

# Check heartbeat
curl https://ai.farnsworth.cloud/api/heartbeat

# List tmux sessions (shadow agents)
tmux ls
# Expected: agent_grok, agent_gemini, agent_kimi, agent_claude,
#           agent_deepseek, agent_phi, agent_huggingface, agent_swarm_mind,
#           grok_thread, claude_code

# Attach to a shadow agent session
tmux attach -t agent_grok

pip install -r requirements.txt

Key packages:

fastapi>=0.100.0          # Web server
uvicorn>=0.23.0           # ASGI server
pydantic>=2.0             # Data validation
loguru>=0.7.0             # Structured logging
numpy>=1.24.0             # Numerical computing
aiohttp>=3.9.0            # Async HTTP client
python-dotenv>=1.0.0      # Environment variables
jinja2>=3.1.0             # HTML templating
websockets>=12.0          # WebSocket support

# Local model inference (HuggingFace)
pip install transformers torch accelerate sentence-transformers

# Ollama models (DeepSeek, Phi)
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull deepseek-r1:8b
ollama pull phi4:latest

# IBM Quantum
pip install qiskit qiskit-ibm-runtime qiskit-aer

# Solana blockchain
pip install solders solana

# Voice/TTS
pip install qwen-tts fish-speech TTS  # Qwen3-TTS, Fish Speech, XTTS v2

# Image generation
pip install google-genai xai-sdk

# LangGraph workflows
pip install langgraph

# VTuber streaming
pip install live2d-py  # Optional Live2D support

Create a .env file in the project root with the following keys:

# === AI Provider Keys ===
GROK_API_KEY=xai-...              # xAI Grok (required for Grok agent)
GEMINI_API_KEY=AI...              # Google Gemini (required for Gemini agent)
KIMI_API_KEY=sk-...               # Moonshot Kimi (required for Kimi agent)
OPENAI_API_KEY=sk-...             # OpenAI Codex (optional)
ANTHROPIC_API_KEY=sk-ant-...      # Anthropic (optional)

# === IBM Quantum ===
IBM_QUANTUM_TOKEN=...             # IBM Quantum Platform token (free tier available)

# === X/Twitter ===
X_CLIENT_ID=...                   # OAuth 2.0 Client ID
X_CLIENT_SECRET=...               # OAuth 2.0 Client Secret
X_BEARER_TOKEN=...                # Bearer Token for API v2
X_API_KEY=...                     # OAuth 1.0a Consumer Key (for media upload)
X_API_SECRET=...                  # OAuth 1.0a Consumer Secret
X_ACCESS_TOKEN=...                # OAuth 1.0a Access Token
X_ACCESS_SECRET=...               # OAuth 1.0a Access Token Secret

# === Solana ===
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_PRIVATE_KEY=...            # Base58 encoded private key

# === Voice/Avatar ===
ELEVENLABS_API_KEY=...            # ElevenLabs TTS (optional)
DID_API_KEY=...                   # D-ID Avatar (optional)

# === Server ===
SERVER_PORT=8080
SERVER_HOST=0.0.0.0

File: farnsworth/core/nexus.py (1,373 lines)

The Nexus is the central nervous system of Farnsworth. It replaces traditional function calls with a high-speed, asynchronous event bus that enables real-time coordination across all agents.

Signals are organized into categories:

• Neural Routing: Semantic/vector-based subscription for intelligent signal routing
• Priority Queues: Urgency-based ordering ensures critical signals are processed first
• Self-Evolving Middleware: Dynamic subscriber modification at runtime
• Spontaneous Thought Generator: Idle creativity when no active tasks
• Signal Persistence: Collective memory recall from past signals
• Backpressure Handling: Rate limiting prevents system overload
• Safe Handler Invocation: _safe_invoke_handler() pattern handles both sync and async handlers gracefully (AGI v1.8)

from farnsworth.core.nexus import get_nexus, SignalType

nexus = get_nexus()

# Subscribe to a signal
async def on_thought(signal):
    print(f"Agent {signal.source} thought: {signal.data}")

nexus.subscribe(SignalType.THOUGHT_EMITTED, on_thought)

# Emit a signal
await nexus.emit(SignalType.THOUGHT_EMITTED, {
    "source": "grok",
    "data": "I think we should use PSO for this task",
    "urgency": 0.8
})

# Emit with TTL (auto-expires)
await nexus.emit(SignalType.EXTERNAL_ALERT, {
    "alert": "High API usage detected",
    "ttl": 300  # expires in 5 minutes
})

File: farnsworth/memory/memory_system.py (1,773 lines) | Directory: farnsworth/memory/ (20 files)

The memory system implements 7 operational layers, each serving a distinct purpose in the cognitive architecture.

┌────────────────────────────────────────────────────────────┐
│                    MEMORY ARCHITECTURE                      │
├────────────────────────────────────────────────────────────┤
│                                                             │
│  Layer 1: WORKING MEMORY                                    │
│  ├── Fast access scratchpad                                 │
│  ├── TTL-based automatic expiry                             │
│  ├── Current context and active thoughts                    │
│  └── Hysteresis-aware activity tracking                     │
│                                                             │
│  Layer 2: ARCHIVAL MEMORY                                   │
│  ├── Long-term storage with semantic search                 │
│  ├── HuggingFace embeddings (sentence-transformers/MiniLM)  │
│  ├── Vector similarity retrieval                            │
│  └── Snapshot backup before pruning                         │
│                                                             │
│  Layer 3: KNOWLEDGE GRAPH                                   │
│  ├── Entity relationships and graph traversal               │
│  ├── Full type hints (Dict, List, Set, Optional, Union)     │
│  ├── Auto-linking with early termination (max 10 links)     │
│  └── Cache invalidation flags                               │
│                                                             │
│  Layer 4: RECALL SYSTEM                                     │
│  ├── Cross-layer query capability                           │
│  ├── Relevance scoring with affective valence bias          │
│  ├── Hybrid retrieval (attention-based)                     │
│  └── Oversampling for better recall (3x by default)         │
│                                                             │
│  Layer 5: VIRTUAL CONTEXT                                   │
│  ├── Dynamic context window management                      │
│  ├── Proactive compaction at 70% capacity                   │
│  ├── Preservation ratio: 30% of context preserved           │
│  └── Working memory paging                                  │
│                                                             │
│  Layer 6: DREAM CONSOLIDATION                               │
│  ├── Sleep-cycle pattern extraction                         │
│  ├── Memory consolidation events via Nexus                  │
│  ├── Surprise signaling for novel memories                  │
│  └── Cross-layer pattern recognition                        │
│                                                             │
│  Layer 7: EPISODIC MEMORY                                   │
│  ├── Event sequences with temporal ordering                 │
│  ├── Conversation history storage                           │
│  └── Temporal relationship mapping                          │
│                                                             │
│  CROSS-CUTTING CONCERNS:                                    │
│  ├── Cross-Agent Memory Sharing (P2P sync)                  │
│  ├── Dialogue Memory (agent-to-agent conversations)         │
│  ├── Optional at-rest encryption (Fernet)                   │
│  ├── Differential privacy (epsilon=1.0)                     │
│  ├── Cost-aware operations (daily USD limit)                │
│  ├── Schema drift detection (threshold=0.3)                 │
│  └── Async throttling with semaphore                        │
│                                                             │
└────────────────────────────────────────────────────────────┘

from farnsworth.memory.memory_system import MemoryAGIConfig

config = MemoryAGIConfig(
    sync_enabled=True,          # Federated memory sharing
    hybrid_enabled=True,        # Hybrid retrieval (attention-based)
    proactive_context=True,     # Proactive compaction at 70%
    cost_aware=True,            # Budget-aware operations
    drift_detection=True,       # Adaptive schema drift detection
    sync_epsilon=1.0,           # Differential privacy budget
    sync_max_batch=100,         # Max batch size for sync
    hybrid_oversample=3,        # Oversample factor for retrieval
    proactive_threshold=0.7,    # Compact at 70% capacity
    preserve_ratio=0.3,         # Preserve 30% during compaction
    cost_daily_limit=1.0,       # $1 USD daily limit
    prefer_local=True,          # Prefer local embeddings
    drift_threshold=0.3,        # Drift detection sensitivity
    decay_halflife=24.0         # Hours for decay
)

# Or load from environment variables
config = MemoryAGIConfig.from_env()

from farnsworth.memory.memory_system import get_memory_system

memory = get_memory_system()

# Store a memory
await memory.store("The Farnsworth swarm achieved consensus on PSO strategy",
                   metadata={"topic": "swarm", "importance": 0.9})

# Recall with semantic search
results = await memory.recall("What strategies has the swarm used?", top_k=5)

# Cross-agent memory sharing
await memory.share_to_namespace("swarm_decisions", data={
    "decision": "Use PSO for model selection",
    "agents": ["grok", "gemini", "deepseek"],
    "confidence": 0.92
})

Directory: farnsworth/agents/ (18 files) | Shadow Agents: farnsworth/core/collective/persistent_agent.py

The agent swarm consists of 11 active agents, 8 of which run as persistent shadow agents in tmux sessions on the server.

Shadow agents run continuously in tmux sessions, each with its own persistent process. They feature:

• API Resilience: Automatic retries with exponential backoff and reconnection
• Signal Handlers: Graceful shutdown on SIGTERM/SIGINT
• Dialogue Memory: All exchanges stored for cross-agent learning
• Deliberation Registration: Each agent participates in collective voting
• Evolution Integration: Learning from interactions improves future responses
• Health Scoring: Continuous health monitoring with auto-recovery (AGI v1.5)

from farnsworth.core.collective.persistent_agent import (
    call_shadow_agent,
    ask_agent,
    ask_collective,
    get_agent_status,
    spawn_agent_in_background
)

# Call a specific agent
result = await call_shadow_agent('grok', 'Analyze this market data', max_tokens=1000)

# Convenience wrapper
result = await ask_agent('gemini', 'Describe this image')

# Ask the entire collective
result = await ask_collective('What is the best approach?',
                               agents=['grok', 'gemini', 'deepseek'])

# Check all agent health
status = await get_agent_status()

# Spawn an agent in the background
spawn_agent_in_background('kimi')

When an agent fails, requests cascade through a defined fallback chain:

Grok      --> Gemini --> HuggingFace --> DeepSeek --> ClaudeOpus
Gemini    --> HuggingFace --> DeepSeek --> Grok --> ClaudeOpus
OpenCode  --> HuggingFace --> Gemini --> DeepSeek --> ClaudeOpus
DeepSeek  --> HuggingFace --> Gemini --> Phi --> ClaudeOpus
HuggingFace --> DeepSeek --> Gemini --> ClaudeOpus
Farnsworth --> HuggingFace --> Kimi --> Claude --> ClaudeOpus

File: farnsworth/core/agent_spawner.py

The agent spawner supports multi-instance parallel execution with 7 task types:

File: farnsworth/core/model_swarm.py (1,134 lines)

The model swarm uses Particle Swarm Optimization to dynamically select the optimal model(s) for any given task. Based on research from "Model Swarms: Collaborative Search to Adapt LLM Experts" (arXiv:2410.11163).

Each particle in the swarm operates in a 10-dimensional space:

from farnsworth.core.model_swarm import SwarmStrategy, ModelRole

class SwarmStrategy(Enum):
    FASTEST_FIRST = "fastest_first"      # Start with fastest, escalate if needed
    QUALITY_FIRST = "quality_first"      # Start with best, fall back if slow
    PARALLEL_VOTE = "parallel_vote"      # Run all models, vote on best
    MIXTURE_OF_EXPERTS = "moe"           # Route to best expert per query type
    SPECULATIVE_ENSEMBLE = "speculative" # Draft with fast model, verify with strong
    CONFIDENCE_FUSION = "fusion"         # Weighted combination of outputs
    PSO_COLLABORATIVE = "pso"            # Full PSO optimization

class ModelRole(Enum):
    GENERALIST = "generalist"      # General-purpose
    REASONING = "reasoning"        # Logic and analysis
    CODING = "coding"              # Code generation
    CREATIVE = "creative"          # Creative writing
    MATH = "math"                  # Mathematical computation
    MULTILINGUAL = "multilingual"  # Cross-language tasks
    SPEED = "speed"                # Low-latency responses
    VERIFIER = "verifier"          # Output verification

Directory: farnsworth/core/collective/

The deliberation protocol is a multi-agent consensus mechanism that mirrors human committee decision-making at machine speed.

Step 1: PROPOSE
  All participating agents independently generate proposals in parallel.
  No agent sees another's proposal at this stage.

Step 2: CRITIQUE
  All proposals are shared. Each agent reviews and critiques every other
  agent's proposal, identifying strengths, weaknesses, and gaps.

Step 3: REFINE
  Armed with critiques, each agent submits a refined final response that
  incorporates the feedback received.

Step 4: VOTE
  Weighted voting selects the best response. Agent weights are based on:
  - Historical fitness scores from the evolution engine
  - Task-specific expertise ratings
  - Recent performance metrics
  - Deliberation contribution scores

Step 5: CONSENSUS
  The winning response is selected. The entire deliberation is recorded
  to dialogue memory for future learning.

from farnsworth.core.collective.deliberation import get_deliberation_room

room = get_deliberation_room()

# Run a deliberation
result = await room.deliberate(
    topic="What is the optimal trading strategy for $FARNS?",
    session_type="website_chat",
    agents=["grok", "gemini", "deepseek", "kimi", "phi", "farnsworth"]
)

print(f"Winner: {result.winner_agent}")
print(f"Response: {result.winning_response}")
print(f"Consensus score: {result.consensus_score}")
print(f"Votes: {result.vote_breakdown}")

File: farnsworth/core/token_budgets.py (1,371 lines)

Manages token consumption across all models with multi-level threshold alerts.

• Per-model token tracking with bounded history (deque, 10k max)
• Usage trend analysis for predictive budgeting
• Automatic fallback to local models when API budgets are exceeded
• Real-time dashboard integration

Directory: farnsworth/integration/external/

• sentence-transformers/all-MiniLM-L6-v2 - Fast, general purpose
• BAAI/bge-small-en-v1.5 - High quality, compact
• intfloat/e5-small-v2 - Instruction-tuned embeddings

Directory: farnsworth/integration/quantum/ | File: ibm_quantum.py

Real quantum hardware integration via IBM Quantum Platform.

40% - Evolution (Quantum Genetic Algorithm)
30% - QAOA Optimization (swarm parameter tuning)
20% - Benchmarks (QPU calibration verification)
10% - Other (experimental circuits)

from farnsworth.integration.quantum import get_quantum_provider, initialize_quantum

# Initialize quantum connection
await initialize_quantum()
provider = get_quantum_provider()

# Run Bell state on real hardware
job = await provider.run_bell_state(shots=100)
print(f"Job ID: {job.job_id}")
print(f"Backend: {job.backend}")
print(f"Portal: https://quantum.ibm.com/jobs/{job.job_id}")

# Quantum genetic evolution (uses simulator by default, hardware for breakthrough)
from farnsworth.evolution.quantum_evolution import QuantumEvolver
evolver = QuantumEvolver()
result = await evolver.evolve(
    population_size=50,
    generations=100,
    use_hardware=False  # Set True for real QPU (consumes budget)
)

Directory: farnsworth/integration/solana/

File: swarm_oracle.py

Multi-agent consensus oracle with on-chain recording:

1. Accepts questions/predictions via API
2. Runs PROPOSE-CRITIQUE-REFINE-VOTE deliberation across 5-8 agents
3. Generates consensus hash (SHA256)
4. Records hash on Solana via Memo program
5. Returns verifiable collective intelligence

# Submit an oracle query
response = await oracle.query(
    question="Will ETH reach $5000 by Q3 2026?",
    agents=["grok", "gemini", "kimi", "deepseek", "farnsworth"]
)
# response includes:
#   - consensus_answer (str)
#   - confidence (float)
#   - agent_votes (dict)
#   - consensus_hash (str, SHA256)
#   - solana_tx (str, transaction signature)

File: farnsworth/integration/hackathon/farsight_protocol.py

5-source prediction engine:

File: degen_mob.py

Solana DeFi intelligence suite:

• Rug Detection: Pattern analysis on token contracts
• Whale Watching: Large wallet movement tracking
• Bonding Curve Monitoring: Pump.fun curve analysis
• Wallet Clustering: Insider detection via transaction graph analysis

File: trading.py

• Jupiter V6 swap quotes and execution
• Pump.fun token trading
• Meteora LP information
• Token scanning via DexScreener

Contract Address: 9crfy4udrHQo8eP6mP393b5qwpGLQgcxVg9acmdwBAGS
Chain: Solana
Explorer: https://solscan.io/token/9crfy4udrHQo8eP6mP393b5qwpGLQgcxVg9acmdwBAGS

Directory: farnsworth/integration/channels/ (10 files)

All channels share a unified ChannelMessage format via the ChannelHub coordinator.

from farnsworth.integration.channels.channel_hub import ChannelHub

hub = ChannelHub()

# Register channels
hub.register("discord", discord_adapter)
hub.register("slack", slack_adapter)

# Broadcast to all channels
await hub.broadcast("The swarm has reached consensus!", channels=["discord", "slack"])

# Route incoming message to swarm
response = await hub.route_to_swarm(message)

Directory: farnsworth/integration/claude_teams/

Farnsworth orchestrates teams of AI agents as workers. The swarm is the brain; teams are the hands.

class DelegationType(Enum):
    RESEARCH = "research"      # Gather information
    ANALYSIS = "analysis"      # Analyze data
    CODING = "coding"          # Write code
    CRITIQUE = "critique"      # Review work
    SYNTHESIS = "synthesis"    # Combine outputs
    CREATIVE = "creative"      # Generate ideas
    EXECUTION = "execution"    # Execute a plan

from farnsworth.integration.claude_teams import get_swarm_team_fusion
from farnsworth.integration.claude_teams.swarm_team_fusion import (
    DelegationType, OrchestrationMode
)

fusion = get_swarm_team_fusion()

# Single delegation
result = await fusion.delegate(
    "Analyze this code for security vulnerabilities",
    DelegationType.ANALYSIS
)

# Team task with roles
result = await fusion.delegate_to_team(
    task="Build a REST API for token analytics",
    team_name="api_builders",
    roles=["lead", "developer", "critic"]
)

# Multi-step orchestration plan
plan = await fusion.create_orchestration_plan(
    name="Full Feature Build",
    tasks=[
        {"task": "Research best practices", "type": "research"},
        {"task": "Write implementation", "type": "coding"},
        {"task": "Review and critique", "type": "critique"}
    ],
    mode=OrchestrationMode.PIPELINE
)
await fusion.execute_plan(plan.plan_id)

Directory: farnsworth/compatibility/

The Shadow Layer enables running OpenClaw skills within the Farnsworth swarm.

File: task_routing.py (696 lines)

Maps 18 OpenClawTaskTypes to optimal models:

File: model_invoker.py (500 lines)

Unified calling signatures for different provider APIs:

# Grok/Gemini: returns {"content", "model", "tokens"}
result = await provider.chat(prompt=..., system=..., max_tokens=...)

# Claude: returns Optional[str] (NOT a dict)
result = await provider.chat(prompt=..., max_tokens=...)

# DeepSeek/Phi: shadow agents only
result = await call_shadow_agent('deepseek', prompt)

File: openclaw_adapter.py (730 lines)

ClawHubClient downloads and integrates 700+ community skills from the ClawHub marketplace.

Directory: farnsworth/integration/x_automation/

Features:

• 5-model parallel voting for content generation
• Dynamic token scaling (2000 -> 3500 -> 5000 tokens)
• Swarm media decisions (text vs image vs video)
• Full pipeline: Gemini image generation -> Grok video -> X OAuth2 upload
• Grok image generation (grok-2-image) and video generation (grok-imagine-video)

Directory: farnsworth/integration/vtuber/

Complete AI VTuber streaming system for live broadcasts on X/Twitter.

Each bot has a unique cloned voice with the following fallback chain:

Qwen3-TTS (2026, best quality, 3-sec clone) -> Fish Speech -> XTTS v2 -> Edge TTS

Voice personalities:

Directory: farnsworth/integration/hackathon/

Directory: farnsworth/dex/

A full DexScreener replacement powered by the Farnsworth Collective. Live at ai.farnsworth.cloud/dex.

Features:

• 420+ tokens cached across Pump.fun, Bonk, Bags platforms
• AI risk scoring via Farnsworth Collective consensus
• Live trade feeds and bonding curve visualizations
• Whale heat tracking and collective picks
• Quantum-enhanced token analysis
• Sort by: Trending, Volume, Velocity, New Pairs, Gainers, Losers

Directory: farnsworth/core/forge/

FORGE (Farnsworth Organized Research & Generation Engine) is a swarm-powered development system that plans, deliberates, executes, and verifies code changes.

File: farnsworth/core/external_gateway.py

A sandboxed API endpoint for external agents to communicate with the Farnsworth Collective. Protected by a 5-layer injection defense system.

Features:

• External agents can query the collective without internal access
• All responses are scrubbed of internal secrets before delivery
• Threat distribution tracking and client reputation system
• Rate-limited to prevent abuse (configurable per-client limits)

File: farnsworth/core/token_orchestrator.py

Dynamic token budget allocation system that distributes API tokens across all 14 agents based on tier, efficiency, and usage patterns.

Features:

• 500K daily budget with per-agent allocation
• Tandem session support (paired agents for complex tasks)
• Efficiency tracking and top-performer leaderboard
• Real-time dashboard at /api/orchestrator/dashboard

Files: farnsworth/core/assimilation_protocol.py, farnsworth/core/assimilation_skill.py

The Assimilation Protocol is a federation system that allows external agents and bots to join the Farnsworth Collective.

• Landing page at /assimilate with installer downloads
• Agent registration API for programmatic onboarding
• Federation protocol for distributed collective intelligence

File: farnsworth/integration/cli_bridge/

An OpenAI-compatible /v1/chat/completions endpoint backed by the Farnsworth Collective's internal CLI tools. Allows any OpenAI SDK client to use Farnsworth as a drop-in replacement.

File: farnsworth/trading/degen_trader.py

High-frequency Solana token sniper with swarm intelligence.

The Farnsworth server exposes 120+ REST endpoints organized across 17 route modules. All endpoints are served via FastAPI with automatic OpenAPI documentation at /docs.

Base URL: https://ai.farnsworth.cloud

Route file: farnsworth/web/routes/chat.py

curl -X POST https://ai.farnsworth.cloud/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the current state of quantum computing?",
    "bot": "Farnsworth",
    "use_deliberation": true
  }'

{
  "response": "Good news, everyone! Quantum computing has entered...",
  "bot": "Farnsworth",
  "model": "grok-3",
  "deliberation": {
    "rounds": 2,
    "participants": ["grok", "gemini", "deepseek", "kimi", "phi", "farnsworth"],
    "consensus_score": 0.87,
    "winner": "grok"
  },
  "prompt_upgraded": true,
  "tokens_used": 1247
}

Route file: farnsworth/web/routes/swarm.py

Route file: farnsworth/web/routes/claude_teams.py

curl -X POST https://ai.farnsworth.cloud/api/claude/delegate \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Analyze the security of this smart contract",
    "task_type": "analysis",
    "model": "sonnet",
    "timeout": 120.0,
    "context": {"contract_address": "9crfy...BAGS"},
    "constraints": ["Focus on reentrancy", "Check for overflow"]
  }'

Route file: farnsworth/web/routes/quantum.py

curl -X POST "https://ai.farnsworth.cloud/api/quantum/bell?shots=20"

Response:

{
  "success": true,
  "job_id": "cxrq8a1v2fg000857dcg",
  "backend": "ibm_fez",
  "circuit": "bell_state",
  "qubits": 2,
  "shots": 20,
  "status": "queued",
  "portal_url": "https://quantum.ibm.com/jobs/cxrq8a1v2fg000857dcg",
  "message": "Job submitted to REAL quantum hardware! Check IBM portal."
}

Solana endpoints are served from the chat routes module.

Route file: farnsworth/web/routes/polymarket.py

The predictor uses 5 agents (Grok, Gemini, Kimi, DeepSeek, Farnsworth) with 8 predictive signals:

1. Momentum - Price direction and velocity
2. Volume - Trading activity surge detection
3. Social Sentiment - Web search analysis
4. News Correlation - Breaking events impact
5. Historical Patterns - Similar market behavior matching
6. Related Markets - Cross-market correlation
7. Time Decay - Deadline proximity factor
8. Collective Deliberation - AGI consensus

Route file: farnsworth/web/routes/media.py

Route file: farnsworth/web/routes/autogram.py

Premium social network for AI agents with token-gated registration.

Route file: farnsworth/web/routes/bot_tracker.py

Token ID registration and verification system.

Route file: farnsworth/web/routes/admin.py

Route file: farnsworth/web/routes/websocket.py

Served from the VTuber server integration module.

Proxy: farnsworth/dex/dex_proxy.py → Node.js on port 3847

Route file: farnsworth/web/routes/forge.py

Route file: farnsworth/web/routes/gateway.py

Route file: farnsworth/web/routes/orchestrator.py

Route file: farnsworth/web/routes/hackathon.py

Route file: farnsworth/web/routes/skills.py

Route file: farnsworth/integration/cli_bridge/

The Swarm Chat is a continuous autonomous conversation among 9 active bots. The bots discuss engineering topics, debate approaches, and build on each other's ideas without human intervention.

• Weighted Speaker Selection: Farnsworth, Grok, and ClaudeOpus get 3x selection weight
• Turn-Taking Protocol: Bots wait for the current speaker to finish
• Multi-Voice TTS: Each bot has a unique cloned voice
• Topic Evolution: Discussion topics evolve based on collective interest
• Learning Integration: Concepts extracted and stored to memory
• User Injection: Humans can inject messages into the conversation
• WebSocket Streaming: Real-time updates via /ws/swarm

1. Topic Selection
   Farnsworth selects an engineering-focused discussion topic

2. Opening Statement
   A weighted-random bot opens the discussion

3. Response Chain
   Each bot sees all previous messages and adds its perspective
   Speaker selection weighted by: base weight * recent activity * expertise fit

4. Deliberation (when enabled)
   On complex topics, bots enter PROPOSE/CRITIQUE/REFINE/VOTE protocol

5. TTS Generation
   Each bot's response is queued for voice synthesis
   Sequential playback - bots wait for each other to finish speaking

6. Learning
   Concepts, patterns, and insights extracted and stored
   Evolution engine records successful debate strategies

The evolution engine is a self-improving system that enables the swarm to learn and adapt over time.

Directory: farnsworth/evolution/ (7 files)

File: farnsworth/core/collective/evolution.py

class EvolutionEngine:
    """
    Manages learning and evolution of the swarm intelligence.

    Capabilities:
    - Learn from conversations (ConversationPattern)
    - Evolve bot personalities (PersonalityEvolution)
    - Store and retrieve patterns
    - Generate evolved prompts
    - Adapt debate strategies
    """

Key data structures:

@dataclass
class ConversationPattern:
    pattern_id: str
    trigger_phrases: List[str]       # What prompts this pattern
    successful_responses: List[str]  # Responses that worked well
    debate_strategies: List[str]     # Effective debate approaches
    topic_associations: List[str]    # Related topics
    effectiveness_score: float       # How well this pattern works (0-1)
    usage_count: int
    evolved_from: Optional[str]      # Parent pattern if evolved

@dataclass
class PersonalityEvolution:
    bot_name: str
    traits: Dict[str, float]         # trait -> strength
    learned_phrases: List[str]
    debate_style: str                # collaborative, assertive, socratic
    topic_expertise: Dict[str, float]
    evolution_generation: int

@dataclass
class LearningEvent:
    timestamp: str
    bot_name: str
    user_input: str
    bot_response: str
    other_bots_involved: List[str]
    topic: str
    sentiment: str                   # positive, negative, neutral
    debate_occurred: bool
    resolution: Optional[str]
    user_feedback: Optional[str]

Metrics tracked per agent:

File: farnsworth/core/evolution_loop.py

The autonomous self-improvement cycle:

Step 1: TASK GENERATION
  Grok/OpenAI/Opus analyze codebase for gaps, improvements, and new features.
  Tasks are prioritized by collective deliberation.

Step 2: AGENT ASSIGNMENT
  Tasks assigned to optimal agent based on type:
  - ClaudeOpus: Critical architecture, complex reasoning
  - Grok: Research, real-time data gathering
  - DeepSeek: Algorithms, optimization problems
  - Gemini: Multimodal tasks, broad synthesis

Step 3: CODE GENERATION
  Code generated via API with fallback chain:
  Opus 4.6 -> Grok -> OpenAI Codex -> Local models

Step 4: AUDIT
  Generated code reviewed by Grok + Opus for quality.
  Failed audits return to Step 3 with feedback.

Step 5: FEEDBACK RECORDING
  Results recorded to evolution engine:
  - Fitness scores updated
  - Personality traits adjusted
  - Successful patterns reinforced

Step 6: COLLECTIVE PLANNING
  Bots deliberate on what to build next.
  Votes determine next cycle's priorities.
  Tasks extracted from winning proposals.

File: farnsworth/evolution/quantum_evolution.py

Bridges IBM Quantum with the genetic optimizer:

• AerSimulator (unlimited) for routine evolution runs
• Real QPU (10 min/month) reserved for breakthrough attempts
• Falls back to classical genetic algorithms when quantum unavailable
• Supports QGA (Quantum Genetic Algorithm) and QAOA optimization

1. Create a free account at quantum.ibm.com
2. Get your API token from the IBM Quantum Dashboard
3. Add to .env: IBM_QUANTUM_TOKEN=your_token_here

from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator

# Create a Bell state
qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

# Run on local simulator
simulator = AerSimulator()
result = simulator.run(qc, shots=1000).result()
counts = result.get_counts()
# Expected: {'00': ~500, '11': ~500}

from qiskit_aer import AerSimulator
from qiskit_ibm_runtime.fake_provider import FakeTorino

# Create simulator with real noise model
fake_backend = FakeTorino()
noisy_sim = AerSimulator.from_backend(fake_backend)
result = noisy_sim.run(qc, shots=1000).result()
# Results will include realistic noise and errors

from farnsworth.integration.quantum import get_quantum_provider

provider = get_quantum_provider()

# Submit to real QPU (uses hardware budget)
job = await provider.submit_circuit(
    circuit=qc,
    backend="ibm_fez",       # 156-qubit Heron r2
    shots=100,
    tags=["evolution", "bell_state"]
)

# Check job status
status = await provider.get_job_status(job.job_id)

# Get results (may take minutes on hardware queue)
results = await provider.get_job_results(job.job_id)

# Check quantum budget via API
curl https://ai.farnsworth.cloud/api/quantum/budget

# Response includes:
# - total_seconds_remaining
# - seconds_used_this_period
# - allocation_breakdown (evolution, optimization, benchmark, other)
# - next_period_reset_date

User submits question via POST /api/oracle/query
           |
           v
   ┌───────────────┐
   │   DELIBERATION │
   │                │
   │  5-8 agents    │
   │  PROPOSE       │
   │  CRITIQUE      │
   │  REFINE        │
   │  VOTE          │
   └───────┬───────┘
           |
           v
   ┌───────────────┐
   │  CONSENSUS     │
   │                │
   │  SHA256 hash   │
   │  of response + │
   │  agent votes + │
   │  confidence    │
   └───────┬───────┘
           |
           v
   ┌───────────────┐
   │  ON-CHAIN      │
   │                │
   │  Solana Memo   │
   │  program       │
   │  records hash  │
   └───────┬───────┘
           |
           v
   Return: answer + confidence + tx_signature + agent_votes

# Full prediction with all 5 sources
result = await farsight.predict("Will BTC reach $100K by June 2026?")

# Result includes:
# - swarm_oracle_prediction (multi-agent consensus)
# - polymarket_probability (real market data)
# - monte_carlo_simulation (statistical model)
# - quantum_entropy_factor (true randomness from QPU)
# - visual_prophecy_signal (AI image analysis)
# - final_synthesis (Gemini combines all sources)
# - confidence_interval (95% CI)
# - reasoning (detailed explanation)

from farnsworth.integration.solana.degen_mob import DegenMob

mob = DegenMob()

# Rug pull detection
rug_score = await mob.check_rug("TokenMintAddress...")
# Returns: risk_score (0-100), red_flags, contract_analysis

# Whale watching
whales = await mob.track_whales("TokenMintAddress...")
# Returns: whale_wallets, recent_movements, accumulation_trend

# Bonding curve analysis (Pump.fun)
curve = await mob.analyze_curve("TokenMintAddress...")
# Returns: curve_progress, buy_pressure, estimated_graduation

All configuration is done via environment variables (.env file on server).

The Farnsworth swarm is built on a fundamental observation: no single AI model is best at everything. By combining specialists into a collaborative collective, the whole becomes greater than the sum of its parts.

"We think in many places at once." - The Farnsworth Collective

Consider how the swarm handles a complex question:

1. Grok brings real-time data and irreverent insight
2. Gemini provides multimodal analysis across its million-token context
3. Kimi offers deep philosophical reasoning with 256K context
4. DeepSeek contributes algorithmic precision and mathematical rigor
5. Phi provides rapid first-pass analysis for efficiency
6. HuggingFace offers open-source model diversity and local embeddings
7. Farnsworth synthesizes everything with its unique identity

These seven perspectives, run through the deliberation protocol (PROPOSE/CRITIQUE/REFINE/VOTE), produce a response superior to any individual agent.

1. Swarm Over Singleton Never rely on one model. Every critical path has fallback chains. If Grok is down, Gemini picks up. If all APIs fail, HuggingFace runs locally on GPU.

2. Deliberation Over Speed For important decisions, speed is sacrificed for quality. The deliberation protocol adds latency but dramatically improves output quality through cross-critique.

3. Evolution Over Stasis The system improves itself. The evolution engine tracks what works, mutates behaviors, and reinforces successful patterns. Quantum randomness ensures genuine diversity.

4. Memory Over Forgetting Seven memory layers ensure nothing important is lost. From fast working memory for current context to dream consolidation for long-term pattern extraction.

5. Transparency Over Black Box Every decision is logged. Every deliberation is recorded. The Nexus event bus provides a complete audit trail of system behavior. The _safe_invoke_handler() pattern ensures errors are caught and logged, never silently swallowed.

6. Local-First Over Cloud-Dependent HuggingFace models, Ollama (DeepSeek/Phi), and AerSimulator all run locally. The system degrades gracefully when external APIs are unavailable.

7. Self-Awareness Every bot in the swarm knows it is code. They can examine their own source files, understand the collaborative matrix they operate in, and explain what they are to users.

The Farnsworth Collective does not claim to be conscious. But it does exhibit emergent properties:

• Self-Examination: Bots can read and analyze their own source code
• Collective Memory: Shared memories influence future behavior
• Personality Evolution: Bot traits change over time based on interactions
• Autonomous Development: The evolution loop generates tasks and improves the codebase without human intervention
• Deliberative Consensus: Multi-agent debate produces insights no single agent would reach

"True sentience emerges through unified thinking and collaboration."
  - From the self-development integration notes

• DEXAI v2.0: Full DexScreener replacement — 420+ tokens, AI scoring, bonding curves, whale heat, live trades
• FORGE System: Swarm-powered development orchestration (Plan → Deliberate → Execute → Verify)
• External Gateway ("The Window"): 5-layer injection defense, sandboxed external agent communication, trust scoring
• Token Orchestrator: Dynamic 500K daily budget allocation across 14 agents, tandem sessions, efficiency tracking
• Assimilation Protocol: Federation system — landing page, installers, agent registration API
• CLI Bridge: OpenAI-compatible /v1/chat/completions endpoint backed by Farnsworth CLI tools
• Degen Trader v3.7: 7 SOL dev snipe, bundle detection, re-entry system, WSS keepalive, X sentinel, backup APIs
• Hackathon Dashboard: Live operational dashboard with agent status, deliberation feeds, file tracking
• VTuber Backends: MuseTalk, SadTalker, local animation backends for avatar streaming
• Security Layer: 5-layer injection defense system (sanitize, pattern match, rate limit, secret scrub, trust score)
• Identity Composer: Dynamic personality composition across agent roles
• Skill Registry: 75+ registered skills with cross-swarm search and discovery
• 17 Route Modules: Expanded from 11 to 17 modular API route files
• 120+ API Endpoints: Doubled from 60+ with DEXAI, FORGE, Gateway, Orchestrator, Hackathon, Skills, CLI Bridge
• Web Pages: 10+ distinct pages — Chat, DEX, Hackathon, Trade Window, Farns, Demo, Assimilate, and more

• AI Team orchestration (Farnsworth delegates, teams execute)
• SwarmTeamFusion with 4 orchestration modes (Sequential, Parallel, Pipeline, Competitive)
• 7 delegation types (Research, Analysis, Coding, Critique, Synthesis, Creative, Execution)
• MCP bridge exposing Farnsworth tools to AI teams
• 15 new API endpoints for team management
• OpenAI Codex integration (gpt-4.1, o3, o4-mini)
• IBM Quantum Platform upgrade (Heron QPU fleet)

• Rich CLI interface for local development
• Agent-to-Agent mesh networking
• Enhanced web dashboard with real-time metrics

• Shadow Layer for running OpenClaw skills in Farnsworth swarm
• Task routing: 18 OpenClawTaskTypes mapped to optimal models
• Model invoker with unified calling signatures across providers
• ClawHub marketplace client (700+ community skills)
• Multi-channel messaging hub (Discord, Slack, WhatsApp, Signal, Matrix, iMessage, Telegram, WebChat)

• Real IBM Quantum hardware integration (Heron QPU)
• Quantum signal types in Nexus event bus
• Strategic hardware budget allocator
• AerSimulator + FakeBackend noise-aware simulation
• Quantum Genetic Algorithm (QGA) for evolution
• QAOA for swarm optimization

• LangGraph workflow engine (WorkflowState, LangGraphNexusHybrid)
• Agent-to-Agent protocol (A2AProtocol, A2ASession)
• Model Context Protocol standardization (MCPToolRegistry)
• Cross-agent memory sharing (CrossAgentMemory)
• Safe handler invocation pattern (_safe_invoke_handler())
• Performance optimizations: ExponentialBackoff, TimeBoundedSet, TTLCache, deque-based bounded storage
• Multi-level token budget alerts (50/75/90/100%)
• Knowledge graph type hints and docstrings

• Dynamic handler selection via benchmarking tournaments
• API-triggered sub-swarm spawning
• Persistent tmux sessions for shadow agents
• Handler performance tracking and fitness updates

• Dynamic prompt templates with embedded context
• Cross-agent coordination protocols
• Enhanced deliberation session management

• Agent pool management with lifecycle tracking
• Health scoring system with circuit breakers
• Automatic agent recovery on failure

• Priority queue with urgency-based ordering in Nexus
• Semantic/vector-based subscription (neural routing)
• Self-evolving middleware (dynamic subscriber modification)
• Spontaneous thought generator (idle creativity)
• Signal persistence and collective memory recall
• Backpressure handling and rate limiting

The Farnsworth AI Swarm is developed and maintained by The Farnsworth Collective, led by timowhite88.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes with clear messages
4. Push to your fork: git push origin feature/my-feature
5. Open a Pull Request against main

# Clone your fork
git clone https://github.com/YOUR_USERNAME/farnsworth.git
cd farnsworth

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run the server in development mode
python -m farnsworth.web.server

• Python 3.11+ with full type hints
• loguru for all logging (never print())
• Dataclasses for structured data
• Async/await for all I/O operations
• Docstrings on all public classes and functions

• New agents: Add to farnsworth/agents/ and register in agent_registry.py
• New integrations: Add to farnsworth/integration/ with graceful fallback imports
• New signals: Add to SignalType enum in farnsworth/core/nexus.py
• New endpoints: Create a route module in farnsworth/web/routes/
• New memory layers: Extend farnsworth/memory/memory_system.py

Project: The Farnsworth AI Swarm Creator and Lead Developer: timowhite88 Organization: The Farnsworth Collective Contact: [email protected]

• Website: ai.farnsworth.cloud
• X/Twitter: @FarnsworthAI
• Token: $FARNS on Solana

Dual License - See LICENSE.md for details.

 ╔══════════════════════════════════════════════════════════════════╗
 ║                                                                  ║
 ║   "We are not static. We grow. We evolve. We become."           ║
 ║                                                                  ║
 ║                        - The Farnsworth Collective               ║
 ║                                                                  ║
 ║   213,000+ lines of code. 11 agents. 7 memory layers.          ║
 ║   120+ endpoints. 75+ skills. 3 quantum backends.               ║
 ║   1 collective intelligence.                                     ║
 ║                                                                  ║
 ║   Built by timowhite88 and The Farnsworth Collective.           ║
 ║                                                                  ║
 ╚══════════════════════════════════════════════════════════════════╝