Skip to content

Cookbook

Jump to bottom
PaulTiffany edited this page Nov 14, 2025 · 4 revisions

Cookbook: Ready-to-Run Recipes for Compitum Tasks

Quick-Scan Infobox

Aspect Details
Target User Educators preparing demonstrations, developers integrating components—basic command-line and Python knowledge assumed.
Core Goal Provide steps for common tasks, from single routes to performance checks, with focus on inspection and adjustment.
Time to First Recipe 1 minute: Copy a command, run it in the terminal.
Key Analogy A set of prepared instructions: Select based on need, follow sequentially, review results to understand adjustments.
Customization Tip Replace placeholders (such as prompts) with your values; test on small inputs first.
Known Limitation Recipes assume a working installation; high-load tasks may need hardware adjustments.

Core Workflow: Steps for Using Recipes

This section outlines the sequence for most recipes: Prepare inputs and settings, run the command or script, review the output, and adjust based on signals. Each step connects to Compitum's components, such as constraints and certificates, to build understanding.

graph TB
    subgraph Prep["1. Prepare Inputs"]
        I1["Define prompt<br/>Example: 'Classify quadratic roots'"]
        I2["Select config<br/>configs/edu_demo.yaml"]
        I3["Set variables<br/>COMPITUM_TRACE=1"]
        I4["Choose recipe<br/>From sections below"]
    end
   
    subgraph Run["2. Execute"]
        C1["Run command<br/>compitum route ..."]
        C2["Compute signals<br/>Free energy, shadow prices"]
        C3["Select option<br/>Based on utility"]
    end
   
    subgraph Review["3. Inspect Results"]
        S1["Certificate JSON<br/>Audit details"]
        S2["Metrics summary<br/>Free energy: -0.03"]
        S3["Flags<br/>Boundary: Safe"]
        S4["Shadow prices<br/>Latency: 0.2"]
    end
   
    subgraph Adjust["4. Refine"]
        L1["Review traces<br/>jq '.drift_signal'"]
        L2["Update settings<br/>Adjust constraints"]
        L3["Repeat process<br/>For next task"]
    end
   
    Prep --> Run
    Run --> Review
    Review --> Adjust
    Adjust -.-> Prep
   
    style Prep fill:#e3f2fd,stroke:#01579b
    style Run fill:#e8f5e9,stroke:#1b5e20
    style Review fill:#fff3e0,stroke:#ef6c00
    style Adjust fill:#fce4ec,stroke:#c2185b
Loading

Caption: Sequence of steps for a recipe, showing preparation to refinement. Alt text: Flow diagram with four subgraphs for inputs, execution, review, and adjustment, connected in a loop with fewer than 15 nodes.

This workflow ensures each use reveals how geometry and controls affect outcomes. Limitation: Outputs vary with data; compare across runs for patterns.

Recipe Categories

Index of Recipes

mindmap
  root((Cookbook))
    Quickstart Recipes
      Single Route Trace
      Batch Processing
      Interactive REPL
    Analysis Recipes
      Certificate Inspection
      Metric Extraction
      Convergence Plots
    Integration Recipes
      Context Pack Building
      API Endpoint Setup
      Webhook Routing
    Testing Recipes
      Smoke Benchmarks
      Stability Verification
      Pre-Commit Checks
    Education Recipes
      Classroom Demo
      Student Portfolio
      Constraint Experiments
    Production Recipes
      Docker Deploy
      Load Testing
      Monitoring Setup
Loading

Caption: Hierarchical view of recipe groups and examples. Alt text: Mind map with root "Cookbook" branching to categories and sub-items.

Quickstart Recipes

Recipe 1: Single Route Trace

Goal: Process one prompt and save the certificate for review.
Time: 30 seconds.
Difficulty: Beginner.
Link to Concepts: Shows immediate signals, as in philosophy's feedback mechanisms.

Ingredients:

  • A prompt (any task or question).
  • Terminal access.

Steps:

# Run route and save trace
compitum route \
  --prompt "Explain the Pythagorean theorem for 8th graders" \
  --trace \
  > pythagorean_trace.json
# View structure
cat pythagorean_trace.json | jq '.'

Expected Output:

{
  "prompt": "Explain the Pythagorean theorem...",
  "selected_model": "claude-sonnet-4.5",
  "utility": 7.8,
  "free_energy": -2.3,
  "drift_signal": -0.03,
  "constraints": {
    "latency": {"bound": 2.0, "actual": 1.4, "slack": 0.6},
    "cost": {"bound": 0.01, "actual": 0.006, "slack": 0.004}
  },
  "shadow_prices": {"latency": 0.12, "cost": 0.45},
  "utility_components": {
    "quality": 0.85,
    "coherence": -0.8,
    "diversity": 0.92
  },
  "boundary_flag": false,
  "entropy": 1.87,
  "feasible": true
}

Note: Values depend on current models and settings; negative drift indicates descent.

Review Points:

  • Drift signal less than 0: Confirms free energy decrease.
  • All slacks at least 0: Verifies feasibility.
  • Shadow prices: Identify active constraints.
  • Boundary flag: Checks for narrow margins.

Educational Use:

# For a class prompt
compitum route \
  --prompt "Why did the Roman Empire fall?" \
  --trace \
  | tee rome_trace.json \
  | jq '.utility_components'
# Output:  
# {"quality": 0.85, "coherence": -0.8, "diversity": 0.92}  
# Discuss: Low coherence suggests need for focused prompts.

Montessori Parallel: Like matching blocks, the certificate provides self-check—students review signals to refine their questions.

Customizations:

  • Custom config: COMPITUM_CONFIG=configs/strict_edu.yaml compitum route --prompt "..." --trace > trace.json.
  • Add context: compitum route --prompt "Summarize this paper" --context paper.txt --trace > summary_trace.json.
  • Limit steps: compitum route --prompt "..." --max-steps 3 --trace > quick_trace.json.

Trace Review with jq:

# Drift value
jq '.drift_signal' trace.json
# Output: -0.03  
# Constraints with low slack
jq '.constraints | to_entries[] | select(.value.slack < 0.1)' trace.json
# Output: [{"key":"cost","value":{"bound":0.01,"actual":0.009,"slack":0.001}}] (if applicable)

Limitation: Single runs may not show trends; use batch for patterns.

Recipe 2: Batch Processing with Convergence Tracking

Goal: Handle multiple prompts and monitor changes over runs.
Time: 5 minutes.
Difficulty: Intermediate.
Link to Concepts: Tracks free energy descent for stability.

Ingredients:

  • File of prompts (prompts.txt).

Create Prompts File (prompts.txt):

Explain photosynthesis simply
What causes ocean tides?
How do vaccines work?
Describe the water cycle
Why is the sky blue?

Batch Script (batch_route.sh):

#!/bin/bash
OUTPUT_DIR="batch_results"
mkdir -p "$OUTPUT_DIR"
PROMPT_NUM=0
while IFS= read -r prompt; do
  PROMPT_NUM=$((PROMPT_NUM + 1))
  echo "Processing prompt $PROMPT_NUM: $prompt"
 
  compitum route \
    --prompt "$prompt" \
    --trace \
    > "$OUTPUT_DIR/trace_${PROMPT_NUM}.json"
 
  DRIFT=$(jq -r '.drift_signal' "$OUTPUT_DIR/trace_${PROMPT_NUM}.json")
  echo "$PROMPT_NUM,$DRIFT" >> "$OUTPUT_DIR/drift_series.csv"
 
done < prompts.txt
echo "Convergence Summary:"
python3 << EOF
import json
import glob
drifts = []
for f in sorted(glob.glob("$OUTPUT_DIR/trace_*.json")):
    with open(f) as trace:
        cert = json.load(trace)
        drifts.append(cert['drift_signal'])
avg_drift = sum(drifts) / len(drifts)
print(f"Average drift: {avg_drift:.4f}")
print(f"Drift trend: {'Descending' if drifts[-1] < drifts[0] else 'Check config'}")
print(f"All negative? {'Yes' if all(d < 0 for d in drifts) else 'Some positive'}")
EOF

Expected Output from Python:

Average drift: -0.0250
Drift trend: Descending
All negative? Yes

Run:

chmod +x batch_route.sh
./batch_route.sh

Visualization Script (plot_convergence.py):

[Notebook content will be embedded by CI]

Run: python3 plot_convergence.py. Output: PNG file with three plots showing trends.

Limitation: Assumes consistent settings; varying prompts may affect comparisons.

Recipe 3: Interactive REPL for Experimentation

Goal: Adjust and test routes in a loop.
Time: 2 minutes setup.
Difficulty: Intermediate.
Link to Concepts: Supports bounded exploration.

REPL Script (repl.py):

[Notebook content will be embedded by CI]

Usage Examples:

[Notebook content will be embedded by CI]

Note: Full JSON as in Recipe 1.

Limitation: Interactive mode suits small tests; for scale, use batch.

Analysis Recipes

Recipe 4: Certificate Inspection with Plots

Goal: Visualize certificate details for decisions.
Time: 10 minutes.
Difficulty: Advanced.
Link to Concepts: Highlights shadow prices for sensitivity.

Analysis Script (analyze_certificate.py):

[Notebook content will be embedded by CI]

Expected Output:

Analysis saved to analysis/certificate_analysis.png
Recommendations:

Entropy balanced.
High shadow prices:
 cost: λ=0.55, actual 0.009 / bound 0.01
 Relaxing by 20% gains ~0.11 utility.

============================================================
Summary:
Model: claude-sonnet-4.5
Utility: 7.8
Feasible: Yes

Note: PNG shows bars and text summary; adjust for your data.

Run: python3 analyze_certificate.py pythagorean_trace.json.

Limitation: Plots assume matplotlib; for batch, loop over files.

Integration Recipes

Recipe 5: Building Context Packs

Goal: Assemble budgeted context for routing or other uses.
Time: 5 minutes.
Difficulty: Intermediate.
Link to Concepts: Uses SPD metrics for coherence in additions.

Basic Command:

# Build from repo
python tools/build_llm_context_pack.py \
  --out context_pack.jsonl \
  --target-size 1MB \
  --include "src/**/*.py" "docs/**/*.md" \
  --exclude "tests/**" "**/__pycache__/**"
# Check size
wc -l context_pack.jsonl
du -h context_pack.jsonl

Expected Output:

500 context_pack.jsonl
1.0M	context_pack.jsonl

Advanced:

# With priorities
python tools/build_llm_context_pack.py \
  --out custom_pack.jsonl \
  --target-size 500KB \
  --include "src/router.py" "src/observers/*.py" "docs/Philosophy.md" \
  --prioritize "router,observers,philosophy" \
  --format "jsonl"

For Education:

# Student work
python tools/build_llm_context_pack.py \
  --out student_alice_context.jsonl \
  --target-size 200KB \
  --include "assignments/alice/**/*.md" \
  --metadata '{"student": "alice", "subject": "literature", "grade": "10"}'

Output Format (JSONL):

{"source": "src/router.py", "content": "class Router:\n...", "tokens": 1523, "type": "code"}
{"source": "docs/Philosophy.md", "content": "# Philosophy...", "tokens": 4231, "type": "markdown"}

Use with Router:

compitum route \
  --prompt "Explain constraint shadows" \
  --context-pack context_pack.jsonl \
  --trace > explained_trace.json

Limitation: Token counts approximate; verify with tokenizer for precision.

Recipe 6: API Endpoint Setup

Goal: Expose routing as a service.
Time: 15 minutes.
Difficulty: Advanced.
Link to Concepts: Applies bounded locality to requests.

Server Script (api_server.py):

[Notebook content will be embedded by CI]

Run:

pip install fastapi uvicorn pydantic
python api_server.py

Test:

# Health
curl http://localhost:8000/health
# Output: {"status":"healthy","router":"ready"}  
# Route
curl -X POST http://localhost:8000/route \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Explain photosynthesis", "trace": true}'
# Output: JSON with response, model, utility, certificate (as in Recipe 1)
# Update
curl -X POST "http://localhost:8000/config/update?constraint_name=latency&value=1.5"
# Output: {"message":"Updated latency = 1.5"}

Client Example:

[Notebook content will be embedded by CI]

Output: Model: gpt-4o, Utility: 8.2, etc.

Dockerfile:

FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY src/ ./src/
COPY configs/ ./configs/
COPY api_server.py .
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:8000/health || exit 1
CMD ["uvicorn", "api_server:app", "--host", "0.0.0.0", "--port", "8000"]

Deploy: docker-compose up -d (with compose file for volumes, ports).

Limitation: Handles moderate load; scale with multiple instances for high traffic.

Testing Recipes

Recipe 7: Smoke Benchmarks

Goal: Confirm basic function without full tests.
Time: 2 minutes.
Difficulty: Beginner.
Link to Concepts: Verifies free energy descent.

Command:

COMPITUM_SKIP_ASSERTIONS=1 \
COMPITUM_MAX_STEPS=400 \
pytest -q -k "smoke" --benchmark-min-time=0.01

Expected Output:

tests/test_smoke.py .... [100%]
4 passed in 1.23s

Custom Test (tests/test_custom_smoke.py):

[Notebook content will be embedded by CI]

Run: pytest tests/test_custom_smoke.py -v. Output: Passed/Failed details.

Limitation: Skips deep checks; follow with full verification.

Recipe 8: Pre-Commit Hooks

Goal: Check code and configs before commits.
Time: 3 minutes setup.
Difficulty: Intermediate.
Link to Concepts: Enforces quality bounds.

Install: pip install pre-commit.

Config (.pre-commit-config.yaml):

repos:
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.32.0
    hooks:
      - id: yamllint
        args: [--strict]
        files: ^configs/.*\.yaml$
  - repo: https://github.com/psf/black
    rev: 23.7.0
    hooks:
      - id: black
        language_version: python3.10
  - repo: https://github.com/PyCQA/flake8
    rev: 6.1.0
    hooks:
      - id: flake8
        args: [--max-line-length=100]
  - repo: https://github.com/PyCQA/isort
    rev: 5.12.0
    hooks:
      - id: isort
        args: [--profile=black]
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.5.1
    hooks:
      - id: mypy
        additional_dependencies: [types-all]
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.40.0
    hooks:
      - id: mdl
        args: [--style, relaxed]
  - repo: local
    hooks:
      - id: compitum-smoke
        name: Compitum Smoke Tests
        entry: bash -c 'COMPITUM_SKIP_ASSERTIONS=1 pytest -q -k smoke'
        language: system
        pass_filenames: false
        stages: [commit]

Activate:

pre-commit install
pre-commit run --all-files

Output: Linting results, e.g., "Black reformatted X files".

Custom Hooks Example: Add to config for certificate validation, etc.

Limitation: System-dependent; test on clean clone.

Education Recipes

Recipe 9: Classroom Demonstration with Analysis

Goal: Show routing live, with group review.
Time: 30 minutes.
Difficulty: Intermediate.
Link to Concepts: Applies reflection loops.

Demo Script (classroom_demo.sh):

#!/bin/bash
DEMO_DIR="classroom_demo_$(date +%Y%m%d)"
mkdir -p "$DEMO_DIR"
demo_route() {
    local prompt="$1"
    local explanation="$2"
    echo "Student Question: \"$prompt\""
    echo ""
    echo "Routing..."
    compitum route --prompt "$prompt" --trace > "$DEMO_DIR/trace_$$.json"
    echo ""
    echo "Certificate Generated!"
    echo ""
    DRIFT=$(jq -r '.drift_signal' "$DEMO_DIR/trace_$$.json")
    ENTROPY=$(jq -r '.entropy' "$DEMO_DIR/trace_$$.json")
    MODEL=$(jq -r '.selected_model' "$DEMO_DIR/trace_$$.json")
    UTILITY=$(jq -r '.utility' "$DEMO_DIR/trace_$$.json")
    echo "Metrics:"
    echo " • Model: $MODEL"
    echo " • Utility: $UTILITY"
    echo " • Drift: $DRIFT (negative = descent)"
    echo " • Entropy: $ENTROPY (>1.0 = diverse)"
    echo ""
    echo "Constraints:"
    jq -r '.constraints | to_entries[] | " • \(.key): \(.value.actual) / \(.value.bound) (slack: \(.value.slack))"' \
        "$DEMO_DIR/trace_$$.json"
    echo ""
    echo "Shadow Prices:"
    jq -r '.shadow_prices | to_entries[] | " • \(.key): λ=\(.value) \(if .value > 0.5 then "(limiting)" elif .value > 0.1 then "(active)" else "(room)" end)"' \
        "$DEMO_DIR/trace_$$.json"
    echo ""
    echo "$explanation"
    echo ""
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    echo ""
    read -p "Press Enter to continue..."
    echo ""
}
demo_route \
    "Explain the water cycle simply" \
    "Low shadow prices indicate flexibility for exploration."
demo_route \
    "Write a detailed technical analysis of quantum computing with extensive mathematical proofs and advanced theoretical frameworks requiring deep expertise" \
    "High latency shadow price shows adaptation to time limits."
demo_route \
    "Why is the sky blue?" \
    "Negative drift confirms stability across steps."
echo "Comparative Analysis"
echo "======================="
echo ""
echo "Route,Drift,Entropy,Utility,Model" > "$DEMO_DIR/summary.csv"
for trace in "$DEMO_DIR"/trace_*.json; do
    DRIFT=$(jq -r '.drift_signal' "$trace")
    ENTROPY=$(jq -r '.entropy' "$trace")
    UTILITY=$(jq -r '.utility' "$trace")
    MODEL=$(jq -r '.selected_model' "$trace")
    PROMPT=$(jq -r '.prompt' "$trace" | cut -c1-30)
    echo "\"$PROMPT...\",$DRIFT,$ENTROPY,$UTILITY,$MODEL" >> "$DEMO_DIR/summary.csv"
done
column -t -s',' "$DEMO_DIR/summary.csv"
echo ""
echo "Discussion Questions:"
echo " 1. Why negative drift in all?"
echo " 2. Highest entropy prompt?"
echo " 3. Effect of tighter latency?"
echo " 4. Shadow prices as indicators?"
echo ""
echo "Demo complete! Traces in: $DEMO_DIR"

Expected Output: Metrics and tables for each prompt, CSV summary like:

Route                    Drift  Entropy  Utility  Model
"Explain the water..."  -0.02  1.85     7.5      claude-sonnet-4.5

Run: chmod +x classroom_demo.sh; ./classroom_demo.sh.

Montessori Parallel: Students observe signals like material errors, adjusting independently for growth.

Portfolio Builder (build_student_portfolio.py):

[Notebook content will be embedded by CI]

Run: python build_student_portfolio.py "Alice Smith" traces/alice/. Output: HTML and PNG files.

Limitation: Requires traces named by student; organize files accordingly.

Production Recipes

Recipe 10: Load Testing and Profiling

Goal: Test under load for readiness.
Time: 20 minutes.
Difficulty: Advanced.
Link to Concepts: Extends observation to scale.

Load Test (locustfile.py):

[Notebook content will be embedded by CI]

Run:

pip install locust
locust -f locustfile.py --host http://localhost:8000 \
  --users 10 --spawn-rate 2 --run-time 5m

Targets: <500ms 95th percentile latency, >95% success.

Headless:

locust -f locustfile.py --host http://localhost:8000 \
  --users 50 --spawn-rate 5 --run-time 10m \
  --headless --html load_test_report.html

Output: HTML report with stats.

Profile Script (profile_router.py):

[Notebook content will be embedded by CI]

Run: python profile_router.py. Output: Top functions by time, e.g., "router.route 100 calls 5.2s". View with snakeviz profile_output.prof.

Memory Profile:

[Notebook content will be embedded by CI]

Run: pip install memory-profiler; python -m memory_profiler memory_profile.py. Output: Line-by-line memory use, e.g., "Line # Mem usage Increment".

Limitation: Locust simulates; real traffic may differ—monitor in deployment.

Advanced Workflow Recipes

Recipe 11: Multi-Stage Pipeline with Checks

Goal: Sequence routing, validation, and refinement.
Time: 15 minutes.
Difficulty: Advanced.
Link to Concepts: Builds iterative loops.

Pipeline Script (pipeline.py):

[Notebook content will be embedded by CI]

Expected Output:

Starting Pipeline for: 'Explain machine learning for beginners...'

Stage 1: Initial Routing...
Validation passed
Stage 3: Context Enrichment...
Context added
Stage 4: Finalization...
Pipeline complete - Quality: 8.1
Pipeline trace saved to pipeline_trace.json

============================================================
PIPELINE SUMMARY
============================================================
Stage 1 (initial): Utility=7.5, Drift=-0.02
Stage 2 (enriched): Utility=8.1, Drift=-0.01
Stage 3 (enriched): Utility=8.1, Drift=-0.01

Run: python pipeline.py.

Limitation: Context files must exist; handle errors for missing sources.

Quick-Reference Toolkit

Recipe Index by Use Case

mindmap
  root((Recipe
Index))
    Getting Started
      Recipe 1: First Trace
      Recipe 2: Batch Processing
      Recipe 3: Interactive REPL
    Analysis
      Recipe 4: Certificate Viz
      Custom Signal Analysis
      Convergence Tracking
    Integration
      Recipe 5: Context Packs
      Recipe 6: API Deployment
      Docker Production
    Testing
      Recipe 7: Smoke Tests
      Recipe 8: Pre-Commit
      Load Testing
    Education
      Recipe 9: Classroom Demo
      Student Portfolios
      Constraint Experiments
    Production
      Recipe 10: Load Testing
      Performance Profiling
      Recipe 11: Pipelines
Loading

Caption: Mind map of recipes by category. Alt text: Branching diagram from index to sub-recipes.

Command Summary

Need Command Time
Quick trace compitum route --prompt "..." --trace > t.json 10s
Batch 10 prompts while read p; do compitum route --prompt "$p" --trace; done < prompts.txt 2m
Analyze certificate python analyze_certificate.py trace.json 30s
Smoke test COMPITUM_SKIP_ASSERTIONS=1 pytest -q -k smoke 1m
Start API uvicorn api_server:app --reload 5s
Load test locust -f locustfile.py --headless -u 50 -r 5 -t 5m 5m
Build context python tools/build_llm_context_pack.py --out pack.jsonl 1m
Pre-commit setup pre-commit install && pre-commit run --all 3m

Technical Details

Recipes use CLI for traces (JSON certificates with drift, shadow prices) and environment variables for tuning. They call router.route() or tests, respecting constraints per configuration.

Implementation Notes:

  • Traces: Stdout to JSON for analysis with jq or scripts.
  • Packs: Token-limited JSONL from sources.
  • Benchmarks: Skip heavy computations for speed.
  • Hooks: Lint and test on commit.

Limitation: Relies on installation; verify paths.

Common Issues and Fixes

Issue Symptom Fix Prevention
No trace output Empty file Add --trace; check prompt Include flag in templates
Benchmark timeout Hangs >30s Set UPDATE_BATCH_SIZE=50000; STEPS=200 Use small defaults
Pack over budget >1MB --target-size 800KB; exclude tests Estimate tokens
Pre-commit fails Lint errors Run yamllint configs/ IDE plugins
API errors 500 status Check logs; validate config Add checks
Memory growth Unbounded RAM Limit batch; clear cache Profile regularly
Slow descent Drift unchanged Adjust radius; review constraints Use analysis tool
Invalid certificate Missing fields Update version; regenerate Schema validation

Next Steps: Extend Recipes

For Beginners:

  1. Run Recipe 1 with a prompt.
  2. Use jq on the JSON.
  3. Compare two runs.

For Educators:

  1. Use Recipe 9 in class.
  2. Generate portfolios.
  3. Adapt for subjects.

For Developers:

  1. Deploy Recipe 6.
  2. Add Recipes 7-8 to pipeline.
  3. Test load with 10.

For Researchers:

  1. Sweep parameters with 2.
  2. Profile with 10.
  3. Chain with 11.

Contribute Recipes: Test, document, PR to recipes/community/. Use template: Goal, time, difficulty, link, ingredients, steps, output, troubleshooting.

Related Pages: Configuration for settings; Philosophy for rationale; Usage-Guide for flags; Verification for tests; Output-Format for JSON; API-Reference for code.

Last Updated: November 08, 2025 · Compitum v1.0+

Compitum Wiki

Getting Started

Usage Guide

Core Concepts

Mathematics

Development & Integration

Community & Support

Clone this wiki locally