Skill: Jupyter Notebook Writing

Write Milvus application-level Jupyter notebook examples as a DevRel workflow. Uses a Markdown-first approach — AI edits .md files, then converts to .ipynb via jupyter-switch.

Prerequisites: Python >= 3.10, uv (uvx command available)

When to Use

The user wants to create or edit a Jupyter notebook example, typically demonstrating Milvus usage in an application context (RAG, semantic search, hybrid search, etc.).

Core Workflow: Markdown-First Editing

Jupyter .ipynb files contain complex JSON with metadata, outputs, and execution counts — painful for AI to edit directly. Instead:

• **Write/Edit the .md file** — AI works with clean Markdown

• **Convert to .ipynb** — using jupyter-switch for runnable notebook

• Keep both files in sync — the .md is the source of truth for editing

Format Convention

In the .md file:

• Python code blocks (python ... ) become code cells in the notebook

• Everything else becomes markdown cells

• Cell outputs are not preserved in .md (they get generated when running the notebook)

Conversion Commands

# Markdown -> Jupyter Notebook

uvx jupyter-switch example.md

# produces example.ipynb

# Jupyter Notebook -> Markdown

uvx jupyter-switch example.ipynb

# produces example.md

• The original input file is never modified or deleted

• If the output file already exists, a .bak backup is created automatically

Step-by-Step

Creating a New Notebook

• Create example.md with the content (see structure below)

• Convert: uvx jupyter-switch example.md

• Both example.md and example.ipynb now exist

Editing an Existing Notebook

• If only .ipynb exists, convert first: uvx jupyter-switch example.ipynb

• Edit the .md file

• Convert back: uvx jupyter-switch example.md

Testing / Running

#### 1. Resolve the Jupyter execution environment

Before running any notebook, you must determine which Python environment to use. The system default jupyter execute may not have the required packages installed.

Step A — Detect available environments.

# Discover conda/mamba environments

conda env list 2>/dev/null || mamba env list 2>/dev/null

# Discover registered Jupyter kernels

jupyter kernelspec list 2>/dev/null

# Check system default Python

which python3 2>/dev/null && python3 --version 2>/dev/null

# Check for local virtual environment in the working directory

ls -d .venv/ venv/ 2>/dev/null

# Check if a uv-managed project (pyproject.toml + .venv)

test -f pyproject.toml && test -d .venv && echo "uv/pip project venv detected"

Step B — Ask the user which environment to use. Present a numbered list of choices. Include all detected environments:

• System default — run jupyter execute as-is, no --kernel_name

• Each detected conda/mamba environment — show name and path

• Each registered Jupyter kernel — show kernel name

• Local venv (if .venv/ or venv/ found in working directory) — the Python inside that venv

• Custom — let the user type a Python path or environment name

Note on uv projects: If the working directory has pyproject.toml + .venv/ (a uv-managed project), the local venv option covers this case. The user can also run uv run jupyter execute example.ipynb directly if jupyter is a project dependency.

Example prompt:

Which Python environment should I use to run this notebook?

1. System default (jupyter execute as-is)

2. conda: myenv (/path/to/envs/myenv)

3. Jupyter kernel: some-kernel

4. Local venv (.venv/)

5. Custom — enter a path or environment name

Step C — Apply the chosen environment:

Scenario

Action

Already a registered Jupyter kernel

Use jupyter execute --kernel_name=<name>

Conda env not yet registered as kernel

Register first: <env-python> -m ipykernel install --user --name <name> --display-name "<label>", then use --kernel_name=<name>

Custom Python path

Same as above — register as kernel first, then use --kernel_name

#### 2. Prepare the notebook for execution

Before running, comment out "setup-only" cells in the .md file — cells that are meant for first-time users but should not run in an automated test environment. Specifically:

• **pip install cells** — dependencies should already be installed in the chosen Jupyter environment. If any packages are missing or need upgrading, install them externally in the target environment (with --upgrade), not inside the notebook.

• API key / credential placeholder cells — e.g. os.environ["OPENAI_API_KEY"] = "sk-***********". Instead, set environment variables externally before running (export in shell, or inject via code before jupyter execute).

• Mock / demo-only cells — any cells that exist purely for illustration and would fail or interfere in a real run.

To comment out a cell, wrap its content in a block comment so the cell still executes (producing empty output) but does nothing:

# # pip install --upgrade langchain pymilvus

# import os

# os.environ["OPENAI_API_KEY"] = "sk-***********"

This keeps the notebook structure intact (cell count, ordering) while preventing conflicts with the external Jupyter environment.

For environment variables: either export them in the shell before running jupyter execute, or prepend them to the command:

OPENAI_API_KEY="sk-real-key" jupyter execute --kernel_name=<name> example.ipynb

#### 3. Convert and run

• Convert .md to .ipynb if needed

• Install any missing dependencies in the target environment externally: <env-python> -m pip install --upgrade <packages>

• Run: jupyter execute --kernel_name=<name> example.ipynb (omit --kernel_name if using system default)

• If errors found, fix in the .md file, uncomment setup cells if needed for debugging, and re-convert

Notebook Structure Template

A typical Milvus example notebook follows this structure:

# Title

Brief description of what this notebook demonstrates.

## Prerequisites

Install dependencies:

` ``python

!pip install pymilvus some-other-package

` ``

## Setup

Import and configuration:

` ``python

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

` ``

## Prepare Data

Load or generate example data:

` ``python

# data preparation code

` ``

## Create Collection & Insert Data

` ``python

# collection creation and data insertion

` ``

## Query / Search

` ``python

# search or query examples

` ``

## Cleanup

` ``python

client.drop_collection("example_collection")

` ``

Reference Documents

This skill includes two reference documents under references/. Read them when the task involves their topics.

Reference

When to Read

File

Bootcamp Format

Writing a Milvus integration tutorial (badges, document structure, section format, example layout)

references/bootcamp-format.md

Milvus Code Style

Writing pymilvus code (collection creation, MilvusClient connection args, schema patterns, best practices)

references/milvus-code-style.md

Bootcamp Format ( references/bootcamp-format.md )

Read this when the user is writing a Milvus integration tutorial for the bootcamp repository. It covers:

• Badge format (Colab + GitHub badges at the top)

• Document structure: Header -> Prerequisites -> Main Content -> Conclusion

• Dependency install format with Google Colab restart note

• API key placeholder conventions ("sk-***********")

• Each code block should have a short text introduction before it

Milvus Code Style ( references/milvus-code-style.md )

Read this when the notebook involves pymilvus code. Key rules:

• **Always use MilvusClient API** — never use the legacy ORM layer (connections.connect(), Collection(), FieldSchema(), etc.)

• Always define schema explicitly (create_schema + add_field) — do not use the shortcut create_collection(dimension=...) without schema

• Include has_collection check before creating collections

• Add commented consistency_level="Strong" line in create_collection()

• No need to call load_collection() — collections auto-load on creation

• First MilvusClient connection must include the blockquote explaining uri options (Milvus Lite / Docker / Zilliz Cloud)

Important Notes

• **Always edit the .md file**, not the .ipynb directly. The .md is easier for AI to read and write.

• Keep both files — .md for editing, .ipynb for running/sharing.

• After editing .md, always re-run uvx jupyter-switch example.md to sync the .ipynb.