Write Milvus application-level Jupyter notebook examples using a Markdown-first workflow with jupyter-switch for format conversion.

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: 1. Write/Edit the .md file — AI works with clean Markdown 2. Convert to .ipynb — using jupyter switch for runnable notebook 3. Keep both files in sync — the .md is the source of truth for editing Format Convention In the .md file: Python code blocks ( ) 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 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 1. Create example.md with the content (see structure below) 2. Convert: uvx jupyter switch example.md 3. Both example.md and example.ipynb now exist Editing an Existing Notebook 1. If only .ipynb exists, convert first: uvx jupyter switch example.ipynb 2. Edit the .md file 3. 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. Step B — Ask the user which environment to use. Present a numbered list of choices. Include all detected environments: 1. System default — run jupyter execute as is, no kernel name 2. Each detected conda/mamba environment — show name and path 3. Each registered Jupyter kernel — show kernel name 4. Local venv (if .venv/ or venv/ found in working directory) — the Python inside that venv 5. 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: 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: 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: 3. Convert and run 1. Convert .md to .ipynb if needed 2. Install any missing dependencies in the target environment externally: <env python m pip install upgrade <packages 3. Run: jupyter execute kernel name=<name example.ipynb (omit kernel name if using system default) 4. 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: 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 .

jupyter-notebook-writing