tostido/cocoon-authority-glass-box

🦋 Butterfly Cocoon - Standalone Agent

Generated: 2026-06-05T22:08:58.006890 Mode: ENSEMBLE (2 organisms) Template Size: 9,703,681 chars (code only) Classes: 15 (Neural + Language + Memory + Knowledge + VP) ---

This Space: Amalgam Mesh + Autonomous Dispatch

The front door of this Space (and the local Authority) is the Amalgam Mesh - a single live D3 graph where the cocoon's minds, concepts, and facilities are all massed into one reactive matrix. Click any amber facility node to fire its route live; hit dispatch to let the cocoon fire its own nodes (the autonomous scheduler over the capability syscall table). The classic card-wall console is preserved at /classic.

Full surface + route reference: `AMALGAM_MESH_AND_DISPATCH.md`.

The sections below are the auto-generated cocoon model card - they document the cocoon.py CLI, not the Authority web server.

Current Local Quick Start

The primary local entry point is the global Termux command:

cocoon doctor
cocoon eval --delay-ms 50 --max-failures 1
cocoon gui

Open the GUI at http://127.0.0.1:8765/ on the phone. To serve it to another device on the same LAN:

cocoon gui --host 0.0.0.0 --port 8765

Core runtime status is reported by cocoon doctor. cocoon eval runs real smoke checks against the current cocoon: metadata, embedded readme, Gymnasium CartPole without learning, and headless sphere training. It writes JSON reports under eval_reports/ and records an Amalgam receipt when the Amalgam package is installed. The core is the Python cocoon quine runtime: PyTorch, the Mira-Kite Authority GUI, Flask serve mode, websockets link mode, Cascade receipts, Quinesmith syntax discipline, and headless sphere training. ONNX, pygame visuals, matplotlib plots, PyFlyt, and TMRL are extension faculties.

See:

• —TERMUX_AND_SPACE_QUICKSTART.md
• —COCOON_SYSTEM_COOKBOOK.md

🏴‍☠️ Butterfly Privateer Command (classic console, now at /classic)

This card-wall console is now the classic UI, served at /classic. The default front door at / is the Amalgam Mesh - see AMALGAM_MESH_AND_DISPATCH.md.

The Mira-Kite Authority web interface lets you interact with, train, and "overclock" this cocoon.

This is a local, high-tech pirate-themed command console that provides:

• —Quarters: Chat with Mira and Kite directly.
• —The Brig: Run tactical reasoning drills (cue, chain, role).
• —The Vault: Route signals and manually enforce associations.
• —Overclock: 🦋 Cheat Mode. Programmatically boost the Learning Rate (up to 50x) and inject high-reward "Super-Experiences" to rapidly evolve the neural weights.
• —Black Ledger: Audit cryptographic Cascade receipts and learning traces.

How to Launch the Command Console

# Start the authority server
python mira_kite_authority.py --cocoon cocoon_cognition_agency.py

# Open your browser to:
http://127.0.0.1:8765/

🧬 Formation Fingerprint

This cocoon's emergent history - how these organisms came to be:

Fitness: min=0.7559, max=0.9238, mean=0.8398

Events Witnessed: 253,972 total Top Event Types: neuraldecision (201599), allianceeventrecorded (11202), alliancealliancedissolved (10263), alliancememberleft (7777), statechange (4307)

Alliance Landscape: 149 total alliances

• —Alliance alliance_129_0c01_1652 (tier 1, 2 members)

Simulation Snapshot:

🧠 Neural Topology Visualization

[📊 Open Interactive Topology Viewer](ensemble_topology.html)

The topology visualization provides:

• —Per-organism layers - Toggle individual neural networks on/off
• —Overlay mode - See all organisms' architectures superimposed
• —Stacked mode - View organisms in horizontal strips
• —Grid mode - Compare organisms side-by-side
• —Color-coded neurons - Input (cyan), Hidden (magenta), Output (yellow), Language (green)

Open the HTML file in a browser for the full interactive experience.

🧠 What's Inside

This is a MONOLITHIC cocoon - a completely self-contained Python file with:

Organisms:

• —16525dfc6c33419b
• —0c019d24a56b0086

Embedded Subsystems:

Embedded Data:

• —Neural weights (Base64-encoded PyTorch state dicts)
• —Vocabulary (token↔id mapping)
• —Atomic language corpus (if available)
• —Conversation history (if available)

🔥 Continued Learning

YES, this cocoon supports continued learning!

The cocoon.py file contains full PyTorch modules that can continue training:

1. 1.Full PyTorch modules - can call backward() and update gradients
2. 2.ExperienceBuffer - stores (state, action, reward) tuples for replay
3. 3.AtomicLanguageSystem - creates new semantic atoms from conversations
4. 4.EnhancedKnowledgeWeb - grows semantic relations as concepts connect
5. 5.ConversationHistory - accumulates context over time

# The agent learns from every interaction:
agent = CocoonAgent()
action, output = agent.get_action(state)  # Updates VP, stores experience
agent.atomic_lang.create_atom("new_concept", "definition", emotion=0.8)  # Creates new atom
agent.knowledge_web.add_relation("concept_a", "concept_b", "related_to", strength=0.9)  # Grows web

Export Comparison:

TorchScript (.pt) CAN* continue learning! Load with torch.jit.load(), call .train(), run backward pass. However, it only contains the neural network - no AtomicLanguageSystem, KnowledgeWeb, or other symbolic subsystems.

Fine-tuning a TorchScript model:

import torch

# Load the exported TorchScript model
model = torch.jit.load("brain_ensemble.pt")
model.train()

# Fine-tune on new data
optimizer = torch.optim.Adam(model.parameters(), lr=1e-4)
for state, target in new_training_data:
    optimizer.zero_grad()
    output = model(state)
    loss = criterion(output, target)
    loss.backward()
    optimizer.step()

# Save updated model
torch.jit.save(model, "brain_finetuned.pt")

🚀 Quick Start

# View cocoon info
python cocoon.py --mode info

# Start chatting
python cocoon.py --mode chat

# Play games
python cocoon.py --mode gym --env CartPole-v1

# 3D sphere arena
python cocoon.py --mode sphere --train

# 🛸 Drone warfare (extract adapter first)
python cocoon.py --unpack ./my_cocoon
python cocoon_drone_adapter.py --mode tag_battle

📚 Complete Command Reference

Mode Selection

💬 Chat Mode

Interactive conversation with the neural organisms. Learns from every interaction.

python cocoon.py --mode chat
python cocoon.py --mode chat --verbose

In-Chat Commands:

🌐 Sphere Arena (3D Training)

Swarm defense game where organisms cooperate to catch falling balls.

Sphere Arena Flags:

🛸 Drone Warfare Arena (Companion Script)

NASA JSBSim-grade drone combat simulation. Complete system embedded - extract with --unpack.

Setup:

python cocoon.py --unpack ./my_cocoon    # Extracts full drone suite:
#   - cocoon_drone_adapter.py    (main entry point)
#   - cocoon_drone_arena.py      (8-mode arena)
#   - jsbsim_quadcopter.py       (6-DOF physics)
cd my_cocoon
python cocoon_drone_adapter.py           # Run the adapter

Game Modes: free_fly, formation, pursuit, tag_battle, zone_control, capture_flag, survival, escort

Requirements: pip install numpy matplotlib (PyFlyt optional: pip install PyFlyt)

🎮 Gymnasium Environments

Built-in (always available):

Atari (`pip install ale-py`):**

• —ALE/Pong-v5, ALE/Breakout-v5, ALE/SpaceInvaders-v5

MuJoCo (`pip install gymnasium[mujoco]`):

• —Ant-v4, HalfCheetah-v4

Gym Flags:

�️ TrackMania 2020 (TMRL Integration)

Drive TrackMania 2020 with your cocoon organisms using the embedded TMRL adapter!

Requirements:

1. 1.TrackMania 2020 (Ubisoft/Epic)
2. 2.OpenPlanet plugin installed (openplanet.dev)
3. 3.TMRL Python package: pip install tmrl
4. 4.Extract cocoon_tmrl_adapter.py via --unpack

Quick Start:

# Extract adapter from cocoon
python cocoon.py --unpack ./my_tmrl

# Run the adapter
python cocoon_tmrl_adapter.py --cocoon path/to/cocoon.py --drive --episodes 4

Important:

• —Play on the "tmrl-test" track for proper rewards (search in TrackMania)
• —The adapter uses LIDAR observations + speed data
• —Ensembles use majority voting for actions

TMRL Adapter Commands:

�🌐 HTTP API Server

python cocoon.py --mode serve --port 8080

Endpoints:

Example `/chat` request:

curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello!", "learn": true}'

🔗 Link Mode (P2P Networking)

Connect to other cocoons for battles and chat.

python cocoon.py --mode link --hatch ws://server:9000 --name "Champion"

Link Mode Flags:

In-Link Commands:

Requirements: pip install websockets

🔬 Export & Conversion

TorchScript vs ONNX: | Format | Continued Learning | Portability | Best For | |--------|-------------------|-------------|----------| | .pt (TorchScript) | ✅ Yes - can fine-tune | PyTorch/LibTorch/C++ | Research, fine-tuning | | .onnx (ONNX) | ❌ Inference only | Universal (C++, JS, Rust, etc.) | Production deployment |

📦 Files Created by --unpack

Spawns a complete deployment package:

output_dir/
├── README.md                # This documentation
├── cocoon_tmrl_adapter.py   # TrackMania 2020 adapter (if embedded)
├── cocoon_drone_adapter.py  # Drone Warfare adapter (if embedded)
├── cocoon_drone_arena.py    # Full 8-mode drone arena (if embedded)
├── jsbsim_quadcopter.py     # NASA JSBSim 6-DOF physics (if embedded)
├── vocabulary.json          # Token vocabulary
├── metadata.json            # Export metadata + organism info
├── requirements.txt         # Python dependencies
├── ensemble.onnx            # ONNX model (all brains unified)
└── ensemble_weights.pt      # PyTorch weights bundle

📦 Files Created by --export-package

Netron-viewable package with ONNX models and model card:

my_model/
├── brain_ensemble.onnx    # Combined ONNX (all brains unified)
├── brain_*.onnx           # Individual organism ONNX files
├── vocabulary.json        # Token vocabulary
├── metadata.json          # Full configuration + fitness + architecture
└── README.md              # Model card documentation

Note: To get the full cocoon.py + requirements.txt, use `--unpack` instead.

⚙️ Global Options

These flags work with any mode:

Examples:

python cocoon.py --mode chat --max-organisms 5    # Load only 5 organisms
python cocoon.py --mode gym --voting majority     # Use majority voting
python cocoon.py --mode chat --verbose            # Debug output

📡 API Reference

CocoonAgent

from cocoon import CocoonAgent

agent = CocoonAgent()

# Get action from state (returns action_idx, {outputs dict})
action, outputs = agent.get_action(state_vector)
# outputs = {'action_probs': [...], 'value': float, 'language_logits': [...], 'vp': float}

# Process text input (for chat mode)
response = agent.process_input("Hello there!")

# Access subsystems
agent.atomic_lang.get_atoms_by_emotion(min_valence=0.5)  # Get positive atoms
agent.conversation_history.get_summary()  # Get conversation stats
agent.knowledge_web.get_related("concept", min_strength=0.3)  # Get related concepts
agent.vp_runtime.compute_from_state(state)  # Get VP value

HTTP Endpoints (--mode serve)

🔧 Dependencies

Minimal requirements:

torch>=2.0
numpy

Optional for HTTP serving:

flask  # or fastapi + uvicorn

Optional for Gymnasium:

gymnasium

📦 Re-Exporting

The cocoon can re-export its neural models:

from cocoon import CocoonAgent

agent = CocoonAgent()

# Export to ONNX for deployment
agent.export_onnx("brain.onnx")

# Export to TorchScript for C++/LibTorch
agent.export_torchscript("brain.pt")

# Save updated weights after learning
torch.save(agent.brain.state_dict(), "updated_weights.pth")

🦋 About the Butterfly System

This cocoon was generated by the Butterfly Convergence Engine - a neuro-symbolic AI framework that combines:

• —Neural networks for pattern recognition and action selection
• —Atomic language for grounded semantic understanding
• —VP regulation (Vigilance × Plasticity) for adaptive attention
• —Knowledge webs for relational reasoning
• —Distributed ensembles for robust decision-making

Learn more: Convergence Engine on GitHub

Generated by 🦋 Butterfly Agent Compiler