cambium-ai 0.1.0

Cambium — a bounded-agent behavioral coherence engine. The deterministic spine decides what to ask. The model only answers. The eval framework decides whether the answer counted.

Cambium

The thin living layer where coherence is generated.

The deterministic spine decides what to ask. The model only answers. The eval framework decides whether the answer counted.

Cambium is a bounded-agent behavioral coherence engine. It measures the gap between what a person says they value and what their revealed behavior shows, in production, continuously, with audit-grade provenance.

In a tree, the cambium is the thin layer of living cells under the bark where growth actually happens. The heartwood is structural. Timber is the harvested useful material. The cambium is where something is becoming something else. That's the part of the system this library lives in.

What's here

A complete reference implementation:

• Three bounded Claude call sites — classifier, reasoner, synthesizer — wrapped in a deterministic spine with hard guardrails.
• Multi-domain plug-in architecture — finance is plugin #1; the same machinery handles health, career, sustainability, etc.
• Service-layer abstraction — every configurable parameter flows through a single CambiumService Protocol with four implementations (in-memory, YAML, Timber, Ranger).
• Full eval framework — golden-set runner, deterministic judges, LLM judges with multi-judge consensus, calibration, active-learning loop, drift detection, regression CI gates.
• Bounded-agent capabilities — constitutional self-critique, signed provenance certificates, content-hashed manifests, shadow A/B with paired statistics, MCP server interface, OpenTelemetry hooks, A2UI output.
• Tight integration with the OakQuant platform — Timber (persistence, rules, encryption), Grove (workflow orchestration), Ranger (operator console), Sky (frontend).
• Production-grade golden seed dataset — 60 hand-labeled examples across the three call sites for the finance domain.

Quick start

# Build/dev — Poetry, matches timber-common's publishing pattern.
poetry install
poetry run python examples/basic_pipeline.py

Or with the production stack:

poetry install --with timber,mcp,otel
export CAMBIUM_SERVICE_IMPL=timber
export ANTHROPIC_API_KEY=...
poetry run python examples/eval_run.py

Note: Cambium consumes timber-common's actual public surface (from common.*, not from timber_common.*). The YAML configs in timber_configs/ conform to timber-common's models:-list factory format. See docs/timber-integration.md.

Mental model

                    ┌──────────────────────┐
                    │   IdentityProfile    │  ← stated identity
                    │   (DNA assessment)   │     (16-screen capture)
                    └──────────┬───────────┘
                               │
   ┌───────────────────────────┼───────────────────────────┐
   │                           ▼                           │
   │                ┌─────────────────────┐                │
   │                │   Deterministic     │                │
   │                │       Spine         │                │
   │                │                     │                │
   │                │  redact → classify  │                │
   │                │  → baseline → ask   │                │
   │                │  → clip → validate  │                │
   │                │  → trace → emit     │                │
   │                └──────────┬──────────┘                │
   │                           │                           │
   │              ┌────────────┼────────────┐              │
   │              ▼            ▼            ▼              │
   │       ┌─────────┐  ┌──────────┐  ┌────────────┐       │
   │       │Classify │  │ Reasoner │  │Synthesizer │       │
   │       │ (model) │  │ (model)  │  │  (model)   │       │
   │       └─────────┘  └──────────┘  └────────────┘       │
   │                           │                           │
   │                           ▼                           │
   │                ┌─────────────────────┐                │
   │                │     A2UIDocument    │  → Sky, email, │
   │                │  + ProvenanceCert   │     mobile,    │
   │                └─────────────────────┘     voice      │
   │                                                       │
   │   ┌────────────────── traces ─────────────────────┐   │
   │   │  Append-only JSONL → Timber → audit, eval     │   │
   │   └───────────────────────────────────────────────┘   │
   └───────────────────────────────────────────────────────┘
              ▲                                ▲
              │                                │
        ┌─────┴───────┐                  ┌─────┴──────┐
        │BehavioralEvt│ ← revealed       │  Grove     │
        │  stream     │   behavior       │ workflow   │
        └─────────────┘  (Plaid, …)      │ events:    │
                                         │ HITL,      │
                                         │ sagas,     │
                                         │ handoffs   │
                                         └────────────┘

The picture is deliberately small. Three call sites. One spine. A shared service. Domain plugs in via YAML + 4 Python files. Everything else is around making those parts trustworthy in production.

Why this exists

Most "agentic" systems today give models too much latitude (free-form tool use, unbounded chains, no eval) or too little (single-prompt black boxes with no guardrails). Cambium occupies the third position: bounded agency with strong evaluation. The model has genuine latitude inside narrow questions; the spine decides what to ask and how to use the answer; the eval framework decides whether the manifest of (prompts + models + rules) can promote.

This is the production form of pattern 13 — Creative Sandbox with Deterministic Exit — and it doubles as a reference implementation for patterns 1 (Prompt Chaining), 5 (Evaluator-Optimizer), and 10 (Guardrail Wrap).

Where to read next

If you want to	Read
Get the architecture overview	docs/ARCHITECTURE.md
Understand the call-site contract	docs/ARCHITECTURE.md + cambium/skills/developer/cambium-add-call-site/SKILL.md
Add a new domain	docs/multi-domain-architecture.md + cambium/skills/developer/cambium-add-domain/SKILL.md
See how the 13 agentic patterns map	docs/agentic-patterns.md
Integrate with Timber	docs/timber-integration.md
Position in OakQuant	docs/oakquant-integration.md

License

Apache 2.0 for the library. CC-BY 4.0 for the golden seed datasets.

Author

Pumulo Sikaneta. Founder, OakQuant AI (Revelar Inc.). Author of The Cost of the Machine trilogy on AI governance. Cambium is part of the broader research program described in those books: that the meaningful question for agentic AI is not what the tools can do but who governs the work.