Configuration

Configuration: Tuning Hyperparameters and Constraints

Quick-Scan Infobox

Aspect	Details
Target User	Educators and developers customizing Compitum for specific workflows; YAML basics assumed.
Core Goal	Balance router efficiency (e.g., embedding dims) with real-world bounds (e.g., cost caps) via simple YAML edits.
Time to First Tune	5 mins: Edit router_defaults.yaml, re-run compitum route.
Key Analogy	Like adjusting a lesson plan: Weights (alpha, beta) prioritize objectives, constraints keep it grounded.
Default Files	configs/router_defaults.yaml (hyperparams); configs/constraints_us_default.yaml (A·x ≤ b).

Core Principles Layer (Technical Backbone)

Compitum loads configs at startup, applying them to the router's optimization loop: Hyperparameters shape the free-energy objective ( E = \alpha q - \sum \beta_i c_i ), where ( q ) is quality and ( c_i ) costs (latency, etc.). Constraints enforce feasibility via linear inequalities ( A \cdot x \leq b ), filtering models before selection—PGD (projected gradient descent) projects features ( x_B ) onto the feasible set.

• Router Hyperparams: Control metric learning and weighting.

  • metric.D: int = 35: Embedding dimension—higher for nuanced distances, but scales compute ( O(D^2) ).
  • metric.rank: int = 4: Low-rank approximation for SPD matrix ( M \approx U \Lambda U^T ), rank ( r \ll D ) for efficiency.
  • metric.delta: float = 0.001: Regularization for metric stability (Riemannian geodesic step).
  • update_stride: int = 8: Refit frequency—every ( n ) steps to amortize learning.
  • Weights: ( \alpha + \sum \beta = 1 ); e.g., alpha: 0.4 prioritizes quality over costs.

• Constraints YAML: Defines policy via matrix form.

  • A: List[List[float]]: Coefficient matrix (rows: constraints, cols: features).
  • b: List[float]: Right-hand side bounds.
  • Example: A: [[1, 0, 0, 0]], b: [1] enforces first feature ≤ 1 (e.g., cost cap).
  • Capabilities check: Models must match context features ( x_B ) post-projection.

Why separate files? Decouples tuning: Edit router for speed, constraints for ethics—reloads without full restart.

Math Dive: Free-Energy with Weights (Collapsible for Tinkerers)

The objective minimizes free energy: [ E(\mathbf{x}) = \alpha \cdot q(\mathbf{x}) - \beta_t \cdot l(\mathbf{x}) - \beta_c \cdot c(\mathbf{x}) - \beta_d \cdot d(\mathbf{x}) - \beta_s \cdot s(\mathbf{x}) ] Subject to ( A \mathbf{x} \leq \mathbf{b} ), solved via dual ascent or QP solvers in compitum.constraints.

# Extended Example: Balanced Router for Classroom Use
metric:
  D: 16          # Lighter for student laptops
  rank: 2        # Minimal for quick fits
  delta: 0.01    # Looser for noisy data
update_stride: 4
alpha: 0.5        # Heavy on quality for learning
beta_t: 0.15      # Moderate latency (real-time feedback)
beta_c: 0.1       # Low cost (open models)
beta_d: 0.1       # Distance in embedding space
beta_s: 0.15      # Coherence for consistent narratives

Pro Tip: Use shadow prices from certs to sensitivity-test: High ( \partial E / \partial b_i ) flags tight constraints.

Approachable Layer (Relatable Hooks for Educators)

Envision configs as your class syllabus: Hyperparams set the "pacing" (stride, weights), constraints the "rules of engagement" (no off-topic detours). Tweak alpha up for deeper insights in history sims, or tighten b for budget-bound math proofs—small changes yield big pattern shifts, like rerouting a group project.

• Classroom Tie-In: For a debate router, set beta_s: 0.3 to favor coherent threads—watch emergent consensus nodes form without chaos.
• Analogy Echo: Weights as a recipe: Too much salt (beta_c high) ruins the dish; balance for that perfect bite (low energy).
• Common Hurdle: YAML syntax slips? Indent with spaces (not tabs)—our CLI validates on load.

Quick-Reference Toolkit (Config Snippets)

File	Key Section	Tune For	Example Value	Impact
router_defaults.yaml	metric.D	Embedding nuance vs. speed.	35 (default) → 20	Faster routes, coarser distances.
router_defaults.yaml	alpha	Quality priority.	0.4 → 0.6	Richer outputs, higher compute.
constraints_us_default.yaml	A	Multi-feature bounds.	[[0.5, 1]]	Blended caps (e.g., half cost, full latency).
constraints_us_default.yaml	b	Absolute limits.	[1, 2]	Per-constraint thresholds.

Troubleshooting Table (Collapsible: Common Edits)

Issue	Symptom	Fix	Analogy
High Latency	Routes >5s.	Drop D to 16; raise beta_t: 0.3.	Speeding up a slow group—assign fewer tasks.
Infeasible All	No models selected.	Loosen b (e.g., [1] → [2]); check A dims.	Locked door—widen the keyhole.
Unstable Metrics	NaN distances.	Increase delta: 0.01; ensure rank < D.	Wobbly table—add shims.
YAML Parse	Load error.	Validate with yamllint configs/*.yaml.	Recipe misread—double-check measures.

Next Steps: Your Loop

• Test a Tune: Edit alpha: 0.6 in defaults, route a prompt—compare cert energies?
• Custom Policy: Fork constraints_us_default.yaml for domain (e.g., constraints_edu.yaml with safety rows).
• Validate: Run Cookbook's pre-commit to lint YAMLs.

See also: Usage-Guide for CLI overrides; Output-Format for cert fields like "constraints_applied"; Glossary for "shadow_prices."