fiftyone-create-notebook

What this skill does

# Create FiftyOne Notebooks

## Contents
- [Key Directives](#key-directives)
- [Complete Workflow](#complete-workflow)
- [Notebook Structure Reference](#notebook-structure-reference)
- [Common Use Cases](#common-use-cases)
- [Troubleshooting](#troubleshooting)
- [Best Practices](#best-practices)
- [Resources](#resources)

## Key Directives

**ALWAYS follow these rules:**

### 1. Determine notebook type first

Classify the user's request before anything else:

| User Request Pattern | Type | Template |
|---|---|---|
| "getting started", "beginner", "intro", "first notebook" | Getting Started | [GETTING-STARTED-TEMPLATES.md](GETTING-STARTED-TEMPLATES.md) |
| "tutorial", "how to use X", "deep dive", "demonstrate X" | Tutorial | [TUTORIAL-TEMPLATES.md](TUTORIAL-TEMPLATES.md) |
| "recipe", "quick", "snippet", "how do I X" | Recipe | [RECIPE-TEMPLATES.md](RECIPE-TEMPLATES.md) |
| "full pipeline", "end to end", "ML pipeline", "complete workflow" | Full Pipeline | [GETTING-STARTED-TEMPLATES.md](GETTING-STARTED-TEMPLATES.md) with all stages |

If ambiguous, ask the user.

### 2. Create the notebook file before adding cells

Use the Write tool to create a valid empty `.ipynb` file first:

```json
{
  "nbformat": 4,
  "nbformat_minor": 2,
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python",
      "version": "3.10.0"
    }
  },
  "cells": []
}
```

Then use `NotebookEdit` with `edit_mode: "insert"` to add cells.

### 3. Follow FiftyOne code conventions

All generated code must use standard FiftyOne import aliases:

```python
import fiftyone as fo
import fiftyone.zoo as foz
import fiftyone.brain as fob
import fiftyone.types as fot
from fiftyone import ViewField as F
```

See the "Code Pattern Sources" table below for full conventions.

### 4. Build notebooks cell-by-cell

Use `NotebookEdit` with `edit_mode: "insert"` for every cell. Build top-to-bottom using `cell_id` chaining: insert the first cell without `cell_id` (inserts at beginning), then read the notebook to get its `cell_id`, and insert each subsequent cell with `cell_id` set to the previous cell's ID. This ensures correct ordering.

**Critical:** Without `cell_id`, every insert goes to the **beginning** of the notebook, resulting in reversed cell order.

**Never** write the entire `.ipynb` JSON at once. Incremental cell insertion allows verification and correction.

### 5. Always include App visualization

Every notebook must include at least one cell with:

```python
session = fo.launch_app(dataset)
```

FiftyOne's core value is visual exploration. Notebooks without App visualization miss the point.

### 6. Use zoo datasets when user has no data

For getting-started and tutorial notebooks, default to `foz.load_zoo_dataset()` so users can run the notebook without bringing their own data. For recipes and custom pipelines, support both zoo and user data.

### 7. Precede every code cell with a markdown cell

Never place two code cells in a row without a markdown cell in between. The markdown cell explains **what** the code does and **why**. This is critical for tutorials and getting-started guides. Recipes are exempt — consecutive code cells are permitted for brevity (imports + load data, core solution + verify).

### 8. Present outline before generating

Before creating any cells, draft a notebook outline showing:
- Section headings
- Cell types (markdown/code)
- Brief description of each cell

Get user approval before generating.

### 9. Fetch current API documentation

When generating code, fetch `https://docs.voxel51.com/llms.txt` for the latest FiftyOne API patterns. This ensures generated code uses current APIs and avoids deprecated patterns.

### 10. Verify after generation

After all cells are inserted, read the notebook back with the Read tool to verify:
- Cells are in correct order
- Markdown/code alternation is maintained
- Import aliases are correct
- Narrative flow is logical

## Complete Workflow

### Phase 1: Requirements

Gather information before designing the notebook:

1. **Classify notebook type** — Use the decision matrix from Directive 1. Ask the user if ambiguous.
2. **Determine domain and task** — Ask or infer what ML task the notebook covers. Common domains include:
   - Object Detection
   - Image Classification
   - Instance/Semantic Segmentation
   - Embeddings & Similarity
   - Data Curation (duplicates, outliers, annotation mistakes)
   - Video analysis, 3D point clouds, or any other FiftyOne-supported workflow
3. **Determine data source:**
   - **Zoo dataset** (recommended for tutorials): `foz.load_zoo_dataset("coco-2017", ...)`
   - **User's local data**: `fo.Dataset.from_dir(...)`
   - **Hugging Face Hub**: `foz.load_zoo_dataset("https://huggingface.co/datasets/...", ...)`
   - **Quickstart**: `foz.load_zoo_dataset("quickstart")`
4. **Determine pipeline stages:**

| Stage | Description | Always Include? |
|---|---|---|
| Data Loading | Load/create dataset | Yes |
| Exploration | App, stats, filtering | Yes |
| Brain Methods | Embeddings, uniqueness, duplicates | If relevant |
| Inference | Model predictions | If relevant |
| Evaluation | Metrics, TP/FP/FN analysis | If predictions + ground truth |
| Export | Save to format | Optional |

5. **Confirm with user** — Present a summary:
   - Notebook type: [Getting Started / Tutorial / Recipe / Full Pipeline]
   - Domain: [Detection / Classification / ...]
   - Data source: [Zoo dataset name / User path / HF URL]
   - Pipeline stages: [Load, Explore, Infer, Evaluate, Export]
   - Estimated cells: [N]

### Phase 2: Design

1. **Read the appropriate template doc** as a structural guide (adapt to the user's domain — do not copy specific datasets, models, or field names from the examples):
   - [GETTING-STARTED-TEMPLATES.md](GETTING-STARTED-TEMPLATES.md) for getting-started and full pipeline
   - [TUTORIAL-TEMPLATES.md](TUTORIAL-TEMPLATES.md) for tutorials
   - [RECIPE-TEMPLATES.md](RECIPE-TEMPLATES.md) for recipes
2. **Fetch API documentation** — Fetch `https://docs.voxel51.com/llms.txt` using the WebFetch tool for current FiftyOne API patterns. This is the authoritative source for SDK usage.
3. **Draft notebook outline** — Create a numbered list of cells with cell number, type (markdown/code), and content summary:
```
0. [markdown] Title + description
1. [markdown] What You Will Learn
2. [code] pip install
3. [markdown] ## Setup
4. [code] Imports
5. [markdown] ## Load Dataset
6. [code] Load from zoo + print dataset info
...
```
4. **Present outline for approval** — Show the outline to the user. Wait for approval before generating.

### Phase 3: Generation

1. **Create empty notebook file:**
```python
# Use Write tool
Write(
    file_path="/path/to/notebook.ipynb",
    content='{"nbformat": 4, "nbformat_minor": 2, "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, "language_info": {"name": "python", "version": "3.10.0"}}, "cells": []}'
)
```
Ask the user for the notebook file path, or suggest a default based on the title.

2. **Add cells with NotebookEdit using `cell_id` chaining:**

Insert the first cell without `cell_id` (goes to beginning), then read the notebook to get the assigned `cell_id`. Each subsequent cell uses `cell_id` of the previous cell:
```
# First cell — no cell_id, inserts at beginning
NotebookEdit(
    notebook_path="/path/to/notebook.ipynb",
    new_source="# Title\n\nDescription paragraph.",
    cell_type="markdown",
    edit_mode="insert"
)

# Read notebook to get the first cell's ID (e.g., "cell-0")
Read(file_path="/path/to/notebook.ipynb")

# Second cell — chain after cell-0
NotebookEdit(
    notebook_path="/path/to/notebook.ipynb",
    cell_id="cell-0",
    new_source="!pip install -q fiftyone",
    cell_type="code",
    edit_mode="insert"
)

# Third cell — chain after cell-1
NotebookEdit(
    notebook_path="/path/to/notebook.ipynb",