FAQ

FAQ: Common Queries on Compitum's Mechanics and Usage

Quick-Scan Infobox

Aspect	Details
Target User	New educators, developers, and tinkerers hitting roadblocks; no prior deep-dive needed.
Core Goal	Demystify hurdles—from signals to setup—for smooth loops and quick recoveries.
Time to Resolve	<5 mins: Scan Qs, expand a collapsible if stuck.
Key Analogy	Like a class Q&A: Spot the pattern in questions, bound your search to the right section.
Expansion Note	Community-driven: Add yours via GitHub issues labeled "faq"—keeps it fresh.

Core Principles Layer (Technical Backbone)

Compitum's FAQ distills recurring signals from traces and issues: Feedback loops emphasize mechanistic immediacy (e.g., drift as a proxy reward), locality avoids external dependencies, and code entry points prioritize orchestration for auditable flows. Questions cluster around stability (signals), portability (access), debugging (reports), and onboarding (code paths)—all tied to bounded optimization principles.

Expanded answers with formal ties:

• Q: What does “instantaneous feedback” mean here?
  A: In Compitum, "instantaneous" refers to per-step signals like energy drift ( \Delta E_t = E_t - \bar{E}_{t-1} ) (≤0 for descent), constraint slack ( s_i = b_i - (A x)i \geq 0 ), and coherence (log-evidence from KDE on traces). These act as local rewards in the RL loop, computed O(1) via energy.py and boundary.py, bypassing delayed judge evals. Formally: Update policy ( \pi{t+1} \leftarrow \pi_t + \eta \nabla \log \pi (signals_t) ), ensuring Lyapunov stability without horizon bias.

• Q: Does Compitum require internet access?
  A: Core routing (router.route()) is fully offline: Embeddings, metrics, and predictors run on local models (e.g., via HuggingFace cache). Optional integrations like RouterBench (for benchmarks) or cloud providers (e.g., Grok API) need net for fetches—toggle via COMPITUM_OFFLINE=1 env var, which stubs externals to mocks in predictors.py.

• Q: What should I include when filing an issue?
  A: For reproducibility: OS/Python (python --version), command+flags (e.g., compitum route --prompt "..." --trace), relevant YAML snippets (redact secrets), and trace JSON (key fields: free_energy, shadow_prices, drift_signal). Use GitHub template: Paste under "Environment" and "Steps to Reproduce"—helps triage feasibility violations or metric singularities.

• Q: Where should I start reading the code?
  A: Begin with src/compitum/router.py (top-level orchestration: route() chains constraints → selection → cert). Follow to src/compitum/energy.py (scalar computation: free_energy(components)). Branch to constraints.py (QP feasibility), boundary.py (tie diagnostics), control.py (SRMF trust radii). Structure: Modular observers querying a central quadratic graph—trace calls via pdb or VSCode debugger.

Why these Qs? They map to observer bounds: Feedback as radius checks, access as partition locality, issues as query logs, code as the geometry itself.

Tech Dive: Decoding a Sample Trace for Issues (Collapsible for Tinkerers)

[Notebook content will be embedded by CI]

Approachable Layer (Relatable Hooks for Educators)

FAQs as your "back-pocket prompts": When a lesson route stalls (high drift?), or setup feels walled (offline mode?), these are the quick redirects—like a student handbook that anticipates the "but why?" before it stalls the class. For teachers, they're bridges: Turn a config snag into a mini-lesson on shadows, making constraints feel like fair play rules.

• Classroom Tie-In: Use the trace-reporting Q for student debugging—have kids file "issues" on shared sims, redacting "secrets" (personal queries), to practice auditable feedback.
• Analogy Echo: Instantaneous signals? Like a GPS ping every block, not just at destination—keeps the quadratic path from wandering into dead ends.
• Common Hurdle: Overwhelmed by traces? Start with jq '.free_energy' trace.json—one number to rule the loop.

Quick-Reference Toolkit (Q&A Matrix)

Question	TL;DR Answer	When It Pops	Next Debug Step
Instantaneous Feedback?	Local signals (drift, slack) as step rewards—no judges.	RL tuning stalls.	Plot energy.py history: Descent? Good.
Internet Required?	No for core; yes optional for benches/providers.	Offline class setup.	Set COMPITUM_OFFLINE=1; test route.
Issue Filing?	OS/Python/cmd/config/trace (redacted).	Bug hunt.	Use GH template; attach minimal repro YAML.
Code Start?	router.py → energy.py → constraints/boundary/control.	Onboarding dive.	git grep 'route(' for call flows.

Gotchas Table (Collapsible: Edge Cases)

Hurdle	Symptom	Quick Fix	Analogy
Judge Craving	"But how to eval outputs?"	Lean on coherence/shadows—add if needed.	Skip the grader; self-check the work.
Net Dependency Sneak	Route fails mid-way.	Audit imports: No requests in core.	Surprise toll—stick to local roads.
Trace Too Verbose	JSON overloads editor.	--trace-minimal flag; filter keys.	Novel vs. summary—skim chapters.
Code Maze	Lost in submods.	Draw graph: pydeps src/compitum (install if dev).	Labyrinth—follow the main artery first.

Next Steps: Your Loop

• Self-Q: Got a new one? Draft in Roadmap or issue—community vote adds it.
• Apply One: Re-run a stalled route with offline flag; check drift?
• Deepen: Cross-ref with Design-Notes for signal math.

See also: Usage-Guide for CLI troubleshooting; Configuration for env tweaks; Verification for self-audits; Glossary for terms like "Lyapunov stability."