Repository navigation
Getting Started
Note: Notebooks are available in the repository.
- Notebooks folder: https://github.com/PaulTiffany/compitum/tree/main/notebooks
Quick-Scan Infobox
| Aspect | Details |
|--------|---------|
| Target user | New educators and developers; Python basics assumed |
| Core goal | Set up a local environment, run a demo route, and review the certificate output for initial understanding |
| Time to first route | 10 minutes: clone, install, demo, inspect JSON |
| Key analogy | Preparing a lab station: assemble components, run the process, note observations (signals) |
| Prerequisites | Git, Python 3.10+; optional: text editor for JSON viewing |
| Known limitation | Installation assumes Unix-like shell; Windows users adjust activation commands |
This sequence guides from setup to first output, with each step building toward a complete route.
graph LR
A[Clone repository] --> B[Set up virtual environment]
B --> C[Install dependencies]
C --> D[Run demo route]
D --> E[Inspect certificate]
E --> F[Review insights]
style A fill:#e3f2fd,stroke:#01579b
style B fill:#e8f5e9,stroke:#1b5e20
style C fill:#fff3e0,stroke:#ef6c00
style D fill:#fce4ec,stroke:#c2185b
style E fill:#e3f2fd,stroke:#01579b
style F fill:#e8f5e9,stroke:#1b5e20
Caption: Linear flow from clone to insights, highlighting key actions. Alt text: Horizontal graph with six nodes.
Follow these steps to achieve a working route; if a step fails, refer to troubleshooting.
Onboarding prioritizes reproducibility: editable installation for development, command-line entry for simplicity, and trace-enabled routes to reveal signals early.
The router processes prompts through embedding, filtering, minimization, and certification.
flowchart TD
subgraph Input
A[User prompt] --> B[Embedding layer]
B --> C[D=35 space]
end
subgraph Router["Router core"]
C --> D[Constraint filter]
D --> E["A x ≤ b"]
E --> F[Free energy minimization]
F --> G["E = α q - Σ β c"]
end
subgraph Output
G --> H[Model selection]
H --> I[Certificate JSON]
I --> J[Quality scalars]
I --> K[Feasibility flags]
I --> L[Boundary diagnostics]
I --> M[Drift signal]
end
style Router fill:#e3f2fd,stroke:#01579b
style Input fill:#e8f5e9,stroke:#1b5e20
style Output fill:#fff3e0,stroke:#ef6c00
Caption: Flow from input to output, showing constraint and energy steps. Alt text: Flowchart with three subgraphs (Input, Router, Output).
The process isolates dependencies in a virtual environment.
sequenceDiagram
participant User
participant Venv as Virtual environment
participant Pip as Package manager
participant Compitum as Compitum system
User->>Venv: Create and activate
Venv->>User: Isolated environment ready
User->>Pip: pip install -e ".[dev]"
Pip->>Compitum: Install core dependencies
Pip->>Compitum: Install dev tools
Compitum->>User: Ready for development
Caption: Sequence of installation actions. Alt text: Vertical sequence with four participants and six messages.
Dependencies include numpy/scipy for metrics, yaml for configurations, and pytest for checks. The editable mode (-e) links source changes directly.
The demo embeds the prompt, applies constraints, minimizes free energy, and writes a certificate with scalars, flags, diagnostics, and drift.
Command-line demo
compitum route --prompt "Prove binomial via generating functions." --trace > demo_trace.json
Code detail: parse your first certificate
import json
from compitum.boundary import is_boundary
with open("demo_trace.json", "r", encoding="utf-8") as f:
cert = json.load(f)
print(f"Free energy: {cert['free_energy']:.3f} | Feasible: {cert['feasible']}")
if is_boundary(cert['utilities']):
print("Boundary detected — review for adjustments.")Expected output
Free energy: -0.234 | Feasible: True
Note: If boundary is flagged, utilities show close values; adjust temperature in config.
Getting Started (rendered)
Open on GitHub | Open in nbviewer | Launch in Binder
This notebook helps you verify your environment and shows a minimal import of the Compitum package.
- Repository: https://github.com/PaulTiffany/compitum
- Wiki: https://github.com/PaulTiffany/compitum/wiki
From the repository root, install Jupyter and Compitum in editable mode (once per environment):
# Windows (PowerShell)
python -m venv .venv
.venv\\Scripts\\Activate.ps1
pip install --upgrade pip
pip install jupyter
pip install -e .
python -m ipykernel install --user --name compitum-venv --display-name "Python (compitum)"
jupyter notebookAfter activation, select the "Python (compitum)" kernel for this notebook.
# Python and pip versions
import sys, subprocess
print(sys.version)
subprocess.run([sys.executable, '-m', 'pip', '--version'], check=False)3.10.20 (main, Jun 16 2026, 21:01:32) [GCC 13.3.0]
pip 26.1.2 from /opt/hostedtoolcache/Python/3.10.20/x64/lib/python3.10/site-packages/pip (python 3.10)
CompletedProcess(args=['/opt/hostedtoolcache/Python/3.10.20/x64/bin/python', '-m', 'pip', '--version'], returncode=0)
# Minimal Compitum import and version check
import compitum
print('Compitum version:', getattr(compitum, '__version__', 'unknown'))
print('Compitum modules:', compitum.__all__)Compitum version: 0.2.0
Compitum modules: ['router', 'metric', 'constraints', 'coherence', 'boundary', 'control', 'energy']
- Explore API docs in
src/compitum/. - Check
examples/for scripts that use the router and metrics. - See the Wiki for walkthroughs and deeper explanations.
Montessori parallel: as with cylinder blocks, initial mismatches prompt careful observation and adjustment. Repeated use builds reliable form recognition and independence.
Time estimate: 5–10 minutes to first insight (install, run one demo, inspect JSON).
-
CLI not found: ensure virtual environment is active and compitum is installed with
pip install -e .. -
Import errors: reinstall in a clean environment and confirm Python 3.10+.
-
Determinism: set seeds where applicable; minor variance is expected but drift should be stable.