Vapora/docs/examples-guide.md

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) →