Repository navigation
Home
| Aspect | Details |
|---|---|
| Target user | Educators designing principled activities; developers building stable, auditable routing systems |
| Core goal | Explain what Compitum is, how it works, and where to start—without requiring RL background |
| Time to first insight | 5 minutes: run the quickstart and read the certificate |
| What you get | A router that makes verifiable choices using mechanistic signals (free energy, constraint slacks, coherence) and clear certificates |
| Limitations | Early-stage research code; small set of observers out of the box; performance depends on your embedding/model pool |
| Live resources | Docs site and repo links on the project README |
Compitum is a bounded model router. Like "Tess" in the generative analogy (click the image to download the video), Compitum chooses a model for a prompt by solving a small, constrained problem with local signals instead of judge-dependent rewards.
- Signals (measured every step): free energy change, constraint slacks, entropy, and a geometry-based coherence score.
- Constraints: latency, cost, diversity, safety, or your domain rules, encoded as linear bounds.
- Certificate: a machine-readable explanation of the decision (what was selected, why, and what would change if a constraint were relaxed—its shadow price).
This wiki teaches the ideas and how to use them, one page at a time.
Open on GitHub | Open in nbviewer | Launch in Binder
# Compitum's interface is CLI-first. Install the package, then route a prompt
# and read its certificate straight from the command line.
!pip install -e . -q
!compitum route --prompt "Summarize the key differences between mitosis and meiosis for grade 9." --trace --verbose
# Constraints are linear bounds (A x <= b) over a small feature set (latency
# class, cost class, PII level, region), loaded from YAML -- see
# configs/constraints_us_default.yaml in the repo for the default, or pass
# your own with --constraints path/to/file.yaml.{
"selected_model": "model_B",
"utility": 7.9,
"signals": {
"free_energy": -0.18,
"coherence": -0.9,
"entropy": 1.7
},
"constraints": {
"latency_s": {"bound": 2.0, "actual": 1.6, "slack": 0.4},
"cost_usd": {"bound": 0.01, "actual": 0.008, "slack": 0.002},
"diversity_k": {"bound": 2, "actual": 2, "slack": 0}
},
"shadow_price": {
"cost_usd": 0.62
},
"boundary_flag": false
}How to read this: The choice met all constraints. The shadow price on cost is moderate, meaning loosening cost slightly might yield more utility.
Alt text: Flow from prompt to decision with observers supplying signals; constraints bound the optimization; certificate explains the outcome.
%% GitHub wiki-safe: <=15 nodes; palette applied in styles; tested for rendering in GitHub Markdown
graph TB
A["Prompt"] --> B["Embed prompt"]
B --> C["Evaluate candidate models"]
C --> D["Collect signals<br/> (free energy, coherence, entropy)"]
D --> E["Check constraints<br/> (latency, cost, diversity)"]
E --> F["Select model"]
F --> G["Certificate<br/> (decision + shadow price)"]
subgraph Obs["Observers (signals)"]
O1["Energy drift"]
O2["KDE coherence"]
O3["Entropy"]
O4["Boundary check"]
end
D --- O1
D --- O2
D --- O3
D --- O4
style Obs fill:#fff3e0,stroke:#ef6c00,stroke-width:2px %% Signals
style A fill:#e3f2fd,stroke:#1565c0 %% Learning
style B fill:#e3f2fd,stroke:#1565c0
style C fill:#e3f2fd,stroke:#1565c0
style D fill:#fff3e0,stroke:#ef6c00
style E fill:#e8f5e9,stroke:#2e7d32 %% Control
style F fill:#e8f5e9,stroke:#2e7d32
style G fill:#fce4ec,stroke:#c2185b %% Output
Caption: Signals are local and mechanistic; constraints bound the search; the certificate makes the decision auditable.
Montessori: “Prepared environment” with control of error—materials and task design make the next step obvious.
Compitum: A prepared geometric environment—an SPD metric shapes what is “near,” and constraints define safe exploration. Signals mark progress, not a grader.
Alt text: Side-by-side mapping from classroom ideas to router concepts.
%% GitHub wiki-safe: simple LR graph; consistent palette
graph LR
subgraph Classroom
M1["Prepared environment"]
M2["Control of error"]
M3["Freedom within limits"]
end
subgraph Router
R1["SPD metric (what counts as near)"]
R2["Signals (free energy, coherence)"]
R3["Constraints (latency, cost, diversity)"]
end
M1 --> R1
M2 --> R2
M3 --> R3
style Classroom fill:#e8f5e9,stroke:#2e7d32
style Router fill:#e3f2fd,stroke:#1565c0
Classroom starter: Route a short-answer prompt. Ask students to interpret the certificate: Which constraint was tight? What does the shadow price suggest?
- Getting Started — install, run the quick demo, and read your first certificate.
- Usage Guide — routing options, observers, and outputs.
- Configuration — constraints, temperature, and SPD metric settings.
- Philosophy — why local signals and bounded control are preferable to judge-dependent rewards.
- Cookbook — worked examples (education, summarization, tool use).
- Verification — invariants and tests; how we check the signals.
- Glossary — definitions for terms used throughout the docs.
Time estimates
• 5–10 minutes: Quickstart + certificate
• 20–30 minutes: Configure constraints and re-route a small set
• 45–60 minutes: Classroom pilot or integration into a simple app
- shadow price — marginal utility gained if a bound is relaxed.
- free energy — the scalar we try to decrease step-by-step.
- SPD metric — a positive-definite matrix that defines distance in embedding space.
- certificate — the machine-readable explanation of a routing decision.
- Certificates explain the router’s choice, not the internals of the external models you route to.
- Coherence uses embedding geometry; results depend on the embedding model you select.
- Current observers focus on text tasks; domain-specific observers are encouraged and documented in the extension guide.
- Set random seeds in your embedding or scoring layers when available.
- Log certificates to a directory per run.
- Keep constraint files in version control; compare shadow price trends across runs.
Last updated: 2025-11-07 · Compitum Wiki Home