Skip to content

Getting Started

Jump to bottom
PaulTiffany edited this page Nov 5, 2025 · 35 revisions

🚀 Getting Started: From Repo Clone to First Routed Loop

Quick-Scan Infobox

Aspect Details
🎯 Target User New educators and developers; no prior Compitum exposure—Python basics assumed
🎓 Core Goal Bootstrap a local env, run a demo route, and unpack the cert output for immediate insights
⏱️ Time to First Route 10 minutes: Clone → Install → Demo → Inspect JSON
💡 Key Analogy Like prepping a science fair station: Set up the gear, spark the reaction, log the sparks (signals)
📋 Prerequisites Git, Python 3.10+; optional: VSCode for trace viewing

🗺️ Your Onboarding Journey

graph LR
    A[📥 Clone Repo] --> B[🔧 Setup Venv]
    B --> C[📦 Install Dependencies]
    C --> D[▶️ Run Demo Route]
    D --> E[📊 Inspect Certificate]
    E --> F[🎉 First Insights!]
    
    style A fill:#e1f5ff
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e8f5e9
    style E fill:#fff9c4
    style F fill:#ffebee
Loading

🏗️ Core Principles Layer (Technical Backbone)

Compitum's onboarding emphasizes reproducibility: Editable install for dev workflows, CLI-first for low-friction entry, and trace-enabled routes to surface mechanistic signals right away.

🔬 System Architecture

flowchart TD
    subgraph Input
        A[User Prompt] --> B[Embedding Layer]
        B --> C[D=35 Space]
    end
    
    subgraph Router["🧠 Router Core"]
        C --> D[Constraint Filter]
        D --> E["A x ≤ b"]
        E --> F[Free Energy Min]
        F --> G["E = αq - Σβc"]
    end
    
    subgraph Output
        G --> H[Model Selection]
        H --> I[Certificate JSON]
        I --> J[Quality Scalars]
        I --> K[Feasibility Flags]
        I --> L[Boundary Diagnostics]
        I --> M[Drift Signal]
    end
    
    style Router fill:#e3f2fd
    style Input fill:#f1f8e9
    style Output fill:#fce4ec
Loading

🎛️ Installation Flow

Under the hood, pip install -e ".[dev]" pulls dependencies like:

  • numpy/scipy for metrics
  • yaml for configs
  • pytest for verification

The -e flag activates in a venv to isolate your global environment.

sequenceDiagram
    participant User
    participant Venv as Virtual Environment
    participant Pip as Package Manager
    participant Compitum as Compitum System
    
    User->>Venv: Create & Activate
    Venv->>User: Isolated Environment Ready
    User->>Pip: pip install -e ".[dev]"
    Pip->>Compitum: Install Core Dependencies
    Pip->>Compitum: Install Dev Tools
    Compitum->>User: ✅ Ready for Development
Loading

⚡ Demo Mechanics

The demo invokes router.route():

  1. Embeds the prompt via metric.learn_spd()
  2. Filters constraints ( A x \leq b )
  3. Selects via free-energy minimization ( E = \alpha q - \sum \beta c )
  4. Emits a JSON certificate with:
    • Component quality/latency scalars
    • Feasibility flags
    • Boundary diagnostics (gap/entropy)
    • Drift signal ( \Delta E )

Why CLI-first? Mirrors bounded observers: Quick query (prompt) → Constrained response (cert)—scales to classroom batches without IDE overhead.

💻 Code Dive: Parsing Your First Cert (Click to Expand) 
# Post-Demo: Inspect Trace in Python (Run in .venv)
import json
from compitum.boundary import is_boundary  # From install

with open('demo_trace.json', 'r') as f:  # Redirected from CLI
    cert = json.load(f)

print(f"Energy: {cert['free_energy']:.3f} | Feasible: {cert['feasible']}")

if is_boundary(cert['utilities']):
    print("⚠️  Boundary tie—consider exploration boost.")

# Pro Tip: Assert invariants
assert cert['drift_signal'] <= 0.1, "⚡ Check stability."

Extend: Save as parse_cert.py; run python parse_cert.py after each demo.

Signal Interpretation Guide

graph TD
    A[Certificate Signals] --> B{Drift < 0?}
    B -->|Yes| C[✅ Descent Mode]
    B -->|No| D[⚠️ Check Stability]
    
    A --> E{Shadow > 0.5?}
    E -->|Yes| F[💡 Consider Loosening Bounds]
    E -->|No| G[✅ Constraints OK]
    
    A --> H{Free Energy?}
    H -->|Low| I[🌊 Smooth Flow]
    H -->|High| J[⚡ High Tension]
Loading

🎓 Approachable Layer (Relatable Hooks for Educators)

Think of kickoff like a warm-up activity:

Phase Educational Analogy Technical Reality
Install Setting up your clean lab bench Venv isolation
Demo Route First student query Prompt processing
Certificate Group reflections Signal analysis
Low Energy Smooth flow Optimal selection
Boundaries Lively debates Constraint tensions

🏫 Classroom Integration Flow

journey
    title Classroom Usage Pattern
    section Preparation
      Clone & Install: 5: Teacher
      Test Demo Route: 4: Teacher
    section In Class
      Students Submit Prompts: 5: Students
      Run Batch Routes: 4: Teacher, Students
      Share Certificates: 5: Everyone
    section Discussion
      Analyze Shadow Prices: 4: Everyone
      Discuss Trade-offs: 5: Everyone
      Iterate Parameters: 3: Advanced Students
Loading

💬 Classroom Tie-In Example

Route student-submitted prompts like:

  • "Visualize binomial via Pascal's triangle"
  • "Explain recursion using fractals"

Then discuss the certificates:

Teacher: "Look at these shadow prices. What if we relax the latency bound for deeper generations?"
Students: Explore the trade-offs between speed and depth!

📋 Quick-Reference Toolkit (Onboarding Steps)

Step-by-Step Commands

Step Command What It Does Expected Output 💡 Tip
1️⃣ Clone & Venv git clone https://github.com/PaulTiffany/compitum.git && cd compitum && python -m venv .venv && source .venv/bin/activate Fetches repo, isolates env Activated prompt (.venv) $ Windows: .venv\Scripts\activate
2️⃣ Install Deps pip install -e ".[dev]" Loads core + test/lint tools "Successfully installed compitum-0.1.0" Includes Sphinx for docs
3️⃣ Demo Route compitum route --prompt "Prove binomial via generating functions." --trace > demo.json Embeds, routes, traces cert JSON with prompt, model, signals Swap prompt for your query
4️⃣ Verify compitum --help Checks CLI installation Usage flags listed Or pytest -q for tests

🎯 Installation Decision Tree

graph TD
    A[Start Installation] --> B{Have Python 3.10+?}
    B -->|No| C[Install Python]
    B -->|Yes| D{Have Git?}
    C --> D
    D -->|No| E[Install Git]
    D -->|Yes| F[Clone Repository]
    E --> F
    F --> G[Create Venv]
    G --> H{Venv Activated?}
    H -->|No| I[Troubleshoot Venv]
    H -->|Yes| J[Install Dependencies]
    I --> H
    J --> K{Install Successful?}
    K -->|No| L[Check Troubleshooting]
    K -->|Yes| M[🎉 Ready to Route!]
    
    style M fill:#4caf50,color:#fff
    style L fill:#ff9800
    style I fill:#ff9800
Loading
🔧 Troubleshooting Table (Click to Expand)
Issue Symptom Fix 🎨 Analogy
Venv Fail "No module named venv" apt install python3-venv (Linux) or brew equivalent Missing apron—grab from the drawer
Pip Errors "Wheel build fail" pip install --upgrade pip setuptools wheel Rusty tools—sharpen first
No Cert Fields Empty JSON Add --trace; ensure prompt non-blank Blank canvas—sketch the outline
Docs Not Live 404 on documentation site make docs in root; browse _build/html Unbaked bread—oven time

Common Installation Issues

pie title Installation Issues Distribution
    "Venv Problems" : 35
    "Dependency Conflicts" : 25
    "Missing Prerequisites" : 20
    "Permission Errors" : 15
    "Other" : 5
Loading

🔄 Certificate Analysis Workflow

Understanding your first certificate output:

graph LR
    A[📄 Certificate JSON] --> B[Parse Signals]
    B --> C{Quality Check}
    C -->|Good| D[✅ Deploy]
    C -->|Issues| E[Debug]
    
    B --> F{Boundary Analysis}
    F -->|Clear| D
    F -->|Ambiguous| G[Adjust Parameters]
    
    B --> H{Drift Check}
    H -->|Stable| D
    H -->|Unstable| I[Review Constraints]
    
    E --> J[Iterate]
    G --> J
    I --> J
    J --> A
    
    style D fill:#4caf50,color:#fff
    style E fill:#ff9800
    style G fill:#2196f3,color:#fff
    style I fill:#ff9800
Loading

📊 Sample Certificate Structure

{
  "prompt": "Prove binomial via generating functions.",
  "selected_model": "model_optimal_v2",
  "free_energy": -0.234,
  "feasible": true,
  "shadow_prices": [0.12, 0.08],
  "drift_signal": 0.03,
  "quality_score": 0.89,
  "latency_ms": 145,
  "boundary_gap": 0.15,
  "entropy": 0.42
}

🎯 Next Steps: Your Loop

graph TD
    A[✅ Installation Complete] --> B[Run Demo]
    B --> C{High Drift?}
    C -->|Yes| D[Tweak trust_radius=0.5]
    C -->|No| E[Analyze Results]
    D --> B
    E --> F[Scale to Batch]
    F --> G[Visualize in Cookbook]
    G --> H[Dive Deeper]
    H --> I[Advanced Configs]
    H --> J[Contribute PR]
    
    style A fill:#4caf50,color:#fff
    style E fill:#2196f3,color:#fff
    style J fill:#9c27b0,color:#fff
Loading

🚀 Progression Path

  1. 🏃 Run & Reflect

    • Execute the demo
    • High drift? Tweak trust_radius=0.5 in configs

  2. 📈 Scale It

    • Batch prompts via script
    • Visualize certificates in Cookbook

  3. 🔨 Build On

    • Dive to Usage-Guide for advanced flags
    • PR your first tweak

📚 Additional Resources

mindmap
  root((Compitum<br/>Resources))
    Documentation
      Getting Started
      Usage Guide
      CLI Reference
      Configuration
      Glossary
    Community
      GitHub Issues
      Discussions
      Contributing
    Learning
      Tutorials
      Cookbook
      Examples
      Best Practices
    Tools
      CLI
      Python API
      Trace Viewer
      Config Editor
Loading

🔗 Key Links

🎓 Educational Framework

Learning Objectives Alignment

Level Objective Compitum Feature Assessment
Beginner Understand routing basics Demo route Successful JSON output
Intermediate Analyze constraints Certificate inspection Shadow price interpretation
Advanced Optimize parameters Config tuning Improved metrics
Expert Contribute features PR workflow Code acceptance

🏆 Success Metrics

After completing this guide, you should be able to:

  • ✅ Clone and install Compitum in under 10 minutes
  • ✅ Run your first route and generate a certificate
  • ✅ Interpret basic signals (energy, drift, shadows)
  • ✅ Identify boundary conditions
  • ✅ Scale to batch processing
  • ✅ Navigate documentation confidently
graph LR
    A[Complete Guide] --> B{Can Run Route?}
    B -->|Yes| C{Understand Cert?}
    B -->|No| D[Review Installation]
    C -->|Yes| E{Ready to Scale?}
    C -->|No| F[Review Analysis]
    E -->|Yes| G[🌟 Onboarding Success!]
    E -->|No| H[Practice More]
    
    D --> A
    F --> C
    H --> E
    
    style G fill:#4caf50,color:#fff,stroke:#2e7d32,stroke-width:3px
Loading

Happy Routing! 🚀

Questions? Check our GitHub Discussions or open an Issue

Compitum Wiki

Getting Started

Usage Guide

Core Concepts

Mathematics

Development & Integration

Community & Support

Clone this wiki locally