# Hello FABRIC

A beginner-friendly weave that creates a single Ubuntu VM on the
[FABRIC testbed](https://fabric-testbed.net). Use it to learn how weaves,
slices, and LoomAI work together.

## What It Does

1. Provisions a small Ubuntu 22.04 VM (2 cores, 8 GB RAM, 10 GB disk) on a
   FABRIC site chosen automatically.
2. Waits for the VM to become reachable via SSH.
3. Monitors the VM's health every 30 seconds until you click **Stop**.
4. On Stop, deletes the slice and releases all resources.

## What Is a Weave?

A **weave** is a reusable slice topology template in LoomAI. It packages
everything needed to create and manage a FABRIC experiment:

- **`weave.json`** — Declares the topology (nodes, networks, components),
  metadata, and any user-configurable arguments.
- **`weave.sh`** — The orchestrator script that runs when you click **Run**.
  It handles the full lifecycle: start, monitor, and stop.
- **Supporting scripts** — Python or shell scripts that `weave.sh` calls
  (in this weave, `hello_fabric.py`).

When you click **Run** in the LoomAI WebUI, the backend executes `weave.sh`
with the arguments you provide. Lines starting with `### PROGRESS:` are
displayed as real-time status updates in the UI.

## File Structure

```
Hello_FABRIC/
  weave.json          Topology + metadata (the marker file that makes this a weave)
  weave.sh            Orchestrator script (Run/Stop entry point)
  hello_fabric.py     Python script for slice lifecycle (start/monitor/stop)
  hello_fabric.ipynb  Jupyter notebook — interactive tutorial
  README.md           This file
```

## How to Use

### Run the Weave (WebUI)

1. Open the **Artifacts** panel in LoomAI.
2. Find **Hello FABRIC** and click **Run**.
3. Optionally change the **Slice Name** (default: `hello-fabric`).
4. Watch the progress messages as the slice is created.
5. When you see "Monitoring (click Stop to tear down)...", your VM is ready.
6. Click **Stop** to delete the slice when you're done.

### Use the Jupyter Notebook

The included `hello_fabric.ipynb` notebook walks you through interacting with
your running slice using FABlib — FABRIC's Python library. It assumes the
slice is already running (deployed via the Run button above).

1. Deploy the weave first (click Run and wait for it to be ready).
2. Start JupyterLab from the LoomAI menu.
3. Open `my_artifacts/Hello_FABRIC/hello_fabric.ipynb`.
4. Step through each cell to explore your slice interactively.

## Key Concepts

| Concept | Description |
|---------|-------------|
| **Slice** | A collection of reserved FABRIC resources (VMs, networks, storage). Has a lifecycle: Draft → Configuring → StableOK → Deleted. |
| **Node** | A virtual machine within a slice. Each node runs on a physical host at a FABRIC site. |
| **Site** | A FABRIC data center (e.g., TACC, STAR, MAX). Setting `"site": "auto"` lets FABRIC pick one with available capacity. |
| **FABlib** | The Python library (`fabrictestbed_extensions`) for creating and managing slices programmatically. |
| **Weave** | A LoomAI artifact that packages a reusable slice topology with orchestration scripts. |

## Slice Lifecycle

```
weave.json ──Run──> weave.sh start ──> Configuring ──> StableOK
                                                          │
                                          monitor loop (30s) ◄──┘
                                                          │
                                    Stop button ──> weave.sh stop ──> Deleted
```

## Next Steps

- Modify `weave.json` to add more nodes or change the VM size.
- Add a network to connect multiple nodes (see `networks` in `weave.json`).
- Add components like GPUs or SmartNICs to your nodes.
- Explore other weaves in the LoomAI Artifacts marketplace for more complex
  topologies.
