Repository navigation
Examples
Quick-Scan Infobox
Aspect Details Target User Engineers verifying components, researchers examining decisions, educators adapting for lessons—basic Python and terminal use assumed. Core Goal Provide complete, runnable scripts that demonstrate routing, inspection, and adjustment, with outputs that reveal system reasoning. Time to First Insight 10 minutes: Install, run one script, review the certificate. Key Analogy A set of prepared materials: Each script invites direct use, shows immediate results, and supports repeated trials for clearer understanding. Known Limitation Scripts use synthetic or sample data; real prompts may need config tweaks for optimal signals.
Effective learning starts with materials that are ready and self-correcting. These examples follow that approach: Each one runs independently, produces observable outputs, and includes checks for common issues. Use them to trace a route, inspect a decision, or test a concept—then adjust based on what the signals show.
This structure draws from established methods where feedback comes from the activity itself, allowing steady progress without external prompts.
Set up a virtual environment to isolate dependencies.
Runnable notebook version (GitHub-rendered) Expected Output:
Successfully installed compitum-0.1.0 ... (list of packages)
On Windows (PowerShell): Replace source .venv/bin/activate with .venv\Scripts\Activate.ps1.
Verify: compitum --version should show the installed version, such as "0.1.0".
Limitation: Requires Python 3.9+; if pip fails, update with pip install --upgrade pip.
Script: examples/demo_route.py
Time: 30 seconds
Concept: Full routing process, from prompt to certificate.
Run this to process a prompt and view the decision.
Runnable notebook version (GitHub-rendered)
Expected Output:
Runnable notebook version (GitHub-rendered)
Note: Values vary slightly with seed; negative drift confirms descent.
Without --trace:
Runnable notebook version (GitHub-rendered)
Expected Output:
Selected: thinking (utility=0.82)
This output provides direct feedback: Check slack values for feasibility, shadow prices for constraint impacts, and entropy for decision confidence. If entropy is low (<1.0), the choice was narrow—consider relaxing bounds.
Script: examples/certificate_card.py
Time: 1 minute
Concept: Format certificate details for quick review.
Runnable notebook version (GitHub-rendered) Expected Output:
# Certificate Summary
- Model: thinking
- Utility: 0.8234
- Components:
- quality: +0.65
- coherence: +0.12
- diversity: +0.92
- Boundary: gap=0.15 entropy=1.42 (confident)
- Feasible: True
- Shadow prices: latency=0.08 cost=0.12 (low impact)
- Trust radius: 1.2This view highlights key signals: Positive coherence shows alignment with prior traces; low shadow prices indicate room for adjustments. Use it to discuss decisions without parsing JSON.
Limitation: Assumes a single certificate; for batches, chain with batch scripts.
Script: examples/synth_bench.py
Time: 2 minutes
Concept: Test if the SPD metric distinguishes prompt types.
Runnable notebook version (GitHub-rendered)
Expected Output:
Runnable notebook version (GitHub-rendered)
Note: Differences >0.5 suggest separation; rerun with --seed 42 for consistency.
This measures average distances in synthetic clusters (math vs. code prompts). If gaps are small, the metric may need retraining—check rank parameter.
graph TB
E["Embed prompts<br/>x ∈ ℝ^D"]
M["Apply SPD M<br/>d(x,y) = √((x-y)^T M (x-y))"]
C1["Math cluster center"]
C2["Code cluster center"]
D1["Dist to C1<br/>avg=2.34"]
D2["Dist to C2<br/>avg=2.41"]
E --> M
M --> C1
M --> C2
C1 --> D1
C2 --> D2
style M fill:#e3f2fd,stroke:#01579b
style D1 fill:#e8f5e9,stroke:#1b5e20
style D2 fill:#fff3e0,stroke:#ef6c00
Caption: Flow from embedding to cluster distances, verifying metric utility. Alt text: Diagram with embedding, metric application, centers, and distance calculations (8 nodes).
Script: examples/pedagogy_control_of_error.py
Time: 3 minutes
Concept: Show how repeated use strengthens coherence.
Runnable notebook version (GitHub-rendered) Expected Output:
Before practice:
Decision: thinking Utility=0.72
Components: distance=-0.15 coherence=0.08
After practice:
Decision: thinking Utility=0.79
Components: distance=-0.15 coherence=0.21
Changes: Δcoherence=+0.13, Δutility=+0.07
The script routes once, simulates 200 nearby runs (building trace history), then routes again. Coherence rises as the system recognizes patterns from "practice."
It also tests constraints: A US-region prompt succeeds; a JP-region one fails, showing slack= -0.05 and shadow price=0.45 for location bound.
This demonstrates bounded improvement: Signals guide refinement without unbounded search.
Montessori Parallel: As with cylinder blocks, initial mismatches (low coherence) prompt adjustments; success in similar tasks builds reliable form recognition, fostering independence.
Limitation: Simulation uses synthetic traces; real data accelerates learning but requires storage.
Script: examples/batch_route_demo.py
Time: 1 minute
Concept: Handle groups of prompts at once.
Runnable notebook version (GitHub-rendered)
Expected Output:
Runnable notebook version (GitHub-rendered)
Use for logs or benchmarks. Outputs list decisions; aggregate utilities to spot trends (e.g., average gap <0.1 indicates stable choices).
Limitation: Batch size limited by memory; start with --n 10.
Script: examples/explain_certificate_file.py
Time: 30 seconds
Concept: Review stored JSON/JSONL files.
Runnable notebook version (GitHub-rendered) Expected Output: Markdown cards for each entry, like the single-card example above.
Apply to saved runs: Scan for high shadow prices (>0.5) to identify recurring bottlenecks.
Files: examples/bridge_demo.py, examples/bridge_demo.tex
Time: 2 minutes
Concept: Ensure code aligns with documentation.
Run python examples/bridge_demo.py to extract spans and compare with LaTeX. Outputs confirm matches, e.g., "BRIDGEBLOCK router_init: 12 lines synced."
This internal check maintains consistency—useful for auditing changes.
Limitation: Requires LaTeX installed for full verification.
Runnable notebook version (GitHub-rendered) Expected: Python path in .venv; package details.
Runnable notebook version (GitHub-rendered) Expected: Reinstall message with packages.
Runnable notebook version (GitHub-rendered) Expected: Consistent outputs across runs.
Runnable notebook version (GitHub-rendered) Expected: Stable timings; adjust for parallel overhead.
Limitation: Environment variables may not persist; set per session.
- Complete Scripts: Each runs end-to-end, no partial code.
- Interpretable Outputs: JSON for parsing, Markdown for review.
- Visible Errors: Failures show specific signals (e.g., slack <0).
- Cumulative Improvement: Demos build on traces, showing signal changes.
These patterns ensure feedback guides use: Adjust based on what's observed, then retry.
For educators: Outputs reveal reasoning layers—use cards to discuss "why this model?" with students.
For engineers: Scripts expose controls like trust radius; tweak and measure drift to tune stability.
For researchers: Self-supervised checks (coherence, gaps) enable label-free evaluation—extend with your data.
In each case, the materials provide their own checks: Run, observe, refine. This meets the user halfway, offering structure while inviting adaptation.
- Run the quickstart: Process a prompt in 30 seconds.
- Execute the pedagogy demo: Track coherence gains from practice.
- Generate a certificate card: Summarize a decision.
- Review Mathematics: Details on metrics and stability.
- Extend in Getting Started: Customize for your workflow.
Scripts accept --seed for fixed results. Tests use HYPOTHESIS_PROFILE=ci. This supports repeated trials: Consistent outputs build understanding, much like verifying a measurement multiple times.
Last Tuned: November 08, 2025 · Compitum v1.0+ · Open to Contributions
Examples Tour (rendered)
Open on GitHub | Open in nbviewer | Launch in Binder
This notebook accompanies the wiki Examples page with a safe, CI-friendly tour.
It verifies imports and points to runnable scripts under examples/.
import compitum
print('Compitum version:', getattr(compitum, '__version__', 'unknown'))
print('Modules:', sorted(compitum.__all__))Compitum version: 0.1.1
Modules: ['boundary', 'coherence', 'constraints', 'control', 'energy', 'metric', 'router']
- examples/: curated examples that exercise router components.
- Use
pip install -e .in your venv before running.