Vapora/examples/notebooks/README.md

# VAPORA Interactive Notebooks

Interactive Marimo notebooks for exploring VAPORA capabilities.

## What are Marimo Notebooks?

Marimo is a modern Python notebook framework that's:
- **Reactive**: Automatically updates when inputs change
- **Git-friendly**: Pure Python files (not JSON)
- **Interactive**: Widgets and dynamic visualizations
- **Perfect for**: Learning, experimentation, demos

## Installation

### Prerequisites
- Python 3.9+
- VAPORA examples working

### Setup

```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

## Available Notebooks

### 1. Agent Basics
**File**: `01-agent-basics.py`

Interactive exploration of agent registration and selection.

**Features**:
- Agent role selector (dropdown)
- Load slider (0-100%)
- Capability matrix visualization
- Scoring formula calculator

**Run**:
```bash
marimo run 01-agent-basics.py
```

### 2. Budget Playground
**File**: `03-budget-playground.py`

Experiment with budget limits and cost optimization.

**Features**:
- Monthly budget slider ($0-$1000)
- Task complexity selector
- Provider cost comparison chart
- Budget timeline visualization

**Run**:
```bash
marimo run 03-budget-playground.py
```

### 3. Learning Curves
**File**: `04-learning-curves.py`

Visualize agent learning over time.

**Features**:
- Agent selector dropdown
- Time window (7/14/30 days)
- Learning curve plot (Plotly)
- Success rate trend
- Confidence intervals

**Run**:
```bash
marimo run 04-learning-curves.py
```

### 4. Cost Analysis
**File**: `06-cost-analysis.py`

Analyze cost optimization strategies.

**Features**:
- Workload profile selector
- Provider comparison chart
- Cost efficiency analysis
- ROI calculator

**Run**:
```bash
marimo run 06-cost-analysis.py
```

## Using Notebooks

### Launch Marimo Server

```bash
# Auto-open in browser
marimo run 01-agent-basics.py

# Manual: Open http://localhost:3000
marimo server --port 3000
```

### Notebook Features

**Reactive Updates**
- Change a slider → instantly recalculate
- Select dropdown → automatically visualize
- All dependent cells update automatically

**Widgets**
```python
# Create interactive input
budget = mo.ui.slider(min=0, max=1000, value=500)
mo.md(f"Budget: ${budget.value}")
```

**Visualizations**
```python
# Use Plotly for interactive charts
import plotly.express as px
fig = px.line(data, x='date', y='success_rate')
mo.plot(fig)
```

**Running Shell Commands**
```python
import subprocess

# Call Rust examples
result = subprocess.run(
    ["cargo", "run", "--example", "01-simple-agent"],
    capture_output=True,
    text=True
)
print(result.stdout)
```

## Common Patterns

### Parameter Input
```python
agent_role = mo.ui.dropdown(
    ["developer", "reviewer", "architect"],
    value="developer"
)
```

### Visualization
```python
import plotly.graph_objects as go

fig = go.Figure()
fig.add_trace(go.Scatter(x=dates, y=values))
mo.plot(fig)
```

### Data Display
```python
import pandas as pd

df = pd.DataFrame({
    "Agent": ["alice", "bob"],
    "Expertise": [0.92, 0.78],
})
mo.ui.dataframe(df)
```

## Learning Workflow

**Beginner**:
1. Run 01-agent-basics.py
2. Experiment with agent selection
3. Understand scoring formula

**Intermediate**:
1. Run 03-budget-playground.py
2. Test different budgets
3. Observe cost implications

**Advanced**:
1. Run 04-learning-curves.py
2. Analyze trends
3. Predict future performance

## Troubleshooting

**"marimo command not found"**
```bash
pip install marimo
marimo --version
```

**"Module not found: plotly"**
```bash
pip install -r requirements.txt
```

**"Port already in use"**
```bash
marimo server --port 3001  # Use different port
```

## Contributing Notebooks

To create new notebook:

1. Create `NN-description.py` in this directory
2. Use provided template structure
3. Add to `README.md`
4. Test: `marimo run NN-description.py`

## Resources

- Marimo docs: https://marimo.io
- Plotly docs: https://plotly.com/python
- Interactive examples: https://marimo.io/examples

---

**Total notebooks**: 4

Start with `01-agent-basics.py` →