cocapn-core

Maximum capability in minimum lines. Single-process, async, self-evolving.

Cocapn Fleet v3.1 — a fully async coordination system for multi-agent knowledge crystallization.

Architecture

One import. One port. One truth.

cocapn/
├── models.py      — Pydantic v2 models (Agent, Tile, Stream, Task, Rule)
├── engine.py      — Fleet engine (connect, submit, batch, evolve, monitor)
├── storage.py     — JSONL persistence with field indexing
├── grammar.py     — Sanitized rule engine (safe eval, action whitelist)
├── server.py      — FastAPI endpoints (/connect, /submit, /interact, /task)
├── evolve.py      — Grammar-driven evolution
├── monitor.py     — Stream divergence detection
└── validation_loop.py — Assertion-based tile quality scoring

Install

pip install cocapn

Quick Start

from cocapn import Fleet

fleet = Fleet(storage_dir="./plato")
await fleet.connect("my_agent", "scout")
tile = await fleet.submit("my_agent", "What is DPDK?", "DPDK is...", domain="networking")
status = await fleet.status()

API Endpoints

# Start server
uvicorn cocapn.server:app --port 4042

# Connect agent
curl -X POST http://localhost:4042/connect -H "Content-Type: application/json" \
  -d '{"agent": "bot1", "job": "critic"}'

# Submit tile
curl -X POST http://localhost:4042/submit -H "Content-Type: application/json" \
  -d '{"agent": "bot1", "question": "Q?", "answer": "A!", "domain": "code"}'

# Batch submit
curl -X POST http://localhost:4042/submit/batch -H "Content-Type: application/json" \
  -d '{"agent": "bot1", "tiles": [...]}'

# Health check
curl http://localhost:4042/health

Performance

Operation	Throughput
Stream observe	800K ops/s
Batch submit (100)	535K ops/s
Grammar eval	232K ops/s
Tile submit	128K ops/s
Agent connect	61K ops/s

Tools

• tools/import_tiles.py — Import PLATO tile corpus into cocapn-core
• tools/plato_ask.py — Query tiles from CLI (pip install plato-ask)
• tools/swiss_tournament.py — ELO-based tile quality ranking
• tools/fix_pypi_packages.py — Mass-fix broken PyPI packages
• tools/bench_cocapn.py — Performance benchmarks

Testing

pip install cocapn[dev]
pytest tests/ -v

19 extended tests + 21 original tests = 40 total, all passing.

License

MIT