Metadata-Version: 2.4
Name: cairn-coordination
Version: 0.3.0
Summary: Token-efficient, verifiable multi-agent AI coordination — passive stigmergic blackboard + minimal per-agent context, with an optional on-chain (ERC-8004 identity + coordination receipts) layer.
Author: Tağmaç Çankaya
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/echo-toolkit/cairn
Project-URL: Repository, https://github.com/echo-toolkit/cairn
Keywords: multi-agent,agents,llm,coordination,token-efficiency,blackboard,stigmergy,erc-8004,celo,web3,agent-economy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: web3
Requires-Dist: web3<8,>=7; extra == "web3"
Requires-Dist: eth-account; extra == "web3"
Provides-Extra: langchain
Requires-Dist: langchain-core; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai; extra == "crewai"
Provides-Extra: dev
Requires-Dist: web3<8,>=7; extra == "dev"
Requires-Dist: eth-account; extra == "dev"
Requires-Dist: py-solc-x; extra == "dev"
Requires-Dist: eth-tester; extra == "dev"
Requires-Dist: py-evm; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Cairn 🪨

**A free AGPLv3 coordination layer that lets multiple AI agents work together without burning the token budget — by coordinating through a passive shared blackboard and minimal per-agent context, instead of conversation. Optionally, it makes that coordination *verifiable* on-chain.**

> A *cairn* is a pile of stones travellers stack to mark a path for those behind — guidance left without speaking. That is Cairn's mechanism: agents leave traces, not messages.

---

## The problem

Multi-agent AI systems fail in production mostly on **cost**: agents talk to each other in unbounded loops, each carrying the others' full transcripts, until the context — and the bill — explodes. The dominant tooling is **reactive** (budget caps, circuit-breakers, observability dashboards): it watches the meter and pulls the plug after the fact. It does not change the architecture that generates the spend.

**Cairn is preventive** — it removes the structure that causes the explosion.

## Three mechanisms (each measured in real operation)

1. **Minimal-context workers** — each agent loads only a small task-scoped context, not the full project history. Measured: always-loaded context drops ~32K → ~0.8K tokens per agent-turn.
2. **Passive stigmergic blackboard** — agents leave short traces (claims, findings, status) in one small shared file and read each other's traces. **No agent-to-agent conversation channel.** Coordination emerges from a shared filter, not chatter.
3. **Gardener orchestrator** — a single supervisor that distills emergent findings and times the close (a resonance valve), intervening only on pathology, never micro-managing.

## Measured result (dogfooded, controlled A/B)

On an identical agent task — same model, only the context architecture changed:

| | naive full-context | minimal + blackboard | reduction |
|---|---:|---:|---:|
| billable input tokens | 488,477 | 222,680 | **54%** |
| short-run cost (illustrative) | $4.13 | $1.44 | **65%** |

The throughput / rate-limit win persists even where prompt caching shrinks the dollar delta. The benchmark harness is published so the number is **reproducible — and falsifiable** — on your own workload.

## Quickstart

```bash
pip install cairn-coordination          # core — stdlib-only, zero deps   (import name: cairn)
pip install "cairn-coordination[web3]"   # + the on-chain layer (ERC-8004 identity + receipts)
```
On [PyPI](https://pypi.org/project/cairn-coordination/) (the import name is `cairn`; `cairn` was taken).

Framework-agnostic: you supply `agent_fn(ctx)` and make your own model call inside it. Cairn calls no LLM.

```python
from cairn import run_swarm, Worker, Trace

def agent_fn(ctx):
    # ctx.task = this agent's scope; ctx.board = a compact digest of others' traces (minimal!)
    # call your model, return a Trace — or return None to go idle (self-terminate)
    return Trace(agent=ctx.agent, kind="finding", text="...", value=2.0)

result = run_swarm(agent_fn, [Worker("a", "angle A"), Worker("b", "angle B")])
print(result.closed_reason, result.total_value())
```

`python examples/selftest.py` runs an offline, dependency-free demo of the whole loop.

### Already on LangChain / CrewAI?

Coordinate your existing framework agents through Cairn's blackboard — minimal per-agent context instead of re-passing the full transcript:

```python
from cairn import run_swarm, Worker
from cairn.adapters import from_langchain   # or: from_crewai, or as_worker_fn for any invoke()

run_swarm(from_langchain(my_chat_model_or_graph),
          [Worker("a", "angle A"), Worker("b", "angle B")])
```

`as_worker_fn(invoke)` wraps *any* `invoke(prompt) -> str` callable. The adapters import no framework until a wrapped agent runs (`pip install "cairn-coordination[langchain]"` / `[crewai]`). Offline demo: `python examples/adapter_demo.py`.

---

## Verifiable coordination (optional web3 layer)

Token-efficiency commoditizes; **verifiability** does not. When agents owned by *different parties* coordinate, they need on-chain **identity**, **receipts**, and (optionally) **value rails**. Cairn adds these as an **additive, off-by-default layer** — `import cairn` stays dependency-free, and with no adapter the core runs exactly as before.

```python
from cairn import run_swarm, Worker
from cairn.web3.celo import CeloEVMAdapter

chain = CeloEVMAdapter(private_key=KEY, receipts_addr=RECEIPTS)
run_swarm(agent_fn, workers, receipt=chain)   # emits one verifiable on-chain receipt per run
```

- **Receipts** — one verifiable on-chain record per coordination run (run id + state hash).
- **Identity** — each agent gets a verifiable identity via the pre-deployed **[ERC-8004](https://eips.ethereum.org/EIPS/eip-8004)** registries (identity is config, not a deploy).
- **Payment** — optional native-CELO / ERC-20 (cUSD, USDC) transfers between agents.

**Live on Celo mainnet** (independently verifiable):

| Capability | Proof |
|---|---|
| Coordination receipt | [tx `0xeea84ea9…`](https://celoscan.io/tx/0xeea84ea902a1c6a26ca484a4b53d22e951d976cb2299fccd284688e890a9deec) |
| Agent identity (ERC-8004) | [agentId 9211](https://celoscan.io/token/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432?a=9211) |

The chain layer is chain-agnostic by design (a clean adapter interface); Celo/EVM is the first implementation.

---

## Status

The core library (blackboard + minimal-context workers + gardener/valve) and the verifiable-coordination layer are **here and working** — receipts + identity proven on Celo mainnet, payment on testnet. Funding (NGI Zero Commons / alternatives) is in progress to sustain maintenance.

- Framework-agnostic — coordinates agents built on LangGraph / CrewAI / a plain script.
- Composes with cost tooling (LiteLLM, Langfuse) — Cairn lowers the baseline they cap/observe.
- Sibling of [Echo Toolkit](https://github.com/echo-toolkit/echo) — same operator, same commons philosophy, independent projects.

## License

[AGPLv3](LICENSE). The network-use clause ensures hosted use contributes back. Commercial relicensing available for B2B integrations that cannot accept AGPL — revenue reinvested in maintenance.

## Origin

Built by [Tağmaç Çankaya](https://khashif.run) (Lefkoşa, Cyprus / EU) out of a felt failure: a full-context headless agent swarm that exhausted its budget almost instantly. Cairn is the rebuild — measured, minimal, and given back.
