Vapora/examples/README.md

VAPORA Examples

Comprehensive examples demonstrating VAPORA's capabilities across all complexity levels.

Quick Navigation

Basic Examples (Hello World)

Start here to understand individual components.

• Agent Registry - Register and manage agents
• LLM Provider Selection - Route requests to optimal providers
• Swarm Registration - Set up swarm coordination
• KG Execution Tracking - Record and query execution history
• Backend Health Check - Verify backend health
• Error Handling - Proper error patterns

Intermediate Examples (System Integration)

Combine multiple systems to solve realistic problems.

• Learning Profiles - Build agent expertise from history
• Agent Selection - Score and rank agents
• Budget Enforcement - Control LLM spending
• Cost Tracking - Generate cost reports
• Task Assignment - Assign tasks with load balancing
• Learning Curves - Visualize agent improvement
• Similarity Search - Find similar past tasks

Full-Stack Examples

End-to-end workflows integrating all systems.

• Agent + Routing - Execute with provider selection
• Swarm + Learning - Coordinate multi-agent learning

How to Run Examples

Basic Example

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

All Examples in a Crate

cargo build --examples -p vapora-agents

All Examples (Workspace)

cargo build --examples --workspace

Learning Path

New to VAPORA? Follow this order:

1. Run the 6 basic examples to understand components
2. Review tutorials in docs/tutorials/ for step-by-step guidance
3. Run intermediate examples to see integration
4. Study full-stack examples for complex workflows
5. Explore codebase for production implementations

Example Organization

examples/
├── full-stack/              # Cross-system examples (3 files)
├── real-world/              # Production scenarios (4 files) [WIP]
└── notebooks/               # Interactive Marimo notebooks [WIP]

crates/*/examples/           # Component-specific examples (6 crates × 2-3 examples)
├── vapora-agents/           # Agent orchestration examples
├── vapora-llm-router/       # LLM routing examples
├── vapora-swarm/            # Swarm coordination examples
├── vapora-knowledge-graph/  # Knowledge graph examples
├── vapora-backend/          # Backend integration examples
└── vapora-shared/           # Error handling & patterns

Building Blocks

Key Concepts Demonstrated

Agent Orchestration

• Registering agents with capabilities
• Building learning profiles from history
• Scoring agents for task assignment
• Handling multiple roles and specializations

LLM Routing

• Multi-provider selection (Claude, OpenAI, Gemini, Ollama)
• Budget enforcement per role
• Cost tracking and reporting
• Automatic fallback on budget limits

Swarm Coordination

• Distributed task assignment
• Load balancing algorithms
• Agent capability filtering
• Coalition formation

Knowledge Graph

• Temporal execution history
• Semantic similarity search
• Learning curve computation
• Recommendation generation

Full-Stack Integration

• REST API usage for project management
• WebSocket real-time updates
• Multi-system workflows
• Cost-aware agent orchestration

Tutorial Documentation

See docs/tutorials/ for step-by-step guides:

• 01-getting-started.md - Build and run VAPORA
• 02-basic-agents.md - Agent registration and execution
• 03-llm-routing.md - Multi-provider LLM usage
• 04-learning-profiles.md - Build agent expertise
• 05-budget-management.md - Enforce cost limits
• 06-swarm-coordination.md - Multi-agent workflows
• 07-knowledge-graph.md - Track execution history
• 08-rest-api.md - Backend API usage
• 09-frontend-integration.md - Web UI integration

Code Snippets

For quick reference snippets organized by topic, see docs/examples/:

• agents.md - Agent API patterns
• routing.md - LLM routing recipes
• budgets.md - Budget configuration
• swarm.md - Swarm coordination patterns
• knowledge-graph.md - KG queries
• api.md - REST API examples

Running Tests

All examples compile and can be validated:

# Check all examples compile
cargo check --examples

# Build and run with output
cargo run --example 02-learning-profile -p vapora-agents -- --verbose

# Run CI tests
cargo test --examples --workspace

Troubleshooting

"example not found"

# List available examples in a crate
cargo run --example help -p vapora-agents

Compilation errors

• Ensure you're running from the workspace root
• Check Rust version: rustc --version (1.75+)
• Run cargo update to sync dependencies

Runtime errors

• Backend requires SurrealDB: docker run -d surrealdb/surrealdb:latest
• Optional NATS for async: docker run -d nats:latest

Contributing Examples

To add new examples:

1. Create crates/*/examples/NN-name.rs following existing patterns
2. Add documentation header explaining what's demonstrated
3. Ensure standalone (minimal external dependencies)
4. Run cargo build --examples to verify compilation
5. Update README.md with link to new example

---

Total Examples: 24+ across all complexity levels

Start with basic examples → follow tutorials → explore intermediate/full-stack → examine production code in crates/