refactor(docs/quick-tour): modernize hello-pinecone to pinecone 9.0#572
Open
jhamon wants to merge 1 commit into
Open
refactor(docs/quick-tour): modernize hello-pinecone to pinecone 9.0#572jhamon wants to merge 1 commit into
jhamon wants to merge 1 commit into
Conversation
jhamon
added a commit
that referenced
this pull request
May 13, 2026
## 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 -->
## Purpose hello-pinecone.ipynb pinned pinecone==8.0.0 and had imports scattered across non-first code cells (code cells 2, 5, 8, 10), failing check-structure. Ruff reported I001 import-sorting errors in 3 cells. ## Solution - pinecone==8.0.0 → pinecone==9.0.0 (cell 0, pip install) - Consolidate all unconditional imports into the first code cell (pip install cell) per check-structure requirements - Sort imports: stdlib (os, random, time) then third-party (pandas, pinecone) with blank line between groups - Remove scattered import lines from cells 2, 5, 8, 10 - Use keyword arguments throughout (per .ai/notebook-standards.md:53) Refs: harness task NB-087.
jhamon
force-pushed
the
nb-087-hello-pinecone
branch
from
c90cdc2 to
1c9c9a9
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
hello-pinecone.ipynb pinned
pinecone==8.0.0(one major version behind) and hadimports scattered across non-first code cells (code cells 2, 5, 8, 10),
failing the
check-structurevalidator. Ruff reportedI001import-sortingerrors in three cells where stdlib and third-party imports were not separated
by a blank line.
Solution
pinecone==8.0.0→pinecone==9.0.0(pip install cell)cell) per
check-structurerequirements:os,random,time,pandas,and all
pineconesymbols now live in a single block at the topos,random,time) then third-party group(
pandas, pinecone symbols) with a blank line between groups — fixes allI001findingsVerification
ruff checkcleanruff format --checkcleancheck-pinningpassescheck-secretspassescheck-structurepassescheck-timelesspassespinecone.init/pinecone-client/environment=patterns remainingpc.delete_index(name=index_name)) executed successfullyAdvisory checks
upserts 10 simulated vectors, waits for indexing, runs a cosine-similarity
query, and deletes the index. Output shape and values unchanged.
Refs
Note
Low Risk
Low risk documentation-only change: updates a tutorial notebook’s dependency pin and reorganizes notebook cells/imports without changing the underlying API flow.
Overview
Updates
docs/quick-tour/hello-pinecone.ipynbto pinpinecone==9.0.0(from 8.x) and consolidates/sorts all imports into the first install cell.Cleans the notebook for tooling/validation by clearing execution counts/outputs and normalizing cell
ids, removing redundant per-cell imports while keeping the index create/upsert/query/delete steps the same.Reviewed by Cursor Bugbot for commit 1c9c9a9. Bugbot is set up for automated code reviews on this repo. Configure here.