Repository navigation
Design Notes
Quick-Scan Infobox
Aspect Details Target User Developers who examine components, educators who trace processes—technical background assumed, but no advanced degree required. Core Goal Explain the components: From distances on manifolds to signal values, to support extensions, reviews, and clear understanding. Time to First Insight 5 minutes: Review this infobox, expand one collapsible section, follow one signal in the diagram. Key Analogy A telescope's focus: Based in geometry for precision, limited by constraints for reliability—patterns emerge from consistent observation. Evolution Note This document updates with contributions (label "design-evo"); v1.0 as baseline, with updates planned for Q1 2026. Known Limitation Examples use simplified models; real routes may require tuning for high-dimensional data.
Compitum provides routes that can be audited, based on distances in Riemannian manifolds, updates protected by Lyapunov conditions, and signals derived from mechanisms rather than external judgments. Embeddings use low-rank SPD metrics for computation, selections respect constraints informed by shadow prices, and diversity maintains entropy—resulting in certificates that combine and explain like structured records.
The space is a curved manifold, not a flat Euclidean grid, where distances adjust through positive-definite metrics. Low-rank versions reduce computation, and trust regions limit steps to prevent instability.
graph TB
subgraph "Manifold Landscape"
E["Embedding x ∈ ℝ^D"]
M["Low-Rank SPD M = UΛU^T<br/>rank(r ≤ D)"]
D["Distance d(x,y) = √((x-y)^T M (x-y))<br/>Log-Euclidean mean for fits"]
T["Trust Radius r_t<br/>θ_{t+1} = θ_t + Δθ, ||Δθ|| ≤ r_t"]
L["Lyapunov V(θ) ≤ V(θ_t) + ε<br/>V = Free Energy (drift proxy)"]
E --> M
M --> D
D --> T
T --> L
end
subgraph "Update Loop"
U["SRMF Controller: r_{t+1} = r_t · β^{I_t}<br/>β < 1 contract, I_t = ∫ drift dt"]
L --> U
U --> E
end
style M fill:#e1f5fe,stroke:#01579b
style T fill:#fff3e0,stroke:#ef6c00
style L fill:#e8f5e9,stroke:#1b5e20
Caption: Flow from embedding to stability check, showing how metrics and controls interact. Alt text: Diagram of manifold processing with update loop.
- Low-Rank SPD Metric: ( d(x,y) = \sqrt{(x-y)^T M (x-y)} ), where ( M = U \Lambda U^T ) (rank ( r \leq D ))—computes in ( O(r D) ) time compared to ( O(D^3) ) for full SPD. Riemannian SGD on log-Euclidean means preserves positive-definiteness and resists noise.
- Trust Radius (SRMF Controller): Limits ( \Delta \theta \leq r_t ), updates ( r_{t+1} = r_t \cdot \beta^{I_t} ) (( \beta < 1 ) for caution); Lyapunov condition ( V(\theta_{t+1}) \leq V(\theta_t) + \epsilon ) (V as free energy drift). The integral ( I_t ) accumulates errors over time.
This approach uses geometry to maintain local accuracy and global consistency, aligned with bounded observation: Focus on nearby points without overgeneralizing. Limitation: In very high dimensions, rank selection needs validation to avoid underfitting.
Math Detail: Riemannian Fit in Pseudocode (For Those Interested in Equations)
Riemannian SGD minimizes divergence on paired embeddings.
[Notebook content will be embedded by CI]
Note: Output shows a matrix like 0.12, -0.03], [-0.03, 0.11 (values vary with random seed).
Tip: Select rank through cross-validation on sample routes; low values may simplify too much, high values increase time.
Constraints define available options, and shadow prices indicate their impact. Filter to reduce options, select based on utility, and detect narrow margins.
flowchart TD
Q[Query Arrives] --> F["Filter: Capabilities + A x ≤ b<br/>Proj GD: x^{k+1} = Π(x^k - η ∇E)"]
F --> S["Survivors: k Candidates"]
S --> U["Utility U(x) = q x - c x<br/>Greedy: argmax U among feasible"]
U --> Sh["Shadows λ_i ≈ ∂U*/∂b_i<br/>Finite diff or dual solve"]
Sh --> B{"Boundary? |U_1 - U_2| < δ"}
B -->|Yes| Flag["Flag: Entropy/Gap Audit<br/>Trigger Exploration"]
B -->|No| Select["Route: Best Feasible x*"]
Select --> Cert["Certificate: x*, λ, signals"]
style F fill:#fff3e0,stroke:#ef6c00
style Sh fill:#e1f5fe,stroke:#01579b
style Flag fill:#ffebee,stroke:#c62828
Caption: Process from query to selection, highlighting boundary checks. Alt text: Flowchart of filtering, utility computation, and certification.
- Filtering: Apply hard limits (e.g., tokens ≤ budget) and soft linear constraints ( A x \leq b ) (rows for cost, latency). Projected gradient descent reaches feasibility: ( x^{k+1} = \Pi_{A x \leq b} (x^k - \eta \nabla E) ).
- Best Feasible: Maximize utility in the feasible set; shadow prices ( \lambda_i \approx \frac{\partial U^*}{\partial b_i} ) (from Lagrange dual or perturbation)—measures utility gain per constraint relaxation.
- Boundary Flags: If top utilities differ by less than ( \delta ), review: High entropy prompts diverse options; low gap suggests stricter limits.
This prioritizes feasible solutions to avoid invalid routes, with shadow prices providing guidance for adjustments, similar to resource limits in planning. Limitation: Linear constraints may not capture nonlinear costs; extend with quadratic forms if needed.
Signals provide immediate feedback: Derived internally, computed quickly, and explained directly. No external models; only calculations that indicate progress or issues.
-
Key Signals:
- Drift ( \Delta E_t = E_t - E_{t-1} ): Change in free energy—negative values show improvement; positive values prompt radius reduction.
- Slack ( s_i = b_i - (A x)_i ): Margin on constraints; values near zero require shadow price review.
- Coherence: Log-evidence from kernel density estimation on traces—measures consistency without loss of detail.
- Boundary: Entropy or utility difference—indicates uncertain areas, suggesting further exploration.
-
Efficiency: Each signal computes in constant time after routing; traces collect them for later review.
Mechanistic signals ensure reliability, like a log of observations in an experiment—direct and revisable. Limitation: They assume accurate free energy estimates; calibrate on known data.
To prevent focus on few options, Compitum uses temperature-controlled probabilities and sampling methods.
- Preservation: Softmax probabilities ( p_i = \frac{\exp(U_i / \tau)}{\sum \exp(U_j / \tau)} ), with ( \tau = 1 / \log k ) (k = candidates)—targets entropy near ( \log k ).
- Exploration: Base ε-greedy (ε = 0.1, select random feasible option); advanced: Thompson sampling with beta priors on utilities, drawing samples per query—reduces regret in uncertain spaces.
Entropy supports varied responses, avoiding repetition. Limitation: High temperature may slow convergence; monitor on validation sets.
Overall Rationale: Local mechanisms (signals, limits) enable reliable patterns without oversight. This reflects the philosophy: Rules at each step lead to stable outcomes.
Quick Example: Entropy in Softmax (Test in a Notebook)
Example with 5 candidates, varying temperature—observe probability distribution.
[Notebook content will be embedded by CI]
Note: Adjust τ based on task: Lower for exact matches, higher for idea generation.
These components relate to teaching: Shadow prices show resource impacts, like adjusting group sizes. Geometry supports gradual challenges, signals provide timely feedback. Constraints act as guidelines with flexibility for adaptation.
- In Practice: Use boundary flags for discussion topics—identify ambiguous cases, assign group reviews. This builds collaborative reasoning.
- Montessori Parallel: Like prepared materials, signals offer self-correction: A child notices a block mismatch (drift) and adjusts, gaining independence without direct intervention.
- Adjustment Tip: If exploration leads to too many options, set ε = 0.05—test one path before expanding.
journey
title "A Route's Life: From Query to Certificate"
section Query Lands
Embed & Filter : 2 : Geometry Processes
Constraints Apply : 3 : Feasibility Checked
section Selection Occurs
Utilities Computed : 4 : Shadows Calculated
Diversity Maintained : 5 : Entropy Balanced
section Signals Generated
Drift Measured : 3 : Stability Confirmed
Flags Raised : 2 : Boundaries Noted
section Certificate Produced
Trace Recorded : 4 : Insights Summarized
Next Query Prepared : 5 : Loop Continued
Caption: Journey map of a single route, from input to output. Alt text: Timeline showing stages of processing with estimated efforts.
For Educators: Process student queries in batches—review signal patterns to customize follow-ups. This supports individual progress over uniform pacing.
| Component | Key Mechanism | Rationale | Tune Via | Classroom Parallel |
|---|---|---|---|---|
| Geometry | Low-rank SPD + Trust Radius | Efficient distances, controlled updates. |
metric.rank, trust_radius in YAML. |
Maps with clear paths, limited scope. |
| Constraints & Selection | ( A \cdot x \leq b ) + Shadow Prices | Valid choices, impact analysis. |
constraints.yaml; perturbation scripts. |
Guidelines with adjustment allowances. |
| Process Signals | Drift/Slack/Coherence/Boundary | Direct feedback on routes. | Thresholds in control.py. |
Observations during activities. |
| Diversity & Exploration | Entropy Softmax + Thompson | Varied options, reduced repetition. |
tau temperature; ε/priors in config. |
Group discussions with multiple views. |
Common Issues: Patterns and Fixes
| Issue | Sign | Cause & Fix | Parallel |
|---|---|---|---|
| Drift Increase | ( \Delta E > 0.1 ) per step. | Uncontrolled update—set β = 0.9 in controller. | Overreach in a task—pause and refine. |
| No Feasible Options | Zero candidates. | Limits too strict—increase b by 1.2x; verify dimensions. | Missing supplies—add basics. |
| Low Diversity | Repeated selections. | Temperature too low—raise to 1 / log k; track entropy. | Single viewpoint—include others. |
| Metric Instability | Determinant near 0. | Near-singularity—add 0.01 to diagonal; adjust rank. | Unclear view—refocus. |
Debug Step: Save a route trace; search for "shadow > 0.5"—indicates potential adjustments.
- Test a Component: Use the Cookbook quadratic program example—change a constraint, observe shadow price changes. Does sensitivity match expectations?
- Contribute: Submit a pull request with a new detail (e.g., "Effects of Riemannian Updates"); label "design-evo".
- Follow a Route: Run a live query; diagram the flow from geometry to signals. Do patterns align?
Related Pages: Philosophy for foundational reasons; Verification for checks on consistency; Output-Format for certificate details.
Last Tuned: November 08, 2025 · Compitum v1.0+ · Open to Contributions
This design evolves through review: Examine, suggest, refine—the structure benefits from input.