# Weave Template (Claude)

A spec-driven FABRIC experiment template designed and autonomously managed by Claude Code.

## What It Does

The default experiment:

1. **Deploys** a single Ubuntu 22.04 VM on a randomly-selected FABRIC site
2. **Measures** CPU, memory, and network utilization for 60 seconds
3. **Collects** results as JSON to the local `data/` directory
4. **Analyzes** data and writes summary statistics
5. **Deletes** the slice automatically when finished

## Quick Start

1. Open **Artifacts** in the WebUI
2. Find "Weave Template (Claude)" and click **Run**
3. Optionally adjust the parameters:
   - **Slice Name** — name for the FABRIC slice (default: `claude-exp`)
   - **Duration** — measurement window in seconds (default: `60`)
   - **Data Dir** — local directory for results (default: `data`)
4. Watch progress in the Build Log
5. When complete, open `notebooks/results.ipynb` for graphs and analysis

## Tutorial

Open **`notebooks/tutorial.ipynb`** for a step-by-step guide that covers:

- Running the default experiment
- Using Claude to fill in the roadmap and spec documents
- Asking Claude to build a more complex 2-node network latency experiment
- Running and verifying the result

## File Structure

```
Weave_Template__Claude_/
├── weave.json              # Weave manifest: args, topology, metadata
├── weave.sh                # Orchestrator (deploy → measure → collect → analyze → delete)
├── experiment.py           # Python lifecycle: start/stop/collect/analyze
├── slice.json              # Slice topology for backend submission
├── tools/
│   └── setup-node.sh       # VM boot script: installs sysstat, jq
├── notebooks/
│   ├── tutorial.ipynb      # Step-by-step tutorial with Claude workflow examples
│   ├── progress.ipynb      # Live status and experiment setup description
│   └── results.ipynb       # Full report: motivation, methodology, graphs, conclusion
├── docs/
│   ├── spec-template.md    # Experiment specification (filled in for default experiment)
│   ├── roadmap-template.md # Implementation roadmap (filled in for default experiment)
│   └── testing-template.md # Testing procedures (filled in for default experiment)
├── data/                   # Experiment results (created at runtime)
│   ├── vmstat.json         # CPU data (1-second intervals)
│   ├── memory.json         # Memory data (1-second intervals)
│   ├── network.json        # Network throughput data (1-second intervals)
│   ├── metadata.json       # Run metadata (site, times, config)
│   └── summary.json        # Aggregated statistics
└── README.md               # This file
```

## Customizing the Template

The default experiment is intentionally simple. To build more complex experiments,
ask Claude in the AI chat. For example:

> "Design a 2-node network latency and throughput experiment using iperf3 and ping over L2Bridge"

Claude will update the spec, roadmap, topology, and experiment code for you.
See the tutorial notebook for a full walkthrough.

### What You Can Customize

- **More nodes:** Add entries to the topology in `weave.json` and `slice.json`
- **Networks:** Add L2Bridge, FABNetv4, L2STS, or other network types
- **Special hardware:** Add GPU, FPGA, or SmartNIC components
- **Custom metrics:** Extend `experiment.py` with your measurement logic
- **Parameter sweeps:** Vary experiment parameters across multiple runs

## Slice Lifecycle

```
Backend:  load weave → create draft → submit → wait for StableOK → run boot config
                                                                        ↓
weave.sh: experiment.py start → [connect to slice, install tools, measure]
              ↓
          experiment.py collect → [download data from VM]
              ↓
          experiment.py analyze → [parse data, write summary]
              ↓
          experiment.py stop → [delete slice]
```

## Documentation Workflow

This template includes three documentation templates that Claude fills in
during the design process:

1. **Spec** (`docs/spec-template.md`) — What you're measuring and why
2. **Roadmap** (`docs/roadmap-template.md`) — Phased implementation plan with checkpoints
3. **Testing** (`docs/testing-template.md`) — Validation procedures from smoke test to full run
