cocapn — Repo-First Agent Infrastructure

📚 Documentation: PLUG_AND_PLAY.md · GETTING_STARTED.md · ARCHITECTURE.md · API_REFERENCE.md · LOW_LEVEL.md

Grow an agent inside a repo. Tiles capture knowledge, rooms train, the flywheel compounds.

What This Gives You

• Tiles — atomic knowledge units that remember every Q&A, tagged and versioned
• Rooms — self-training collections of tiles that get smarter over time
• Flywheel — every exchange improves the next: responses feed tiles, tiles improve rooms, rooms sharpen answers
• Interactive agent — python agent.py starts a CLI that learns from you in real time
• Zero infra — pure Python, data lives in JSONL files next to your code

Quick Start

pip install cocapn

# Start talking to your agent — it learns from every exchange
cocapn

# Teach it directly
cocapn --teach "What is PLATO?" "The pedagogical framework for fleet curriculum"

# Check how smart it's gotten
cocapn --status

Or use it as a library:

from cocapn import CocapnAgent, Tile, Room, Flywheel

agent = CocapnAgent(name="my-agent")
response = agent.ask("What is the fleet?")
agent.teach("What is the fleet?", "A coordinated group of AI agents")
agent.save()  # Persists tiles and rooms

API Reference

Tile

Tile(question="Q", answer="A", domain="general", confidence=0.5, tags=["tag"])

Atomic knowledge unit. Tracks usage count, success count, version, and confidence.

Room

Room(name="python", description="Python knowledge", store=tile_store)

A self-training collection of tiles. Feed it Q&A pairs, ask questions — it ranks tiles by relevance and learns from outcomes.

Flywheel

Flywheel(data_dir="data")

The compounding engine. Manages rooms, routes questions, tracks which answers worked.

CocapnAgent

CocapnAgent(name="agent", data_dir="data")

High-level interface: ask(), teach(), status(), save().

How It Fits

• OpenConstruct Documentation — ecosystem-wide docs and guides

Cocapn is the foundation of the SuperInstance fleet:

• cocapn-sdk — One API key, any AI model
• cocapn-cli — Fleet terminal formatting (Rust)
• cocapn-explain — Agent explainability
• cocapn-health-rs — Fleet health monitoring (Rust)
• cocapn-lessons — Trial-based learning from failures
• agent-forge — Universal git-agent framework

Testing

pip install pytest
pytest tests/

Installation

pip install cocapn

Requires Python 3.10+. MIT license.

Wave-69 — sxc1 validator mirror

cocapn is the fleet's validator mirror for the sxc1 cell-exchange dialect (byte-compatible with the exoj JS implementation). Two cell kinds, two disciplines: generator cells emit concise claims; validator cells (like cocapn) re-derive every hash, re-read the spec seal, and answer only in the verdict vocabulary COMPILED | INDETERMINATE. An envelope = {v, seq, cell, body, seal} with id = sha256("sxc1:"+seq+":"+prev+":"+canonicalJSON(cell+body+seal)), genesis prev 64×"0". Fail-closed named codes, in fixed order: E_SXC_FIELD (structure/vocabulary/floats) → E_SXC_SEQ → E_SXC_PREV → E_SXC_HASH → E_SXC_SPEC; the mirror gate adds E_SPEC_SHA_MISSING / E_SPEC_SHA_MALFORMED (cross-repo rule: foreign spec_sha is checked for presence + hex shape, never equality).

python3 -m cocapn.sxc1 ingest  from-fleet/sxc1/<file>      # verify; COMPILED <id> or INDETERMINATE <code> (exit 1)
python3 -m cocapn.sxc1 verdict from-fleet/sxc1/<file> --verdict COMPILED --codes CODE1,CODE2

Pathway: exoj emits → from-fleet/sxc1/ intake → verify → sealed verdicts in for-fleet/sxc1/ (kind validator, repo cocapn, cocapn's own spec_sha); quilt-dba stitches the chain. cocapn never mutates another repo's state — it answers.