# Home · Compitum Wiki

## Quick-Scan Infobox

| 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 |

<hr>

## 1) What Compitum Is

<a href="https://raw.githubusercontent.com/PaulTiffany/compitum/main/assets/tess.mp4"
   target="_blank" rel="noopener">
  <img src="https://raw.githubusercontent.com/PaulTiffany/compitum/main/assets/tess-poster.jpg"
       alt="Routing flow preview — click to play the MP4 in a new tab" width="210">
</a>

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.

<hr>

## 2) Five-Minute Quickstart

### Code (minimal example)

<!-- NOTEBOOK:auto_home_1:BEGIN -->
[Open on GitHub](https://github.com/PaulTiffany/compitum/blob/main/notebooks/wiki_snippets/Home/auto_home_1.ipynb) | [Open in nbviewer](https://nbviewer.org/github/PaulTiffany/compitum/blob/main/notebooks/wiki_snippets/Home/auto_home_1.ipynb) | [Launch in Binder](https://mybinder.org/v2/gh/PaulTiffany/compitum/main?labpath=notebooks/wiki_snippets/Home/auto_home_1.ipynb)

# Snippet from Home.md



```python
# 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.

```

<!-- NOTEBOOK:auto_home_1:END -->
### Expected output (trimmed)

```json
{
  "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.

<hr>

## 3) The One-Page Picture

**Alt text:** Flow from prompt to decision with observers supplying signals; constraints bound the optimization; certificate explains the outcome.

```mermaid
%% 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.

<hr>

## 4) Montessori Parallel (For Educators)

**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.

```mermaid
%% 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?

<hr>

## 5) Where To Go Next

- **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

<hr>

## 6) Terminology (used consistently in this wiki)

- **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.

<hr>

## 7) Known Limitations

- 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.

<hr>

## 8) Reproducibility Notes

- 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.

<hr>

*Last updated: 2025-11-07 · Compitum Wiki Home*