ci(run-notebook): replace whole-cell bash partition with nbclient (#573)

## Purpose

The current `run-notebook` action partitions each code cell whole-cell:
cells containing `!pip` go entirely to a bash script, the rest go to a
Python script. A cell that mixes `!pip install` with Python imports — a
standard Jupyter pattern — fails with `import: command not found`
because bash tries to execute Python as a shell command. See PR #572 /
[run
25743389812](https://github.com/pinecone-io/examples/actions/runs/25743389812/job/75599935724)
for a live example.

## Solution

Drive notebooks through [`nbclient`](https://nbclient.readthedocs.io/),
the same tool Project Jupyter ships behind `jupyter nbconvert
--execute`. `nbclient` launches a real `ipykernel` and processes cells
line-by-line: `!pip` and other shell magics route through the kernel's
magic handlers (subshell), Python runs as Python. Mixed cells work
exactly as they do in Colab and Jupyter Lab.

## Changes

- New `run-notebook.py`: 50-line nbclient driver. Takes the notebook
path as its only arg. Exits 0 on success, 1 on any cell error, 2 on
usage error.
- Updated `action.yml`: installs `nbformat nbclient ipykernel` into the
runner Python, then invokes the new script. No tempdir, no nested venv,
no bash conversion.
- Removed `convert-notebook.py` (~120 lines).

Net diff: 66 insertions, 137 deletions.

## Verification

Tested locally against the notebook from PR #572
(`docs/quick-tour/hello-pinecone.ipynb`, with `!pip install` and Python
imports in the same cell — the case that breaks today's runner):

```
$ python .github/actions/run-notebook/run-notebook.py docs/quick-tour/hello-pinecone.ipynb
Executing docs/quick-tour/hello-pinecone.ipynb
PASS — docs/quick-tour/hello-pinecone.ipynb
```

## Notes

- **`check-structure` follow-up.** The lint rule "imports must be in the
first code cell" was designed around today's runner: under the new
runner, a single cell holding `!pip install` + imports is once again the
correct pattern. Either relax the rule to skip pip-only cells when
locating "the first code cell," or remove the rule entirely. Separate
PR.
- **Notebook dep isolation.** Notebook deps now install into the
runner's Python (the kernel shares its interpreter), not a nested venv.
Acceptable for CI (ephemeral runner) and simpler than the previous
tempdir/venv dance.
- **Per-cell timeout.** 600s by default, overridable via
`NOTEBOOK_CELL_TIMEOUT`.
- **Soak.** Worth running this against a known-passing notebook before
merging to confirm no regressions on the existing fleet — let me know if
you want me to dual-run on a sample.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes the CI notebook execution mechanism from a custom
conversion/venv+bash flow to `nbclient` driving a real Jupyter kernel,
which may alter dependency/runtime behavior and failure modes across the
notebook suite.
> 
> **Overview**
> Updates the `run-notebook` composite action to execute notebooks
end-to-end using `nbclient`/`ipykernel` instead of converting cells into
separate bash/python scripts.
> 
> This removes `convert-notebook.py`, installs `nbformat nbclient
ipykernel` on the runner, and adds `run-notebook.py` which runs the
notebook with a real kernel, returning clearer per-cell errors and
supporting mixed `!pip` + Python cells (with an optional
`NOTEBOOK_CELL_TIMEOUT`).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
f87187a. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: jhamon

.github/actions/run-notebook/action.yml

@@ -1,5 +1,5 @@
 name: "Run Notebook"
-description: "Run a notebook"
+description: "Run a notebook end-to-end against a real Jupyter kernel via nbclient"
 
 inputs:
   notebook:
@@ -26,34 +26,18 @@ runs:
       with:
         python-version: '3.11'
 
-    - name: Install dependencies
+    - name: Install runner dependencies
       shell: bash
       run: |
         pip install --upgrade pip
-        pip install nbformat
+        pip install nbformat nbclient ipykernel
 
-    - id: convert
+    - name: Run the notebook
       shell: bash
-      name: Convert notebook into tmpdir script
       run: |
-        python .github/actions/run-notebook/convert-notebook.py ${{ inputs.notebook }}
-    
-    - name: View the run script
-      shell: bash
-      run: |
-        cat ${{ steps.convert.outputs.script_path }}
-
-    - name: View converted notebook content
-      shell: bash
-      run: |
-        cat ${{ steps.convert.outputs.notebook_path }}
-
-    - name: Run the converted notebook
-      shell: bash
-      run: |
-        bash ${{ steps.convert.outputs.script_path }}
+        python .github/actions/run-notebook/run-notebook.py "${{ inputs.notebook }}"
       env:
         PINECONE_API_KEY: ${{ inputs.PINECONE_API_KEY }}
         OPENAI_API_KEY: ${{ inputs.OPENAI_API_KEY }}
         HF_TOKEN: ${{ inputs.HF_TOKEN }}
-        ANTHROPIC_API_KEY: ${{ inputs.ANTHROPIC_API_KEY }}
+        ANTHROPIC_API_KEY: ${{ inputs.ANTHROPIC_API_KEY }}

.github/actions/run-notebook/convert-notebook.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python
+"""Execute a notebook end-to-end against a real Jupyter kernel.
+
+Replaces the cell-partitioning approach in convert-notebook.py with a
+straight nbclient drive. This means:
+
+  - !pip install and other shell magics run via the kernel's normal magic
+    handling (the kernel spawns a subshell), exactly as in Colab/Jupyter Lab.
+  - A code cell may freely mix `!pip install` and Python imports.
+  - Errors surface with cell and traceback context, not as
+    `line N: import: command not found`.
+
+Notebook deps are installed into the same Python environment as the
+runner (the kernel and runner share an interpreter), so `!pip install foo`
+in cell 1 means cell 2 can `import foo`.
+
+Usage:
+  run-notebook.py <notebook-path>
+
+Exits non-zero on any cell failure.
+"""
+
+import os
+import sys
+
+import nbformat
+from nbclient import NotebookClient
+from nbclient.exceptions import CellExecutionError, CellTimeoutError, DeadKernelError
+
+CELL_TIMEOUT = int(os.environ.get("NOTEBOOK_CELL_TIMEOUT", "600"))
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("usage: run-notebook.py <notebook-path>", file=sys.stderr)
+        return 2
+
+    notebook_path = sys.argv[1]
+    print(f"Executing {notebook_path}")
+
+    nb = nbformat.read(notebook_path, as_version=4)
+    client = NotebookClient(
+        nb,
+        timeout=CELL_TIMEOUT,
+        kernel_name="python3",
+        resources={"metadata": {"path": os.path.dirname(notebook_path) or "."}},
+    )
+
+    try:
+        client.execute()
+    except CellTimeoutError as exc:
+        print(
+            f"\nCell exceeded timeout of {CELL_TIMEOUT}s "
+            f"(override via NOTEBOOK_CELL_TIMEOUT):\n{exc}",
+            file=sys.stderr,
+        )
+        return 1
+    except DeadKernelError as exc:
+        print(
+            f"\nKernel died during execution (OOM/segfault?):\n{exc}", file=sys.stderr
+        )
+        return 1
+    except CellExecutionError as exc:
+        print(f"\nCell execution failed:\n{exc}", file=sys.stderr)
+        return 1
+
+    print(f"PASS — {notebook_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())