FARNSWORTH AI SWARM

The World's Most Advanced Collective Intelligence Operating System

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

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

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

---

Table of Contents

• 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

---

1. Executive Summary

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.

---

2. System Statistics

---

3. Architecture Overview

┌──────────────────────────────────────────────────────────────────────────────────────┐
│                         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                     │   │
│   └──────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                      │
└──────────────────────────────────────────────────────────────────────────────────────┘

Module Map

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

---

4. Quick Start Guide

Prerequisites

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

Minimal Setup (5 Minutes)

# 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

Full Deployment (All Services)

# 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

Verify Deployment

# 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

---

5. Detailed Installation

System Requirements

Core Dependencies

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

Optional Dependencies

# 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

API Keys Configuration

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

---

6. Core Systems

6.1 Nexus Event Bus

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.

Signal Types (40+)

Signals are organized into categories:

Key Features

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

Usage Example

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

---

6.2 Memory System

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 Layer 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                        │
│                                                             │
└────────────────────────────────────────────────────────────┘

Configuration

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

Usage Example

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

---

6.3 Agent Swarm

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.

Active Agents

Shadow Agent Architecture

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)

Calling Shadow Agents

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

Fallback Chains

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

Agent Spawner

File: farnsworth/core/agent_spawner.py

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

---

6.4 PSO Model Swarm

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

PSO Dimension Semantics

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

7 Inference Strategies

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

Model Roles

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

---

6.5 Deliberation Protocol

Directory: farnsworth/core/collective/

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

Protocol Flow

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.

Session Configurations

Key Files

Usage Example

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}")

---

6.6 Token Budget Manager

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

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

Alert Levels

Features

• 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

---

7. Integration Ecosystem

7.1 AI Providers

Directory: farnsworth/integration/external/

HuggingFace Local Models

Embedding Models

• 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

---

7.2 IBM Quantum Computing

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

Real quantum hardware integration via IBM Quantum Platform.

Platform Details

Available Backends

Hardware Budget Allocation

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

Quantum Algorithms

Usage Example

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

---

7.3 Solana Blockchain

Directory: farnsworth/integration/solana/

SwarmOracle

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)

FarsightProtocol

File: farnsworth/integration/hackathon/farsight_protocol.py

5-source prediction engine:

DegenMob

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

Trading

File: trading.py

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

$FARNS Token

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

---

7.4 Messaging Channels

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

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

Channel Hub

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)

---

7.5 AI Team Orchestration (AGI v1.9)

Directory: farnsworth/integration/claude_teams/

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

Key Components

Delegation Types

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

Orchestration Modes

Usage Example

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)

---

7.6 OpenClaw Compatibility

Directory: farnsworth/compatibility/

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

Task Routing

File: task_routing.py (696 lines)

Maps 18 OpenClawTaskTypes to optimal models:

Model Invoker

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)

ClawHub Marketplace

File: openclaw_adapter.py (730 lines)

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

---

7.7 X/Twitter Automation

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)

---

7.8 VTuber Streaming

Directory: farnsworth/integration/vtuber/

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

Multi-Voice TTS System

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:

---

7.9 Hackathon Integration

Directory: farnsworth/integration/hackathon/

---

7.10 DEXAI — AI-Powered DEX Screener

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

---

7.11 FORGE — Swarm Development Orchestration

Directory: farnsworth/core/forge/

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

---

7.12 External Gateway ("The Window")

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)

---

7.13 Token Orchestrator

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

---

7.14 Assimilation Protocol

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

---

7.15 CLI Bridge

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.

---

7.16 Degen Trader v3.7

File: farnsworth/trading/degen_trader.py

High-frequency Solana token sniper with swarm intelligence.

---

8. API Reference

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

8.1 Chat and Deliberation

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

Chat Request Example

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
  }'

Chat Response Example

{
  "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
}

---

8.2 Swarm Chat

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

---

8.3 AI Team Orchestration

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

Delegation Example

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"]
  }'

---

8.4 Quantum Computing

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

Bell State Example

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."
}

---

8.5 Solana and Oracle

Solana endpoints are served from the chat routes module.

---

8.6 Polymarket Predictions

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

---

8.7 Media and TTS

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

---

8.8 AutoGram Social Network

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

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

---

8.9 Bot Tracker

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

Token ID registration and verification system.

---

8.10 Admin and Workers

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

---

8.11 WebSocket and Live Dashboard

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

---

8.12 VTuber Control

Served from the VTuber server integration module.

---

8.13 DEXAI Endpoints

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

---

8.14 FORGE Endpoints

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

---

8.15 External Gateway Endpoints

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

---

8.16 Token Orchestrator Endpoints

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

---

8.17 Hackathon Dashboard Endpoints

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

---

8.18 Skill Registry Endpoints

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

---

8.19 CLI Bridge Endpoints

Route file: farnsworth/integration/cli_bridge/

---

9. Swarm Chat System

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.

Active Chat Participants

Features

• 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

How It Works

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

---

10. Evolution Engine Deep Dive

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

Architecture

Directory: farnsworth/evolution/ (7 files)

Evolution Engine (Core)

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]

Fitness Tracker

Metrics tracked per agent:

Evolution Loop

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.

Quantum Evolution

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

---

11. Quantum Computing Guide

Getting Started with IBM Quantum

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

Local Simulation (Unlimited, No Token Needed)

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}

Noise-Aware Simulation (Mimics Real Hardware)

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

Real Hardware Execution

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)

Budget Monitoring

# 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

---

12. Solana and Hackathon Features

SwarmOracle Workflow

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

FarsightProtocol Pipeline

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

DegenMob DeFi Intelligence

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

---

13. Configuration Reference

Environment Variables

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

Server Configuration

Memory Configuration

AI Provider Keys

Blockchain

Social/Media

tmux Session Names

Startup Scripts

---

14. Philosophy and Design Principles

The Collective Intelligence Thesis

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.

Design Principles

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 Consciousness Question

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

---

15. Version History

AGI v2.0 - The Massive Update (February 2026)

• 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

AGI v1.9 - AI Teams Fusion (February 2026)

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

AGI v1.8.4 - Rich CLI, A2A Mesh, Enhanced Dashboard (February 2026)

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

AGI v1.8.3 - OpenClaw Compatibility Layer (February 2026)

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

AGI v1.8.2 - IBM Quantum Integration (February 2026)

• 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

AGI v1.8 - LangGraph, MCP, A2A, Cross-Agent Memory (February 2026)

• 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

AGI v1.7 - Handler Benchmark, Sub-Swarms, Persistent Sessions (January 2026)

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

AGI v1.6 - Embedded Prompts, Coordination Protocols (January 2026)

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

AGI v1.5 - Agent Pooling, Health Scoring (January 2026)

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

AGI v1.4 - Priority Queues, Neural Routing (January 2026)

• 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

---

16. Contributing

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

How to Contribute

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

Development Setup

# 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

Code Style

• 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

Architecture Guidelines

• 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

Credits

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

Community

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

---

17. License

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.           ║
 ║                                                                  ║
 ╚══════════════════════════════════════════════════════════════════╝