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](crates/vapora-agents/examples/01-simple-agent.rs)** - Register and manage agents
- **[LLM Provider Selection](crates/vapora-llm-router/examples/01-provider-selection.rs)** - Route requests to optimal providers
- **[Swarm Registration](crates/vapora-swarm/examples/01-agent-registration.rs)** - Set up swarm coordination
- **[KG Execution Tracking](crates/vapora-knowledge-graph/examples/01-execution-tracking.rs)** - Record and query execution history
- **[Backend Health Check](crates/vapora-backend/examples/01-health-check.rs)** - Verify backend health
- **[Error Handling](crates/vapora-shared/examples/01-error-handling.rs)** - Proper error patterns

### Intermediate Examples (System Integration)
Combine multiple systems to solve realistic problems.

- **[Learning Profiles](crates/vapora-agents/examples/02-learning-profile.rs)** - Build agent expertise from history
- **[Agent Selection](crates/vapora-agents/examples/03-agent-selection.rs)** - Score and rank agents
- **[Budget Enforcement](crates/vapora-llm-router/examples/02-budget-enforcement.rs)** - Control LLM spending
- **[Cost Tracking](crates/vapora-llm-router/examples/03-cost-tracking.rs)** - Generate cost reports
- **[Task Assignment](crates/vapora-swarm/examples/02-task-assignment.rs)** - Assign tasks with load balancing
- **[Learning Curves](crates/vapora-knowledge-graph/examples/02-learning-curves.rs)** - Visualize agent improvement
- **[Similarity Search](crates/vapora-knowledge-graph/examples/03-similarity-search.rs)** - Find similar past tasks

### Full-Stack Examples
End-to-end workflows integrating all systems.

- **[Agent + Routing](examples/full-stack/01-agent-with-routing.rs)** - Execute with provider selection
- **[Swarm + Learning](examples/full-stack/02-swarm-with-learning.rs)** - Coordinate multi-agent learning

## How to Run Examples

### Basic Example
```bash
cargo run --example 01-simple-agent -p vapora-agents
```

### All Examples in a Crate
```bash
cargo build --examples -p vapora-agents
```

### All Examples (Workspace)
```bash
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:

```bash
# 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"**
```bash
# 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/