Design Notes

# Design Notes: Rationale and Evolution of Compitum's Architecture

**Quick-Scan Infobox**

| Aspect | Details |

|--------|---------|

| **Target User** | Developers and educators probing the "why" behind features; technical curiosity assumed. |

| **Core Goal** | Unpack mechanistic choices—from geometry to signals—for informed extensions and trust-building. |

| **Time to First Insight** | 10 mins: Skim sections, expand a collapsible for math flavor. |

| **Key Analogy** | Like an engine blueprint: Each note a cog—meshed for stability, tuned for emergent drive. |

| **Evolution Note** | Living doc: PRs welcome; tracks v1.0+ shifts (e.g., Thompson integration Q1 2026). |

## Core Principles Layer (Technical Backbone)

Compitum's design prioritizes auditable, constraint-aware optimization over black-box heuristics: Embeddings live on a Riemannian manifold defined by low-rank SPD metrics, updates stay Lyapunov-stable via trust regions, and selection favors mechanistic signals (no external judges). This yields certificates that are both interpretable and composable, with diversity baked in to avoid mode collapse.

### Geometry: Manifold Distances and Stability Bounds

- **Low-Rank SPD Metric**: Distances via \( d(x,y) = \sqrt{(x-y)^T M (x-y)} \), where \( M = U \Lambda U^T \) (rank \( r \leq D \))—approximates full SPD for \( O(r D) \) compute vs. \( O(D^3) \). Fits via Riemannian SGD on log-Euclidean means.

- **Trust Radius (SRMF Controller)**: Bounds parameter steps \( \Delta \theta \leq r_t \), with \( r_{t+1} = r_t \cdot \beta^{I_t} \) (β<1 for contraction); ensures \( V(\theta_{t+1}) \leq V(\theta_t) + \epsilon \) (Lyapunov-like, V=free energy). Integral \( I_t \) accumulates drift errors.

*Why low-rank?* Quadratic spaces explode in high-D; rank caps prevent overfitting to noise, keeping observers "bounded."

### Constraints and Selection: Feasible Optimization

- **Filtering**: Pre-select via capabilities (e.g., model size ≤ GPU) and \( A x \leq b \) (linear, e.g., cost/latency rows). Projected GD: \( x^{k+1} = \Pi_{A x \leq b} (x^k - \eta \nabla E) \).

- **Best Feasible**: Argmax utility among survivors; shadow prices \( \lambda_i \approx \frac{\partial U^*}{\partial b_i} \) via Lagrange dual or finite diffs—quantifies "bang for relaxation buck."

- Selection: Greedy on predicted E, with boundary flags if \( |U_1 - U_2| < \delta \).

### Process Signals: Mechanistic Feedback Loops

- **Signals Suite**: Energy drift (\( \Delta E_t = E_t - E_{t-1} \)), slack (\( s_i = b_i - (A x)_i \)), coherence (KDE log-evidence), boundary (entropy/gap). All computed in O(1) post-route.

- **No Judges**: Rewards are intrinsic—e.g., negative drift as "success signal"—auditable via traces, sidestepping bias in LLM evals.

### Diversity and Exploration: Entropy-Preserving Updates

- **Preservation**: Softmax over utilities with temperature \( \tau = 1 / \log(k) \) (k=candidates) to retain entropy.

- **Exploration**: Epsilon-greedy now (ε=0.1); Thompson sampling planned (beta priors on utilities, sample per route)—balances exploitation under constraints.

*Overarching Rationale:* Design echoes bounded observers: Constraints as radii, signals as queries, geometry as the shared square—emergent patterns from local rules.

Math Dive: Shadow Prices in Action (Collapsible for Tinkerers)

For a toy QP: Max \( U(x) = q x - c x \) s.t. \( A x \leq b \).

\# Pseudocode: Compute Shadows via Dual

import numpy as np

from scipy.optimize import linprog  # For dual approx



def shadow\_prices(A, b, c, q):

    # Primal: min c x s.t. A x >= -q, x >=0 (reformulated)

    res = linprog(c, A\_ub=-A, b\_ub=-q, bounds=(0, None))

    shadows = res\['slack']  # Dual vars approx

    return shadows  # ∂U\*/∂b\_i



\# Example: Cost cap b=\[1]

A = np.array(\[\[1, 0]])  # Cost row

b = np.array(\[1.0])

print(shadow\_prices(A, b, np.array(\[0.1, 0.2]), np.array(\[0.8, 0.6])))

\# Output: High shadow on tight cap → relax it for +U

*Pro Tip:* Log shadows in traces; >0.5 flags ethical tweaks (e.g., loosen latency for accessibility).

## Approachable Layer (Relatable Hooks for Educators)

These notes are the "shop talk" behind Compitum—like chatting with the architect over coffee: Why this wall (constraints) here? To keep the room cozy, not cramped. For teachers, it's empowerment: Tweak geometry for "gentle curves" in student embeddings, or amp signals for real-time "aha" pings in group work.

- **Classroom Tie-In**: Use boundary diagnostics in essay routing—flags "gray zones" for peer review, turning ambiguity into collaborative sparks.

- **Analogy Echo**: Process signals as a heartbeat monitor: Steady drift? Green light for the lesson; spikes? Pause and bound tighter.

- **Common Hurdle**: Over-exploration chaos? Start epsilon-low (0.05)—like dipping toes before the pool jump.

## Quick-Reference Toolkit (Design Pillars Summary)

| Pillar | Key Mechanism | Rationale | Tune Via | Classroom Parallel |

|--------|---------------|-----------|----------|--------------------|

| **Geometry** | Low-rank SPD + Trust Radius | Efficient, stable distances/updates. | metric.rank, trust\_radius. | Map scales for field trips—detailed but not dizzying. |

| **Constraints & Selection** | A·x ≤ b + Shadows | Feasible, sensitive optima. | YAML A/b; post-route diffs. | Class rules + "what if" flexes. |

| **Process Signals** | Drift/Slack/Coherence/Boundary | Auditable, immediate RL. | Thresholds in control.py. | Progress check-ins—no end-of-term shocks. |

| **Diversity & Exploration** | Entropy Softmax + Thompson | Avoid collapse; balanced search. | tau temp; ε/priors. | Group mixes—spark without scatter. |

Gotchas Table (Collapsible: Design Tradeoffs)

| Issue | Symptom | Rationale/Fix | Analogy |

|-------|---------|---------------|---------|

| **High Drift** | E jumps >0.1/step. | Loose radius—tighten via SRMF β=0.9. | Speeding car—brake earlier. |

| **All Infeasible** | Empty selection. | Over-tight b—scale by 1.2; check dims. | Locked pantry—stock basics. |

| **Low Diversity** | Same models repeat. | Raise τ or ε=0.2; monitor entropy. | Echo chamber—invite outsiders. |

| **Metric Singularity** | Det(M)→0. | Bump delta=0.01; rank-up if needed. | Flat map—add contours. |

## Next Steps: Your Loop

- **Probe a Pillar**: Simulate shadows in Cookbook with a QP toy—spot sensitivities?

- **Contribute**: Fork and add a note (e.g., "Quantum Extensions?"); tag "design-evo."

- **Connect Dots**: Trace how geometry feeds signals in a live route.

Related: Philosophy for big-picture ethos; Verification for invariant proofs; Output-Format for signal schemas.