From 995dee594148531d7f71bb689045f73486546056 Mon Sep 17 00:00:00 2001
From: WilliamK112 <164879897+WilliamK112@users.noreply.github.com>
Date: Fri, 21 Aug 2026 15:20:47 +0800
Subject: [PATCH 1/2] ci: smoke-test notebooks

Signed-off-by: WilliamK112 <164879897+WilliamK112@users.noreply.github.com>
---
 .github/workflows/notebooks.yml | 79 +++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 .github/workflows/notebooks.yml

diff --git a/.github/workflows/notebooks.yml b/.github/workflows/notebooks.yml
new file mode 100644
index 00000000..1238d975
--- /dev/null
+++ b/.github/workflows/notebooks.yml
@@ -0,0 +1,79 @@
+name: Notebook smoke
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "notebooks/**"
+      - "src/freshdata/**"
+      - "pyproject.toml"
+      - ".github/workflows/notebooks.yml"
+  pull_request:
+    paths:
+      - "notebooks/**"
+      - "src/freshdata/**"
+      - "pyproject.toml"
+      - ".github/workflows/notebooks.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: notebooks-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install notebook smoke dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e . nbclient nbformat ipykernel
+
+      - name: Validate notebook JSON
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+
+          import nbformat
+
+          notebooks = sorted(Path("notebooks").rglob("*.ipynb"))
+          if not notebooks:
+              raise SystemExit("no notebooks found")
+
+          for path in notebooks:
+              notebook = nbformat.read(path, as_version=4)
+              nbformat.validate(notebook)
+              print(f"validated {path}")
+          PY
+
+      # Keep optional ML/model notebooks out of required CI. The quickstart is
+      # deliberately dependency-light and exercises the installed package.
+      - name: Execute quickstart notebook
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+
+          import nbformat
+          from nbclient import NotebookClient
+
+          path = Path("notebooks/01_quickstart.ipynb")
+          notebook = nbformat.read(path, as_version=4)
+          NotebookClient(
+              notebook,
+              timeout=120,
+              kernel_name="python3",
+              resources={"metadata": {"path": str(path.parent)}},
+          ).execute()
+          print(f"executed {path}")
+          PY

From 30146eda0471e223e64789464e3e9b3752e20a03 Mon Sep 17 00:00:00 2001
From: WilliamK112 <164879897+WilliamK112@users.noreply.github.com>
Date: Fri, 21 Aug 2026 15:42:33 +0800
Subject: [PATCH 2/2] ci: harden notebook smoke environment

Signed-off-by: WilliamK112 <164879897+WilliamK112@users.noreply.github.com>
---
 .github/workflows/notebooks.yml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/notebooks.yml b/.github/workflows/notebooks.yml
index 1238d975..4f6c1b87 100644
--- a/.github/workflows/notebooks.yml
+++ b/.github/workflows/notebooks.yml
@@ -29,6 +29,8 @@ jobs:
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
 
       - uses: actions/setup-python@v5
         with:
@@ -39,6 +41,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -e . nbclient nbformat ipykernel
+          python -m ipykernel install --user --name freshdata-smoke
 
       - name: Validate notebook JSON
         run: |
@@ -72,7 +75,7 @@ jobs:
           NotebookClient(
               notebook,
               timeout=120,
-              kernel_name="python3",
+              kernel_name="freshdata-smoke",
               resources={"metadata": {"path": str(path.parent)}},
           ).execute()
           print(f"executed {path}")