Metadata-Version: 2.3
Name: cambium-ai
Version: 0.2.1
Summary: 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.
License: Apache-2.0
Keywords: ai,agents,agentic-ai,ai-governance,behavioral-finance,evaluation,anthropic,claude,mcp,oakquant
Author: Pumulo Sikaneta
Author-email: pumulo@oakquant.ai
Maintainer: Pumulo Sikaneta
Maintainer-email: pumulo@oakquant.ai
Requires-Python: >=3.13,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Provides-Extra: claude
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: anthropic (>=0.40,<2.0) ; extra == "claude"
Requires-Dist: cryptography (>=46.0.0,<47.0.0)
Requires-Dist: pydantic (>=2.5.0,<3.0.0)
Project-URL: Bug Tracker, https://github.com/oakquant-ai/cambium/issues
Project-URL: Changelog, https://github.com/oakquant-ai/cambium/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/oakquant-ai/cambium/tree/main/docs
Project-URL: Homepage, https://github.com/oakquant-ai/cambium
Project-URL: Repository, https://github.com/oakquant-ai/cambium
Description-Content-Type: text/markdown

# 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

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

Or with the production stack:

```bash
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](docs/agentic-patterns.md)
— 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](docs/ARCHITECTURE.md) |
| Understand the call-site contract | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) + `cambium/skills/developer/cambium-add-call-site/SKILL.md` |
| Add a new domain | [docs/multi-domain-architecture.md](docs/multi-domain-architecture.md) + `cambium/skills/developer/cambium-add-domain/SKILL.md` |
| See how the 13 agentic patterns map | [docs/agentic-patterns.md](docs/agentic-patterns.md) |
| Integrate with Timber | [docs/timber-integration.md](docs/timber-integration.md) |
| Position in OakQuant | [docs/oakquant-integration.md](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.

