jupyter-notebook-writing

スキル：Jupyter ノートブックの作成

DevRel ワークフローとして、Milvus のアプリケーションレベルの Jupyter ノートブック例を作成します。Markdown を優先するアプローチを採用し、AI が .md ファイルを編集した後、jupyter-switch で .ipynb に変換します。

前提条件：Python >= 3.10、uv（uvx コマンドが利用可能）

---

使用する場面

ユーザーが Jupyter ノートブックの例を作成または編集したい場合に使用します。通常は、アプリケーションの文脈で Milvus の利用方法（RAG、セマンティック検索、ハイブリッド検索など）を説明します。

---

基本的なワークフロー：Markdown を優先した編集

Jupyter の .ipynb ファイルには、メタデータ、出力、実行回数を含む複雑な JSON が格納されており、AI が直接編集するのは困難です。そのため、代わりに次の手順を使用します。

1. .md ファイルを作成／編集する — AI はシンプルな Markdown を使用します
2. .ipynb に変換する — 実行可能なノートブックにするため、jupyter-switch を使用します
3. 両方のファイルの内容を同期する — 編集時の信頼できるソースは .md です

形式の規則

.md ファイルでは：

• Python コードブロック（```python ... ```）はノートブック内のコードセルになります
• それ以外のすべてはMarkdown セルになります
• セルの出力は .md には保持されません（ノートブックの実行時に生成されます）

変換コマンド

# Markdown -> Jupyter Notebook
uvx jupyter-switch example.md
# produces example.ipynb

# Jupyter Notebook -> Markdown
uvx jupyter-switch example.ipynb
# produces example.md

• 元の入力ファイルが変更または削除されることはありません
• 出力ファイルがすでに存在する場合は、.bak バックアップが自動的に作成されます

---

手順

新しいノートブックの作成

1. 内容を記述した example.md を作成します（以下の構成を参照）
2. 変換します：uvx jupyter-switch example.md
3. example.md と example.ipynb の両方が作成されます

既存のノートブックの編集

1. .ipynb しか存在しない場合は、先に変換します：uvx jupyter-switch example.ipynb
2. .md ファイルを編集します
3. 変換して戻します：uvx jupyter-switch example.md

テスト／実行

1. Jupyter の実行環境を選択する

ノートブックを実行する前に、使用する Python 環境を特定する必要があります。システムのデフォルトの jupyter execute には、必要なパッケージがインストールされていない場合があります。

ステップ A — 利用可能な環境を検出します。

# 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"

ステップ B — 使用する環境をユーザーに確認します。 番号付きの選択肢を提示し、検出された環境をすべて含めます。

1. システムのデフォルト — --kernel_name を指定せず、そのまま jupyter execute を実行します
2. 検出された各 conda/mamba 環境 — 名前とパスを表示します
3. 登録済みの各 Jupyter カーネル — カーネル名を表示します
4. ローカル venv（作業ディレクトリに .venv/ または venv/ が見つかった場合）— その venv 内の Python を使用します
5. カスタム — Python のパスまたは環境名をユーザーに入力してもらいます

uv プロジェクトに関する注意： 作業ディレクトリに pyproject.toml と .venv/ がある場合（uv で管理されたプロジェクト）、ローカル venv の選択肢が該当します。jupyter がプロジェクトの依存関係に含まれている場合は、ユーザーが uv run jupyter execute example.ipynb を直接実行することもできます。

プロンプトの例：

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

ステップ C — 選択した環境を適用します。

シナリオ	対応
すでに Jupyter カーネルとして登録済み	jupyter execute --kernel_name=<name> を使用します
Conda 環境がまだカーネルとして登録されていない	先に登録します：<env-python> -m ipykernel install --user --name <name> --display-name "<label>"。その後、--kernel_name=<name> を使用します
カスタム Python パス	上記と同様に、先にカーネルとして登録してから --kernel_name を使用します

2. ノートブックを実行用に準備する

実行前に、.md ファイル内の「セットアップ専用」セルをコメントアウトしてください。これらは初回ユーザー向けであり、自動テスト環境では実行しないセルです。具体的には、次のとおりです。

• pip install セル — 選択した Jupyter 環境には、依存関係がすでにインストールされている必要があります。不足しているパッケージやアップグレードが必要なパッケージがある場合は、ノートブック内ではなく、対象環境で外部からインストールしてください（--upgrade を使用）。
• API キー／認証情報のプレースホルダーセル — 例：os.environ["OPENAI_API_KEY"] = "sk-***********"。代わりに、実行前に環境変数を外部から設定してください（シェルでエクスポートするか、jupyter execute の前にコードで設定します）。
• モック／デモ専用セル — 説明のみを目的としており、実際の実行で失敗したり、実行に支障をきたしたりするセル。

セルをコメントアウトするには、セルの内容をブロックコメントで囲みます。こうするとセルは実行されますが（空の出力が生成されます）、何も処理しません。

# # pip install --upgrade langchain pymilvus
# import os
# os.environ["OPENAI_API_KEY"] = "sk-***********"

これにより、外部の Jupyter 環境との競合を防ぎながら、ノートブックの構造（セル数と順序）を維持できます。

環境変数について： jupyter execute の実行前にシェルでエクスポートするか、コマンドの先頭に追加してください。

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

3. 変換して実行する

1. 必要に応じて .md を .ipynb に変換します
2. 不足している依存関係があれば、対象環境に外部からインストールします：<env-python> -m pip install --upgrade <packages>
3. 実行します：jupyter execute --kernel_name=<name> example.ipynb（システムのデフォルトを使用する場合は --kernel_name を省略します）
4. エラーが見つかった場合は、.md ファイルを修正し、必要に応じてデバッグ用にセットアップセルのコメントを解除してから、再変換します

---

ノートブック構造のテンプレート

一般的な Milvus のサンプルノートブックは、次の構造に従います。

# 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")
` ``

---

参考資料

このスキルには、references/ の下に 2 つの参考資料があります。タスクがそれらのトピックに関係する場合は、参照してください。

参考資料	参照するタイミング	ファイル
Bootcamp Format	ブートキャンプリポジトリ向けの Milvus 統合チュートリアルを作成するとき（バッジ、ドキュメント構成、セクション形式、サンプルのレイアウト）	references/bootcamp-format.md
Milvus Code Style	pymilvus コードを作成するとき（コレクションの作成、MilvusClient 接続引数、スキーマのパターン、ベストプラクティス）	references/milvus-code-style.md

Bootcamp Format（references/bootcamp-format.md）

ブートキャンプリポジトリ向けの Milvus 統合チュートリアルを作成するときに参照してください。次の内容を扱います。

• バッジの形式（先頭に Colab バッジと GitHub バッジを配置）
• ドキュメント構成：ヘッダー -> 前提条件 -> メインコンテンツ -> まとめ
• Google Colab の再起動に関する注記を含む依存関係のインストール形式
• API キーのプレースホルダー規約（"sk-***********"）
• 各コードブロックの前に、短い説明文を記載すること

Milvus Code Style（references/milvus-code-style.md）

ノートブックで pymilvus コードを使用する場合に参照してください。主なルールは次のとおりです。

• 必ず MilvusClient API を使用してください — レガシー ORM レイヤー（connections.connect()、Collection()、FieldSchema() など）は使用しないでください
• スキーマは必ず明示的に定義してください（create_schema + add_field） — スキーマを指定せずに省略形の create_collection(dimension=...) を使用しないでください
• コレクションを作成する前に has_collection チェックを含めてください
• create_collection() にコメントアウトした consistency_level="Strong" の行を追加してください
• load_collection() の呼び出しは不要です — コレクションは作成時に自動でロードされます
• 最初の MilvusClient 接続には、uri のオプション（Milvus Lite／Docker／Zilliz Cloud）を説明する引用ブロックを含めてください

---

重要な注意事項

• 必ず .md ファイルを編集してください。.ipynb を直接編集しないでください。.md のほうが AI にとって読み書きしやすいためです。
• 両方のファイルを保持してください — 編集用に .md を、実行／共有用に .ipynb を使用します。
• .md を編集した後は、必ず uvx jupyter-switch example.md を再実行して .ipynb を同期してください。