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

# 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:

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:

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:

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:

marimo run 06-cost-analysis.py

Using Notebooks

Launch Marimo Server

# 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

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

Visualizations

# 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

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

agent_role = mo.ui.dropdown(
    ["developer", "reviewer", "architect"],
    value="developer"
)

Visualization

import plotly.graph_objects as go

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

Data Display

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"

pip install marimo
marimo --version

"Module not found: plotly"

pip install -r requirements.txt

"Port already in use"

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 →