Output Format

Output Format: JSON Certificates and Trace Signals

Quick-Scan Infobox

Aspect	Details
Target User	Educators auditing routes, developers parsing certs; JSON basics assumed.
Core Goal	Decode Compitum's cert schema—from minimal selections to verbose traces—for auditable insights into decisions and drifts.
Time to First Parse	2 mins: jq '.model' trace.json → Spot the winner.
Key Analogy	Like a flight black box: Minimal's the "destination," verbose the full log—replay the quadratic path from takeoff to signals.
Flag for Traces	--trace unlocks full fields; defaults to minimal.

Core Principles Layer (Technical Backbone)

Compitum's outputs are self-contained certificates: JSON blobs auditing the route from prompt embed to model select, with minimal mode stripping to essentials (model + U) for speed, and --trace expanding to process signals (feas, shadows, drifts). Schema rooted in bounded optimization: U as free-energy min ( U = \alpha q - \sum \beta c ), components as breakdowns, constraints via KKT shadows ( \lambda_i ), boundaries on gap/entropy, drifts via EMA/integral. Timestamps and versions ensure reproducibility; pgd_signature hashes projected features for integrity. Full verbose mirrors observer queries: Embed → Filter (A x ≤ b) → Select (argmin E) → Certify (signals post-hoc).

• Minimal Structure: Lean for CLI pipes—e.g., {"model": "grok-3-mini", "U": -0.15}; U scalar for quick sorts.
• Verbose/Trace Expansion: Includes utility_components dict (q:0.8, l:0.2, etc.), constraints (feas:bool, shadows:[0.1,0.0]), boundary (gap:0.02, H:1.2, flag:true), drift (r_t:0.8, ema:0.05, I:-0.1). See repo examples/trace.example.json for end-to-end.
• Validation: Certs are flat, ARIA-friendly JSON—parse via jq or pydantic for classroom scripts.

Why certs? Auditable envelopes: Minimal for loops, traces for quadratic post-mortems—emergent patterns from logged bounds.

Code Dive: Parsing a Cert (Collapsible for Tinkerers)

Open on GitHub | Open in nbviewer | Launch in Binder

Snippet from Output-Format.md

# Quick Parse: Load and Extract Key Signals
import json
from typing import Dict, Any

def audit_cert(cert_path: str) -> Dict[str, Any]:
    with open(cert_path, 'r') as f:
        cert = json.load(f)
    
    # Core audit
    model = cert['model']
    U = cert['utility']
    feas = cert['constraints']['feasible']
    shadows = cert['constraints']['shadow_prices']
    gap = cert['boundary']['utility_gap']
    flag = cert['boundary']['is_boundary']
    
    # Flags
    issues = []
    if not feas:
        issues.append("Infeasible route—check b.")
    if flag:
        issues.append(f"Boundary tie: gap={gap:.3f}, consider reroute.")
    if max(shadows) > 0.5:
        issues.append("Tight constraint—high shadow.")
    
    return {
        "model": model,
        "U": U,
        "issues": issues,
        "full": cert  # For deep dive
    }

# Example: Load Minimal
cert = '{"model": "fast", "U": 0.742}'
print(audit_cert('trace.json'))  # Expand to file

Pro Tip: Schema enforce: Use jsonschema on traces—flags missing 'pgd_signature'.

Approachable Layer (Relatable Hooks for Educators)

Certs are your "route report card": Minimal's the grade (U + model), verbose the comments (why shadows spiked, drifts crept). For classrooms, they're debrief tools—parse components to discuss "quality tradeoffs," boundaries as "close calls needing peer review." No black magic: JSON's human-scale, like a shared doc—pipe to tables for group analysis, turning abstract E mins into "what bounded this choice?" stories.

• Classroom Tie-In: Route student queries, share certs—high unc? Brainstorm relaxations; low U? Tweak weights like lesson tweaks.
• Analogy Echo: Drift fields as the "vibe check": EMA smooths the wobbles, integral the nagging pulls—keeps the quadratic flight steady.
• Common Hurdle: Bloated JSON? --trace-minimal strips noise; jq filters to '.[].boundary'.

Quick-Reference Toolkit (Cert Fields)

Field	Type	Description	Example	When to Check
model	str	Selected router winner.	"grok-3-mini"	Core decision.
utility (U)	float	Free-energy scalar.	-0.15	Overall goodness.
utility_components	dict	Breakdown: q, l, c, d, e, unc.	{"quality": 0.8, "latency": 0.2}	Tradeoff audits.
constraints	dict	Feas bool, violations list, shadows array.	{"feasible": true, "shadow_prices": [0.1, 0.0]}	Binding rules.
boundary	dict	Gap, entropy H, unc, flag.	{"utility_gap": 0.02, "is_boundary": true}	Ambiguity flags.
drift	dict	r_t, ema, integral I.	{"trust_radius": 0.8, "drift_ema": 0.05}	Stability traces.
pgd_signature	str	Hash of projected features.	"sha256:abc123"	Integrity check.
timestamp	str	ISO route time.	"2025-11-03T04:16:09Z"	Reproducibility.
router_version	str	Compitum tag.	"v1.0.0"	Version lock.

Gotchas Table (Collapsible: Cert Snags)

Issue	Symptom	Fix	Analogy
Missing Fields	KeyError on trace.	Add --trace; check schema.	Incomplete report—demand the full.
NaN U	Inf in scalar.	Clip components; debug preds.	Overflow grade—cap the scale.
High Drift	r_t →0.	Tune EMA α=0.3; inspect I windup.	Leaky boat—patch the holes.
Parse Fail	Invalid JSON.	Validate with jq .; escape prompts.	Garbled fax—resend clear.

Next Steps: Your Loop

• Parse a Trace: jq '.constraints' examples/trace.example.json—spot shadows?
• Script Audits: Extend the snippet; batch on student routes.
• Customize: Add domain fields via PR to router.py emit.

See also: Trace-Glossary for field deep-dives; Usage-Guide for --trace flags; Cookbook for jq recipes; Verification for schema tests.