Skip to content

v1.8.0 — Teaching Colony runs on real Claude

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 14 Apr 15:50
· 5 commits to main since this release

What's new in v1.8.0

First release where the Teaching Colony actually runs on a real language model. v1.8.0 adds an interactive REPL and fills in the Claude Code adapter's live-mode dispatch path with real Anthropic API calls, prompt caching, and model tiering. A reader can now type ask what do you know about beekeeping at a colony prompt and receive a real Claude answer grounded in the seeded primer — not a canned mock string.

This is the first release of the Agent Colony pattern that costs money to use. The README section explains the envelope in detail: roughly $2-5 for a full 500,000-token session with the recommended Sonnet/Haiku model mix, after prompt caching kicks in.

Why v1.8 as its own increment

v1.6.0 shipped a 4,300-line artefact where the headline claim was false on the happy path (see v1.7.0 release notes). That review is still fresh. v1.8.0 ships the live-mode dispatch path on its own — and nothing else — so it can be verified end-to-end against a real model before v1.9 layers research walks on top. v2.0 will add the full command set, session persistence, and cost enforcement. Each increment gets its own commit-test-tag-release cycle.

What v1.8.0 adds

  • Interactive REPL — examples/teaching_colony/chat.py. asyncio-based. Commands: ask, help, quit. Forward-looking v1.9+ commands (research, status, cancel, knows, capabilities) route helpfully to "coming in v1.9+" messages rather than tracebacks.
  • Live-mode dispatch_agent in the Claude Code substrate:
    • Prompt caching — cache_control: ephemeral on the Mirror system prompt. Repeat dispatches of the same agent within 5 minutes pay ~10% of the system-prompt cost. The REPL's budget display shows cache-read tokens as a separate counter so you can see it work.
    • Model tiering — Sonnet for Teacher and Librarian (real pedagogical work); Haiku for Registry, Chronicler, Equilibrium, Sentinel (small structured decisions).
    • Prose-vs-JSON prompt discipline — Teacher and Librarian get pedagogical prompts; the four supervisory agents get JSON-strict prompts with explicit schemas and a one-retry fallback for malformed responses.
  • Session budget — examples/teaching_colony/colony/logic/budget.py. Budget class tracking all four Anthropic usage counters. TEACHING_COLONY_TOKEN_BUDGET env var, default 500,000, safe fallback on invalid values. 80% warning, 100% hard stop for new dispatches.
  • Three new test modules — 36 new tests covering the Budget class (27), REPL smoke in mock mode (9), and gated live-Claude dispatch (3). The live tests require ANTHROPIC_API_KEY and run with pytest -m live; they prove that prompt caching actually hits on the second dispatch (cache_read_input_tokens > 0).

Test results

72 passed, 3 deselected (live tests), 2 xfailed

Every v1.7.0 mock-mode test still passes. The 2 xfails are unchanged — live-mode Managed Agents dispatch_agent and update_mirror, still deferred until research-preview allowlist.

How to try it

cd examples/teaching_colony
pip install -r requirements.txt

# Offline, no cost, good for seeing the mechanics
python -m examples.teaching_colony.chat --mock

# Live mode — real Claude, real tokens, ~$0.15 for ~30 questions
export ANTHROPIC_API_KEY=...
python -m examples.teaching_colony.chat

# Tighter budget for cost discipline
TEACHING_COLONY_TOKEN_BUDGET=50000 python -m examples.teaching_colony.chat

Known gaps after v1.8.0

  • No research walks yet. research, status, cancel, knows, capabilities are all v1.9+.
  • No tool use. fetch_url, extract_links, score_links are v1.9+.
  • No background concurrency. Research walks will run concurrently in v1.9; v1.8 has one synchronous dispatch per ask.
  • No capability graduation yet. v1.9 wires Librarian's coverage check to the existing §7 Comprehension Contract path.
  • Retrieval is single-shot keyword match, not real RAG. Fine while the KB has one entry; replaced in v2.0 when the KB has dozens.
  • REPL dispatches only to Teacher. ask sentinel co-sign this kind of syntax is v2.0.
  • Tokens display is post-dispatch, not streaming. A streaming token counter is v2.0 polish.
  • Managed Agents live-mode dispatch_agent and update_mirror still raise NotImplementedError (2 xfails, unchanged from v1.7.0).

Roadmap updated

The repo roadmap now reads:

Version Status Focus
v1.8.0 ✅ released 2026-04-14 Live-mode dispatch, prompt caching, REPL foundation
v1.9.0 planned Research walks with hop budget, tool use, G3 graduation
v2.0.0 planned Full interactive Teaching Colony — reference implementation
v2.1+ planned Live-mode Managed Agents, Newcomer diagrams, peer feedback

Cite as:

Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.8.0). https://github.com/DavidROliverBA/agent-colony-pattern