Usage Guide

Usage Guide: CLI Routing from Prompt to Certificate

Quick-Scan Infobox

Aspect	Details
Target User	Educators scripting demos, developers chaining routes; bash/Python basics assumed.
Core Goal	Master Compitum's CLI for quick queries—embed prompts, apply configs, emit traces for bounded audits.
Time to First Route	2 mins: compitum route --prompt "..." → Model + U output.
Key Analogy	Like a quest starter: Prompt as the hook, flags as gear slots (configs for bounds, trace for loot logs)—dispatch and debrief.
Defaults	No flags: Minimal cert; add --trace for signals suite.

Core Principles Layer (Technical Backbone)

Compitum's CLI (compitum route) orchestrates the observer loop: Embed prompt to D=35 space via metric.learn_spd(), filter candidates under constraints ( A x \leq b ) (from --constraints), weight via free-energy ( E = \alpha q - \sum \beta c ) (tuned in --defaults), select argmin E, emit cert. --verbose dumps full JSON (model, U, components); --trace expands to signals (feas bool, shadows array, boundary flag, drift r_t)—all O(1) post-select. Custom YAMLs override: Router_defaults.yaml sets α=0.4 (quality bias), constraints_us_default.yaml A=1,0, b=[1] (cost cap). Batch via script wrappers; streaming JSONL in mid-term roadmap. Invokes router.route(prompt, context) under the hood, with pgd_signature hashing for repro.

• Flag Mechanics: --prompt embeds via sentence-transformers; configs load at init (validate YAML); trace includes timestamp/router_version for audits.
• Error Handling: Infeas → empty select (log violations); NaN E → clip components, fallback to defaults.
• Extensibility: Pipe outputs to jq for chains (e.g., | jq '.model' → next prompt).

Why CLI-first? Bounded entry: Quick query → constrained response—scales from solo tinker to classroom batch without IDE lift.

Code Dive: Custom Route Script (Collapsible for Tinkerers)

Runnable notebook version (GitHub-rendered)

Pro Tip: Validate configs: python -c "from compitum.router import Router; Router.from_yaml('configs/router_defaults.yaml')"—catches YAML syntax pre-run.

Approachable Layer (Relatable Hooks for Educators)

The CLI's your "dispatch desk": Feed a prompt like a student query, slot configs as lesson rules (constraints for "on-topic" bounds), hit trace for the debrief packet (signals as reflection notes). Minimal runs are the warm-up jog—quick model pick for a theorem recap; verbose traces the full group share, unpacking "why this path?" via shadows and drifts. For classrooms, it's facilitation lite: Script batch for debate rounds, trace to spot "high entropy ties" for interventions—turns quadratic proofs into interactive "route reviews," echoing OSRS quest logs without the grind.

• Classroom Tie-In: Custom configs for history sims—tighten b on "era accuracy," trace components to score "coherence clusters."
• Analogy Echo: Flags as backpack tweaks: --trace packs the full kit (boundaries as maps), minimal's the light hike.
• Common Hurdle: Path woes? Use pwd in YAML—abs paths keep it grounded.

Quick-Reference Toolkit (CLI Flags & Examples)

Flag	Purpose	Default	Example Use	Output Tease
--prompt	Input query str.	Req'd.	--prompt "Pythagorean theorem summary."	Embed → Route.
--constraints	YAML A/b policy.	Internal defaults.	--constraints configs/constraints_us_default.yaml	Feas filter.
--defaults	YAML hyperparams (α, β, D).	Internal.	--defaults configs/router_defaults.yaml	E weights.
--verbose	Full JSON cert.	Minimal (model+U).	--verbose	Components dict.
--trace	Full + signals.	Off.	--trace	Shadows, drifts, boundary.

Examples Table

Scenario	Command	Expected	When
Minimal	compitum route --prompt "Summarize Pythagorean."	{"model": "fast", "U": 0.74}	Quick test.
With Trace	compitum route --prompt "Binomial proof via gens." --trace	JSON w/ feas=true, gap=0.03, flag=true.	Audit ambiguities.
Custom	compitum route --prompt "Privacy policy draft" --constraints ... --defaults ... --trace	Tuned E=-0.2, shadows=[0.1].	Domain bounds.

Gotchas Table (Collapsible: CLI Quirks)

Issue	Symptom	Fix	Analogy
No Output	Blank CLI.	--prompt non-empty; venv active.	Forgot the note—jot the query.
YAML Load	Parse err.	yamllint configs/*.yaml; indents=spaces.	Crumpled map—smooth it out.
Slow Route	>10s.	Drop D=16 in defaults; OMP=1.	Traffic jam—side road stride.
No Signals	Trace lacks boundary.	Explicit --trace; check v0.1.0+.	Empty log—ink the pen.

Next Steps: Your Loop

• Route One: Minimal prompt—add trace, spot a shadow>0.2?
• Batch a Set: Script 3 queries; jq patterns in outputs.
• Tune a Flag: Custom YAML α=0.6, compare U shifts.

See also: Output-Format for cert schemas; Trace-Glossary for field defs; Cookbook for advanced recipes; Configuration for YAML deep; Troubleshooting for snags.