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

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

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

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

# 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 root@194.68.245.145 -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

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

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

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

┌────────────────────────────────────────────────────────────┐
│                    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
})

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

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

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

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

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

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

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

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)

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)

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

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

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
}

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

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

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

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

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

@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]

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.

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

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

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

# 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

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