## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# VAPORA Examples Guide

Comprehensive guide to understanding and using VAPORA's example collection.

## Overview

VAPORA includes 26+ runnable examples demonstrating all major features:

- 6 Basic examples - Hello world for each component
- 9 Intermediate examples - Multi-system integration patterns
- 2 Advanced examples - End-to-end full-stack workflows
- 3 Real-world examples - Production scenarios with ROI analysis
- 4 Interactive notebooks - Marimo-based exploration (requires Python)

Total time to explore all examples: 2-3 hours

## Quick Start

### Run Your First Example

    # Navigate to workspace root
    cd /path/to/vapora

    # Run basic agent example
    cargo run --example 01-simple-agent -p vapora-agents

Expected output:

    === Simple Agent Registration Example ===

    Created agent registry with capacity 10
    Defined agent: "Developer A" (role: developer)
    Capabilities: ["coding", "testing"]

    Agent registered successfully
    Agent ID: <uuid>

### List All Available Examples

    # Per-crate examples
    cargo build --examples -p vapora-agents

    # All examples in workspace
    cargo build --examples --workspace

## Examples by Category

### Phase 1: Basic Examples (Foundation)

Start here to understand individual components.

#### Agent Registry

File: `crates/vapora-agents/examples/01-simple-agent.rs`

What it demonstrates:

- Creating an agent registry
- Registering agents with metadata
- Querying registered agents
- Agent status management

Run:

    cargo run --example 01-simple-agent -p vapora-agents

Key concepts:

- `AgentRegistry` - thread-safe registry with capacity limits
- `AgentMetadata` - agent name, role, capabilities, LLM provider
- `AgentStatus` - Active, Busy, Offline

Time: 5-10 minutes

#### LLM Provider Selection

File: `crates/vapora-llm-router/examples/01-provider-selection.rs`

What it demonstrates:

- Available LLM providers (Claude, GPT-4, Gemini, Ollama)
- Provider pricing and use cases
- Routing rules by task type
- Cost comparison

Run:

    cargo run --example 01-provider-selection -p vapora-llm-router

Key concepts:

- Provider routing rules
- Cost per 1M tokens
- Fallback strategy
- Task type matching

Time: 5-10 minutes

#### Swarm Coordination

File: `crates/vapora-swarm/examples/01-agent-registration.rs`

What it demonstrates:

- Swarm coordinator creation
- Agent registration with capabilities
- Swarm statistics
- Load balancing basics

Run:

    cargo run --example 01-agent-registration -p vapora-swarm

Key concepts:

- `SwarmCoordinator` - manages agent pool
- Agent capabilities filtering
- Load distribution calculation
- `success_rate / (1 + current_load)` scoring

Time: 5-10 minutes

#### Knowledge Graph

File: `crates/vapora-knowledge-graph/examples/01-execution-tracking.rs`

What it demonstrates:

- Recording execution history
- Querying executions by agent/task type
- Cost analysis per provider
- Success rate calculations

Run:

    cargo run --example 01-execution-tracking -p vapora-knowledge-graph

Key concepts:

- `ExecutionRecord` - timestamp, duration, success, cost
- Temporal queries (last 7/14/30 days)
- Provider cost breakdown
- Success rate trends

Time: 5-10 minutes

#### Backend Health Check

File: `crates/vapora-backend/examples/01-health-check.rs`

What it demonstrates:

- Backend service health status
- Dependency verification
- Monitoring endpoints
- Troubleshooting guide

Run:

    cargo run --example 01-health-check -p vapora-backend

Prerequisites:

- Backend running: `cd crates/vapora-backend && cargo run`
- SurrealDB running: `docker run -d surrealdb/surrealdb:latest`

Key concepts:

- Health endpoint status
- Dependency checklist
- Prometheus metrics endpoint
- Startup verification

Time: 5-10 minutes

#### Error Handling

File: `crates/vapora-shared/examples/01-error-handling.rs`

What it demonstrates:

- Custom error types
- Error propagation with `?`
- Error context
- Display and Debug implementations

Run:

    cargo run --example 01-error-handling -p vapora-shared

Key concepts:

- `Result<T>` pattern
- Error types (InvalidInput, NotFound, Unauthorized)
- Error chaining
- User-friendly messages

Time: 5-10 minutes

### Phase 2: Intermediate Examples (Integration)

Combine 2-3 systems to solve realistic problems.

#### Learning Profiles

File: `crates/vapora-agents/examples/02-learning-profile.rs`

What it demonstrates:

- Building expertise profiles from execution history
- Recency bias weighting (recent 7 days weighted 3× higher)
- Confidence scaling based on sample size
- Task type specialization

Run:

    cargo run --example 02-learning-profile -p vapora-agents

Key metrics:

- Success rate: percentage of successful executions
- Confidence: increases with sample size (0-1.0)
- Recent trend: last 7 days weighted heavily
- Task type expertise: separate profiles per task type

Real scenario: Agent Alice has 93.3% success rate on coding (28/30 executions over 30 days), with confidence 1.0 from ample data.

Time: 10-15 minutes

#### Agent Selection Scoring

File: `crates/vapora-agents/examples/03-agent-selection.rs`

What it demonstrates:

- Ranking agents for task assignment
- Scoring formula: `(1 - 0.3*load) + 0.5*expertise + 0.2*confidence`
- Load balancing prevents over-allocation
- Why confidence matters

Run:

    cargo run --example 03-agent-selection -p vapora-agents

Scoring breakdown:

- Availability: `1 - (0.3 * current_load)` - lower load = higher score
- Expertise: `0.5 * success_rate` - proven capability
- Confidence: `0.2 * confidence` - trust the data

Real scenario: Three agents competing for coding task:

- Alice: 0.92 expertise, 30% load → score 0.71
- Bob: 0.78 expertise, 10% load → score 0.77 (selected despite lower expertise)
- Carol: 0.88 expertise, 50% load → score 0.59

Time: 10-15 minutes

#### Budget Enforcement

File: `crates/vapora-llm-router/examples/02-budget-enforcement.rs`

What it demonstrates:

- Per-role budget limits (monthly/weekly)
- Three-tier enforcement: Normal → Caution → Exceeded
- Automatic fallback to cheaper providers
- Alert thresholds

Run:

    cargo run --example 02-budget-enforcement -p vapora-llm-router

Budget tiers:

- 0-50%: Normal - use preferred provider (Claude)
- 50-80%: Caution - monitor spending closely
- 80-100%: Near threshold - use cheaper alternative (GPT-4)
- 100%+: Exceeded - use fallback only (Ollama)

Real scenario: Developer role with $300/month budget:

- Spend $145 (48% used) - in Normal tier
- All tasks use Claude (highest quality)
- If reaches $240+ (80%), automatically switch to cheaper providers

Time: 10-15 minutes

#### Cost Tracking

File: `crates/vapora-llm-router/examples/03-cost-tracking.rs`

What it demonstrates:

- Token usage recording per provider
- Cost calculation by provider and task type
- Report generation
- Cost per 1M tokens analysis

Run:

    cargo run --example 03-cost-tracking -p vapora-llm-router

Report includes:

- Total cost (cents or dollars)
- Cost by provider (Claude, GPT-4, Gemini, Ollama)
- Cost by task type (coding, testing, documentation)
- Average cost per task
- Cost efficiency (tokens per dollar)

Real scenario: 4 tasks processed:

- Claude (2 tasks): 3,500 tokens → $0.067
- GPT-4 (1 task): 4,500 tokens → $0.130
- Gemini (1 task): 4,500 tokens → $0.053
- Total: $0.250

Time: 10-15 minutes

#### Task Assignment

File: `crates/vapora-swarm/examples/02-task-assignment.rs`

What it demonstrates:

- Submitting tasks to swarm
- Load-balanced agent selection
- Capability filtering
- Swarm statistics

Run:

    cargo run --example 02-task-assignment -p vapora-swarm

Assignment algorithm:

1. Filter agents by required capabilities
2. Score each agent: `success_rate / (1 + current_load)`
3. Assign to highest-scoring agent
4. Update swarm statistics

Real scenario: Coding task submitted to swarm with 3 agents:

- agent-1: coding ✓, load 20%, success 92% → score 0.77
- agent-2: coding ✓, load 10%, success 85% → score 0.77 (selected, lower load)
- agent-3: code_review only ✗ (filtered out)

Time: 10-15 minutes

#### Learning Curves

File: `crates/vapora-knowledge-graph/examples/02-learning-curves.rs`

What it demonstrates:

- Computing learning curves from daily data
- Success rate trends over 30 days
- Recency bias impact
- Performance trend analysis

Run:

    cargo run --example 02-learning-curves -p vapora-knowledge-graph

Metrics tracked:

- Daily success rate (0-100%)
- Average execution time (milliseconds)
- Recent 7-day success rate
- Recent 14-day success rate
- Weighted score with recency bias

Trend indicators:

- ✓ IMPROVING: Agent learning over time
- → STABLE: Consistent performance
- ✗ DECLINING: Possible issues or degradation

Real scenario: Agent bob over 30 days:

- Days 1-15: 70% success rate, 300ms/execution
- Days 16-30: 70% success rate, 300ms/execution
- Weighted score: 72% (no improvement detected)
- Trend: STABLE (consistent but not improving)

Time: 10-15 minutes

#### Similarity Search

File: `crates/vapora-knowledge-graph/examples/03-similarity-search.rs`

What it demonstrates:

- Semantic similarity matching
- Jaccard similarity scoring
- Recommendation generation
- Pattern recognition

Run:

    cargo run --example 03-similarity-search -p vapora-knowledge-graph

Similarity calculation:

- Input: New task description ("Implement API key authentication")
- Compare: Against past execution descriptions
- Score: Jaccard similarity (intersection / union of keywords)
- Rank: Sort by similarity score

Real scenario: New task: "Implement API key authentication for third-party services" Keywords: ["authentication", "API", "third-party"]

Matches against past tasks:

1. "Implement user authentication with JWT" (87% similarity)
2. "Implement token refresh mechanism" (81% similarity)
3. "Add API rate limiting" (79% similarity)

→ Recommend: "Use OAuth2 + API keys with rotation strategy"

Time: 10-15 minutes

### Phase 3: Advanced Examples (Full-Stack)

End-to-end integration of all systems.

#### Agent with LLM Routing

File: `examples/full-stack/01-agent-with-routing.rs`

What it demonstrates:

- Agent executes task with intelligent provider selection
- Budget checking before execution
- Cost tracking during execution
- Provider fallback strategy

Run:

    rustc examples/full-stack/01-agent-with-routing.rs -o /tmp/example && /tmp/example

Workflow:

1. Initialize agent (developer-001)
2. Set task (implement authentication, 1,500 input + 800 output tokens)
3. Check budget ($250 remaining)
4. Select provider (Claude for quality)
5. Execute task
6. Track costs ($0.069 total)
7. Update learning profile

Time: 15-20 minutes

#### Swarm with Learning Profiles

File: `examples/full-stack/02-swarm-with-learning.rs`

What it demonstrates:

- Swarm coordinates agents with learning profiles
- Task assignment based on expertise
- Load balancing with learned preferences
- Profile updates after execution

Run:

    rustc examples/full-stack/02-swarm-with-learning.rs -o /tmp/example && /tmp/example

Workflow:

1. Register agents with learning profiles
   - alice: 92% coding, 60% testing, 30% load
   - bob: 78% coding, 85% testing, 10% load
   - carol: 90% documentation, 75% testing, 20% load
2. Submit tasks (3 different types)
3. Swarm assigns based on expertise + load
4. Execute tasks
5. Update learning profiles with results
6. Verify assignments improved for next round

Time: 15-20 minutes

### Phase 5: Real-World Examples

Production scenarios with business value analysis.

#### Code Review Pipeline

File: `examples/real-world/01-code-review-workflow.rs`

What it demonstrates:

- Multi-agent code review workflow
- Cost optimization with tiered providers
- Quality vs cost trade-off
- Business metrics (ROI, time savings)

Run:

    rustc examples/real-world/01-code-review-workflow.rs -o /tmp/example && /tmp/example

Three-stage pipeline:

Stage 1 (Ollama - FREE):

- Static analysis, linting
- Dead code detection
- Security rule violations
- Cost: $0.00/PR, Time: 5s

Stage 2 (GPT-4 - $10/1M):

- Logic verification
- Test coverage analysis
- Performance implications
- Cost: $0.08/PR, Time: 15s

Stage 3 (Claude - $15/1M, 10% of PRs):

- Architecture validation
- Design pattern verification
- Triggered for risky changes
- Cost: $0.20/PR, Time: 30s

Business impact:

- Volume: 50 PRs/day
- Cost: $0.60/day ($12/month)
- vs Manual: 40+ hours/month ($500+)
- Savings: $488/month
- Quality: 99%+ accuracy

Time: 15-20 minutes

#### Documentation Generation

File: `examples/real-world/02-documentation-generation.rs`

What it demonstrates:

- Automated doc generation from code
- Multi-stage pipeline (analyze → write → check)
- Cost optimization
- Keeping docs in sync with code

Run:

    rustc examples/real-world/02-documentation-generation.rs -o /tmp/example && /tmp/example

Pipeline:

Phase 1 (Ollama - FREE):

- Parse source files
- Extract API endpoints, types
- Identify breaking changes
- Cost: $0.00, Time: 2min for 10k LOC

Phase 2 (Claude - $15/1M):

- Generate descriptions
- Create examples
- Document parameters
- Cost: $0.40/endpoint, Time: 30s

Phase 3 (GPT-4 - $10/1M):

- Verify accuracy vs code
- Check completeness
- Ensure clarity
- Cost: $0.15/doc, Time: 15s

Business impact:

- Docs in sync instantly (vs 2 week lag)
- Per-endpoint cost: $0.55
- Monthly cost: ~$11 (vs $1000+ manual)
- Savings: $989/month
- Quality: 99%+ accuracy

Time: 15-20 minutes

#### Issue Triage

File: `examples/real-world/03-issue-triage.rs`

What it demonstrates:

- Intelligent issue classification
- Two-stage escalation pipeline
- Cost optimization
- Consistent routing rules

Run:

    rustc examples/real-world/03-issue-triage.rs -o /tmp/example && /tmp/example

Two-stage pipeline:

Stage 1 (Ollama - FREE, 85% accuracy):

- Classify issue type (bug, feature, docs, support)
- Extract component, priority
- Route to team
- Cost: $0.00/issue, Time: 2s

Stage 2 (Claude - $15/1M, 15% of issues):

- Detailed analysis for unclear issues
- Extract root cause
- Create investigation
- Cost: $0.05/issue, Time: 10s

Business impact:

- Volume: 200 issues/month
- Stage 1: 170 issues × $0.00 = $0.00
- Stage 2: 30 issues × $0.08 = $2.40
- Manual triage: 20 hours × $50 = $1,000
- Savings: $997.60/month
- Speed: Seconds vs hours

Time: 15-20 minutes

## Learning Paths

### Path 1: Quick Overview (30 minutes)

1. Run `01-simple-agent` (agent basics)
2. Run `01-provider-selection` (LLM routing)
3. Run `01-error-handling` (error patterns)

Takeaway: Understand basic components

### Path 2: System Integration (90 minutes)

1. Run all Phase 1 examples (30 min)
2. Run `02-learning-profile` + `03-agent-selection` (20 min)
3. Run `02-budget-enforcement` + `03-cost-tracking` (20 min)
4. Run `02-task-assignment` + `02-learning-curves` (20 min)

Takeaway: Understand component interactions

### Path 3: Production Ready (2-3 hours)

1. Complete Path 2 (90 min)
2. Run Phase 5 real-world examples (45 min)
3. Study `docs/tutorials/` (30-45 min)

Takeaway: Ready to implement VAPORA in production

## Common Tasks

### I want to understand agent learning

Read: `docs/tutorials/04-learning-profiles.md`

Run examples (in order):

1. `02-learning-profile` - See expertise calculation
2. `03-agent-selection` - See scoring in action
3. `02-learning-curves` - See trends over time

Time: 30-40 minutes

### I want to understand cost control

Read: `docs/tutorials/05-budget-management.md`

Run examples (in order):

1. `01-provider-selection` - See provider pricing
2. `02-budget-enforcement` - See budget tiers
3. `03-cost-tracking` - See detailed reports

Time: 25-35 minutes

### I want to understand multi-agent workflows

Read: `docs/tutorials/06-swarm-coordination.md`

Run examples (in order):

1. `01-agent-registration` - See swarm setup
2. `02-task-assignment` - See task routing
3. `02-swarm-with-learning` - See full workflow

Time: 30-40 minutes

### I want to see business value

Run examples (real-world):

1. `01-code-review-workflow` - $488/month savings
2. `02-documentation-generation` - $989/month savings
3. `03-issue-triage` - $997/month savings

Takeaway: VAPORA saves $2,474/month for typical usage

Time: 40-50 minutes

## Running Examples with Parameters

Some examples support command-line arguments:

    # Budget enforcement with custom budget
    cargo run --example 02-budget-enforcement -p vapora-llm-router -- \
      --monthly-budget 50000 --verbose

    # Learning profile with custom sample size
    cargo run --example 02-learning-profile -p vapora-agents -- \
      --sample-size 100

Check example documentation for available options:

    # View example header
    head -20 crates/vapora-agents/examples/02-learning-profile.rs

## Troubleshooting

### "example not found"

Ensure you're running from workspace root:

    cd /path/to/vapora
    cargo run --example 01-simple-agent -p vapora-agents

### "Cannot find module"

Ensure workspace is synced:

    cargo update
    cargo build --examples --workspace

### Example fails at runtime

Check prerequisites:

Backend examples require:

    # Terminal 1: Start SurrealDB
    docker run -d -p 8000:8000 surrealdb/surrealdb:latest

    # Terminal 2: Start backend
    cd crates/vapora-backend && cargo run

    # Terminal 3: Run example
    cargo run --example 01-health-check -p vapora-backend

### Want verbose output

Set logging:

    RUST_LOG=debug cargo run --example 02-learning-profile -p vapora-agents

## Next Steps

After exploring examples:

1. Read tutorials: `docs/tutorials/README.md` - step-by-step guides
2. Study code snippets: `docs/examples/` - quick reference
3. Explore source: `crates/*/src/` - understand implementations
4. Run tests: `cargo test --workspace` - verify functionality
5. Build projects: Create your first VAPORA integration

## Quick Reference

### Build all examples

    cargo build --examples --workspace

### Run specific example

    cargo run --example <name> -p <crate>

### Clean build artifacts

    cargo clean
    cargo build --examples

### List examples in crate

    ls -la crates/<crate>/examples/

### View example documentation

    head -30 crates/<crate>/examples/<name>.rs

### Run with output

    cargo run --example <name> -- 2>&1 | tee output.log

## Resources

- Main docs: See `docs/` directory
- Tutorial path: `docs/tutorials/README.md`
- Code snippets: `docs/examples/`
- API documentation: `cargo doc --open`
- Project examples: `examples/` directory

Total examples: 23 Rust + 4 Marimo notebooks

Estimated learning time: 2-3 hours for complete understanding

Next: Start with Path 1 (Quick Overview) →