stipple 0.1.0__tar.gz

stipple-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+
+# Node
+node_modules/
+*.tsbuildinfo
+
+# Vite output is built artifact, but tracked because anywidget loads from it
+# Uncomment to exclude from git if we switch to a release-only build:
+# src/stipple/_static/
+
+# IDE / OS
+.DS_Store
+.vscode/
+.idea/
+
+# Jupyter
+.ipynb_checkpoints/
+.jupyter-probe/
+
+# Probe diagnostic screenshots — regenerable via scripts/probe_*.py
+scripts/*.png
+scripts/g*-result.png
+scripts/ex-*.png
+scripts/sticky-*.png

stipple-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Ledbetter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stipple-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: stipple
+Version: 0.1.0
+Summary: WebGPU scatter widget for Jupyter — render millions of points, lasso, return row indices to Python.
+Project-URL: Homepage, https://github.com/smledbetter/stipple
+Project-URL: Repository, https://github.com/smledbetter/stipple
+Project-URL: Issues, https://github.com/smledbetter/stipple/issues
+Project-URL: Changelog, https://github.com/smledbetter/stipple/releases
+Author-email: Steve Ledbetter <smledbetter@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: anywidget,jupyter,lasso,ml,scatter,visualization,webgpu
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Jupyter :: JupyterLab
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: anywidget>=0.9
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyarrow>=15
+Requires-Dist: traitlets>=5
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: ipywidgets>=8.1; extra == 'dev'
+Requires-Dist: jupyterlab>=4.4; extra == 'dev'
+Requires-Dist: pandas>=2.2; extra == 'dev'
+Requires-Dist: playwright>=1.55; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: ipywidgets>=8.1; extra == 'examples'
+Requires-Dist: jupyterlab>=4.4; extra == 'examples'
+Requires-Dist: scikit-learn>=1.4; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# Stipple
+
+WebGPU scatter widget for Jupyter. Render millions of points, lasso a region, get the row indices back in Python.
+
+```python
+from stipple import Stipple
+w = Stipple(df, x="umap_0", y="umap_1", color="label")
+w
+# ... user lassos in widget ...
+w.selected_indices  # numpy array
+```
+
+## Status
+
+Pre-release. Gate ladder:
+
+- [x] **G0** — Package skeleton + 100-point WebGPU render
+- [ ] **G1** — Arrow-over-comm transport (1M rows)
+- [ ] **G2** — 1M scatter with pan/zoom + discrete color
+- [ ] **G3** — 10M scale via chunked buffers
+- [ ] **G4** — Polygon lasso → `selected_indices`
+- [ ] **G5** — Example notebooks + cross-env test matrix
+- [ ] **G6** — Wheel packaging
+
+## Dev setup
+
+```bash
+uv sync --extra dev
+cd js && npm install && npm run build && cd ..
+uv run jupyter lab examples/
+```
+
+## Architecture
+
+- Python: `anywidget.AnyWidget` subclass with `traitlets`. Arrow IPC over the comm channel for tensor/DataFrame transport.
+- JS: Vite-built ESM bundle at `src/stipple/_static/index.js`. WebGPU scatter pipeline with instanced unit quads.
+
+See `Projects/Research/Stipple/JUPYTER-WIDGET-RESEARCH.md` in the upstream Thinking vault for design rationale.
+
+## License
+
+MIT

stipple-0.1.0/README.md

@@ -0,0 +1,42 @@
+# Stipple
+
+WebGPU scatter widget for Jupyter. Render millions of points, lasso a region, get the row indices back in Python.
+
+```python
+from stipple import Stipple
+w = Stipple(df, x="umap_0", y="umap_1", color="label")
+w
+# ... user lassos in widget ...
+w.selected_indices  # numpy array
+```
+
+## Status
+
+Pre-release. Gate ladder:
+
+- [x] **G0** — Package skeleton + 100-point WebGPU render
+- [ ] **G1** — Arrow-over-comm transport (1M rows)
+- [ ] **G2** — 1M scatter with pan/zoom + discrete color
+- [ ] **G3** — 10M scale via chunked buffers
+- [ ] **G4** — Polygon lasso → `selected_indices`
+- [ ] **G5** — Example notebooks + cross-env test matrix
+- [ ] **G6** — Wheel packaging
+
+## Dev setup
+
+```bash
+uv sync --extra dev
+cd js && npm install && npm run build && cd ..
+uv run jupyter lab examples/
+```
+
+## Architecture
+
+- Python: `anywidget.AnyWidget` subclass with `traitlets`. Arrow IPC over the comm channel for tensor/DataFrame transport.
+- JS: Vite-built ESM bundle at `src/stipple/_static/index.js`. WebGPU scatter pipeline with instanced unit quads.
+
+See `Projects/Research/Stipple/JUPYTER-WIDGET-RESEARCH.md` in the upstream Thinking vault for design rationale.
+
+## License
+
+MIT

stipple-0.1.0/TESTING.md

@@ -0,0 +1,52 @@
+# Stipple env support matrix
+
+The automated probes in `scripts/probe_g*.py` cover **JupyterLab on M4
+Chromium with WebGPU flags** end-to-end. The matrix below is the manual
+verification grid for the remaining environments. Fill in as tested.
+
+| Environment | Status | Notes |
+|---|---|---|
+| JupyterLab / Chromium (probe) | ✓ verified | `scripts/probe_g4.py` green; FPS 60+ at 10M |
+| JupyterLab / real Chrome 134+ | _pending_ | Open `examples/embeddings.ipynb`; check the lasso |
+| JupyterLab / real Safari 26+ | _pending_ | Safari 26 ships WebGPU on Apple Silicon |
+| VSCode notebook | _pending_ | Webview is Chromium-based; expected to work |
+| Google Colab | _pending_ | Cross-origin output iframe — may fail; not load-bearing |
+| JupyterHub | _pending_ | `anywidget` must be installed in the kernel env, not just the launch env |
+
+## How to fill in a row manually
+
+```bash
+# Install the dev extras (jupyterlab + sklearn + ipywidgets, etc.)
+uv sync --extra dev --extra examples
+# Build the JS bundle if you haven't yet
+cd js && npm install && npm run build && cd ..
+# Launch
+uv run jupyter lab examples/embeddings.ipynb
+```
+
+Then in the browser:
+1. Run all cells
+2. Shift+drag in the widget canvas
+3. Run the inspection cell — `w.selected_indices` should be populated
+
+For Safari, navigate manually to the JupyterLab URL printed in the terminal.
+
+For Colab: `pip install stipple` inside a Colab cell, then upload the example
+notebook. Per the upstream research note this row is the load-bearing one
+for "covers most ML researchers"; treat any failure as expected and document
+the symptom.
+
+For VSCode: open the example notebook directly in VSCode (Python +
+Jupyter extensions installed), select the `.venv` interpreter, run cells.
+
+## Known caveats
+
+- `widget model not found` console errors during initial widget setup are
+  benign — JupyterLab's manager probes for the model before the comm
+  channel completes registration. The final view is properly connected,
+  proven by the bidirectional trait sync.
+- WebGPU is gated behind a permissions banner in some Chrome
+  configurations; if no adapter is found, check `chrome://flags` for
+  `#enable-unsafe-webgpu` and Linux users may also need `#enable-vulkan`.
+- The widget requires HTTPS or `localhost` — WebGPU is blocked on plain
+  HTTP origins outside localhost.

stipple-0.1.0/examples/dedup.ipynb

@@ -0,0 +1,163 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "422f3f70",
+   "metadata": {},
+   "source": [
+    "# Near-duplicate discovery with Stipple\n",
+    "\n",
+    "**Recipe:** render an embedding of your dataset, look for tight micro-clusters in the projection, lasso them to recover the row indices of suspected near-duplicates.\n",
+    "\n",
+    "This example uses **synthetic** 2D embeddings with planted near-duplicate clusters so the visualization is reproducible. In real use you'd substitute MinHash-LSH projections, sentence-embedding projections, etc.\n",
+    "\n",
+    "## Setup\n",
+    "200k synthetic 'documents' embedded in 2D. 195k are diffuse Gaussian noise; 5k form 50 tight planted near-duplicate clusters of size ~100, scattered across the embedding space."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "74795c66",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "from stipple import Stipple"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "5b1051e5",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "200,000 total points · 195,000 background · 5,000 planted duplicates in 50 clusters\n",
+      "Planted-dup indices: [195,000, 200,000)\n"
+     ]
+    }
+   ],
+   "source": [
+    "rng = np.random.default_rng(0)\n",
+    "n_noise = 195_000\n",
+    "n_clusters = 50\n",
+    "per_cluster = 100\n",
+    "n_dups = n_clusters * per_cluster\n",
+    "n = n_noise + n_dups\n",
+    "\n",
+    "# Diffuse 'unique' documents (background)\n",
+    "x_noise = rng.standard_normal(n_noise).astype(np.float32) * 3.0\n",
+    "y_noise = rng.standard_normal(n_noise).astype(np.float32) * 3.0\n",
+    "\n",
+    "# Planted near-duplicate clusters: 50 cluster centers in the same range,\n",
+    "# each producing ~100 points within a tight (~0.05) Gaussian.\n",
+    "centers = rng.standard_normal((n_clusters, 2)).astype(np.float32) * 3.0\n",
+    "x_dups = np.empty(n_dups, dtype=np.float32)\n",
+    "y_dups = np.empty(n_dups, dtype=np.float32)\n",
+    "for k in range(n_clusters):\n",
+    "    sl = slice(k * per_cluster, (k + 1) * per_cluster)\n",
+    "    x_dups[sl] = centers[k, 0] + rng.standard_normal(per_cluster).astype(np.float32) * 0.04\n",
+    "    y_dups[sl] = centers[k, 1] + rng.standard_normal(per_cluster).astype(np.float32) * 0.04\n",
+    "\n",
+    "x = np.concatenate([x_noise, x_dups])\n",
+    "y = np.concatenate([y_noise, y_dups])\n",
+    "labels = np.concatenate([\n",
+    "    np.full(n_noise, 'noise'),\n",
+    "    np.full(n_dups, 'planted-dup'),\n",
+    "])\n",
+    "\n",
+    "print(f'{n:,} total points · {n_noise:,} background · {n_dups:,} planted duplicates in {n_clusters} clusters')\n",
+    "print(f'Planted-dup indices: [{n_noise:,}, {n:,})')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "f8b250d8",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "78b3bef30ddc4f1ca49b2f5421a706f6",
+       "version_major": 2,
+       "version_minor": 1
+      },
+      "text/plain": [
+       "<stipple.widget.Stipple object at 0x1096a0680>"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "w = Stipple(x=x, y=y, color=labels)\n",
+    "w"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d5e64cbe",
+   "metadata": {},
+   "source": [
+    "**Try:** zoom into a high-density spot (wheel up to zoom). The planted duplicate clusters appear as tight orange specks against the blue background haze. Shift+drag around one to lasso it."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "ae4ca0bb",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "No selection yet. Zoom into a tight cluster and shift+drag to lasso it.\n"
+     ]
+    }
+   ],
+   "source": [
+    "idx = w.selected_indices\n",
+    "if len(idx) == 0:\n",
+    "    print('No selection yet. Zoom into a tight cluster and shift+drag to lasso it.')\n",
+    "else:\n",
+    "    planted = (idx >= n_noise).sum()\n",
+    "    purity = planted / max(1, len(idx))\n",
+    "    print(f'Selected {len(idx):,} points · {purity:.1%} from planted-dup region')\n",
+    "    if planted > 0:\n",
+    "        # Show which planted cluster(s) we hit\n",
+    "        local = idx[idx >= n_noise] - n_noise\n",
+    "        clusters = np.unique(local // per_cluster)\n",
+    "        print(f'Planted clusters hit: {clusters.tolist()}')"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

stipple-0.1.0/examples/embeddings.ipynb

@@ -0,0 +1,176 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "82f186fa",
+   "metadata": {},
+   "source": [
+    "# Embedding visualization with Stipple\n",
+    "\n",
+    "Render an embedding projection, lasso a region of interest, get the row indices back in Python — the canonical ML-researcher workflow.\n",
+    "\n",
+    "This example uses the `sklearn` digits dataset (1797 samples, 8×8 grayscale digits 0–9). PCA → 2D for display. Replace with your own embedding + UMAP / t-SNE / PCA in real use.\n",
+    "\n",
+    "## Workflow\n",
+    "1. Compute (or load) a 2-D embedding\n",
+    "2. Pass `x`, `y`, `color` to `Stipple(...)`\n",
+    "3. Shift+drag in the canvas to lasso a region\n",
+    "4. Read `w.selected_indices` back in Python\n",
+    "5. Do something with those rows: inspect, retrain on, etc."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "6362f475",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "from sklearn.datasets import load_digits\n",
+    "from sklearn.decomposition import PCA\n",
+    "from stipple import Stipple"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "9baf56cf",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "1,797 samples · 64 features → 2D projection\n"
+     ]
+    }
+   ],
+   "source": [
+    "digits = load_digits()\n",
+    "X, y = digits.data, digits.target\n",
+    "proj = PCA(n_components=2).fit_transform(X)\n",
+    "labels = np.array([str(d) for d in y])\n",
+    "print(f'{X.shape[0]:,} samples · {X.shape[1]} features → 2D projection')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "id": "4c0ae8ac",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "9e0ae961241f43ae8f5207d354537922",
+       "version_major": 2,
+       "version_minor": 1
+      },
+      "text/plain": [
+       "<stipple.widget.Stipple object at 0x114711430>"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "w = Stipple(x=proj[:, 0], y=proj[:, 1], color=labels)\n",
+    "w"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "id": "039f6ecb-8488-486a-969a-09a82ca3bf2d",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "len: 235 count: 1 id: 4637922352\n"
+     ]
+    }
+   ],
+   "source": [
+    "  print(\"len:\", len(w.selected_indices), \"count:\", w.selection_count, \"id:\", id(w))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8691db73",
+   "metadata": {},
+   "source": [
+    "Shift+drag in the canvas above to lasso a cluster of digits. Then run the next cell to inspect what you selected."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "8ed86bac",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "No selection yet. Shift+drag in the widget above to lasso a region, then re-run this cell.\n"
+     ]
+    }
+   ],
+   "source": [
+    "import collections\n",
+    "idx = w.selected_indices\n",
+    "if len(idx) == 0:\n",
+    "    print('No selection yet. Shift+drag in the widget above to lasso a region, then re-run this cell.')\n",
+    "else:\n",
+    "    counts = collections.Counter(y[idx].tolist())\n",
+    "    print(f'Selected {len(idx):,} samples')\n",
+    "    print('Digit distribution:')\n",
+    "    for digit, c in sorted(counts.items()):\n",
+    "        bar = '█' * int(40 * c / max(counts.values()))\n",
+    "        print(f'  {digit}: {c:>4}  {bar}')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c80f9f41-ed32-467e-8500-50bf745c2108",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b104fd5c-ab21-4202-8dd4-e41c8fb064e9",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

stipple-0.1.0/examples/g0_smoke.ipynb

@@ -0,0 +1,70 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "467aa9d1",
+   "metadata": {},
+   "source": [
+    "# Stipple G0 smoke test\n",
+    "\n",
+    "Verifies the package skeleton + WebGPU pipeline render 100 points."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1607176b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from stipple import Stipple\n",
+    "import stipple\n",
+    "print(f\"stipple {stipple.__version__}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "273f5a85",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "w = Stipple()\n",
+    "w"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9e0c662c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(f\"status: {w.status}\")\n",
+    "print(f\"adapter_info: {w.adapter_info}\")\n",
+    "print(f\"error: {w.error}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}