embedgl 0.0.1__py3-none-any.whl

embedgl/widget.py

@@ -0,0 +1,378 @@
+from __future__ import annotations
+
+import io
+import json
+import uuid
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+import anywidget
+import numpy as np
+import polars as pl
+import traitlets
+from PIL import Image
+
+from .query import evaluate, field_kind, scalar
+
+
+class EmbeddingViewer(anywidget.AnyWidget):
+    """Explore projected rows without transferring the source DataFrame to the browser."""
+
+    _esm = Path(__file__).parent / "static" / "widget.js"
+    _css = Path(__file__).parent / "static" / "widget.css"
+    dataset = traitlets.Dict().tag(sync=True)
+    query = traitlets.Dict().tag(sync=True)
+    selected_count = traitlets.Int(0).tag(sync=True)
+    selection_revision = traitlets.Int(0).tag(sync=True)
+    height = traitlets.Int(640, min=320, max=2000).tag(sync=True)
+
+    def __init__(
+        self,
+        frame: pl.DataFrame,
+        *,
+        id_column: str,
+        coordinates_2d: Sequence[str] | None = None,
+        coordinates_3d: Sequence[str] | None = None,
+        cluster_column: str | None = None,
+        thumbnail_column: str | None = "thumbnail",
+        image_column: str | None = None,
+        searchable_columns: Sequence[str] = (),
+        filterable_columns: Sequence[str] = (),
+        metadata_columns: Sequence[str] = (),
+        height: int = 640,
+    ) -> None:
+        self.id_column = id_column
+        self.coordinate_columns = {
+            mode: tuple(columns)
+            for mode, columns in (("2d", coordinates_2d), ("3d", coordinates_3d))
+            if columns is not None
+        }
+        self.cluster_column = cluster_column
+        self.thumbnail_column = thumbnail_column
+        self.image_column = image_column
+        self.searchable_columns = list(searchable_columns)
+        self.filterable_columns = list(filterable_columns)
+        self.metadata_columns = list(dict.fromkeys([*metadata_columns, id_column]))
+        self._selected = np.empty(0, dtype="<u4")
+        self._query_revision = 0
+        self._text = ""
+        self._filters: list[dict[str, Any]] = []
+        self._geometry: dict[str, np.ndarray] = {}
+        self._row_column = f"__viewer_{uuid.uuid4().hex}"
+        super().__init__(height=height)
+        self.replace_data(frame)
+        self.on_msg(self._message)
+
+    @property
+    def selected_ids(self) -> list[str | int]:
+        return self._frame[self._selected.tolist(), :].get_column(self.id_column).to_list()
+
+    @property
+    def selected_df(self) -> pl.DataFrame:
+        return self._frame[self._selected.tolist(), :]
+
+    def replace_data(self, frame: pl.DataFrame) -> None:
+        if not isinstance(frame, pl.DataFrame):
+            raise TypeError("frame must be an eager Polars DataFrame")
+        if frame.height >= 2**32:
+            raise ValueError("Row count must fit uint32")
+        if not self.coordinate_columns:
+            raise ValueError("Provide coordinates_2d and/or coordinates_3d")
+        required = {
+            self.id_column,
+            *self.searchable_columns,
+            *self.filterable_columns,
+            *self.metadata_columns,
+        }
+        required.update(column for columns in self.coordinate_columns.values() for column in columns)
+        required.update(column for column in (self.cluster_column, self.image_column) if column)
+        if self.thumbnail_column and self.thumbnail_column in frame.columns:
+            required.add(self.thumbnail_column)
+        missing = required.difference(frame.columns)
+        if missing:
+            raise ValueError(f"Missing columns: {sorted(missing)}")
+        ids = frame.get_column(self.id_column)
+        if not (ids.dtype == pl.String or ids.dtype.is_integer()) or ids.null_count() or ids.n_unique() != frame.height:
+            raise ValueError("IDs must be unique non-null strings or integers")
+        geometry: dict[str, np.ndarray] = {}
+        bounds: dict[str, Any] = {}
+        for mode, columns in self.coordinate_columns.items():
+            if len(columns) != (2 if mode == "2d" else 3):
+                raise ValueError(f"{mode} requires {'two' if mode == '2d' else 'three'} coordinate columns")
+            if any(not frame.schema[column].is_numeric() for column in columns):
+                raise ValueError("Coordinates must be numeric")
+            positions = frame.select(columns).to_numpy().astype("<f4")
+            if not np.isfinite(positions).all():
+                raise ValueError("Coordinates must be finite and non-null")
+            if mode == "2d":
+                positions = np.column_stack((positions, np.zeros(frame.height, dtype="<f4")))
+            geometry[mode] = np.ascontiguousarray(positions, dtype="<f4")
+            bounds[mode] = {
+                "min": positions.min(axis=0).tolist() if frame.height else [0, 0, 0],
+                "max": positions.max(axis=0).tolist() if frame.height else [0, 0, 0],
+            }
+        fields = [{"name": column, "kind": field_kind(frame.schema[column])} for column in self.filterable_columns]
+        for column in self.searchable_columns:
+            if field_kind(frame.schema[column]) != "string":
+                raise ValueError(f"Search column must be a string: {column}")
+        for column in (self.thumbnail_column, self.image_column):
+            if column and column in frame.columns and frame.schema[column] != pl.Binary:
+                raise ValueError(f"Image column must have Binary dtype: {column}")
+        for column in self.metadata_columns:
+            if frame.schema[column] == pl.Binary or frame.schema[column].is_nested():
+                raise ValueError(f"Metadata must be scalar: {column}")
+        legend: list[dict[str, Any]] = []
+        unique: list[str] = []
+        if self.cluster_column:
+            field_kind(frame.schema[self.cluster_column])
+            labels = frame.get_column(self.cluster_column).cast(pl.String).fill_null("(null)")
+            codes, unique = labels.to_numpy(), labels.unique(maintain_order=True).to_list()
+            mapping = {label: index for index, label in enumerate(unique)}
+            cluster_codes = np.fromiter((mapping[label] for label in codes), dtype="<u4", count=frame.height)
+            legend = [{"code": index, "label": label} for index, label in enumerate(unique[:200])]
+        else:
+            cluster_codes = np.zeros(frame.height, dtype="<u4")
+        self._frame = frame.clone()
+        self._indexed = self._frame.with_row_index(self._row_column)
+        self._geometry = geometry
+        self._clusters = cluster_codes
+        self._matches = np.arange(frame.height, dtype="<u4")
+        self._selected = np.empty(0, dtype="<u4")
+        self._query_revision += 1
+        self._text, self._filters = "", []
+        with self.hold_sync():
+            self.selected_count = 0
+            self.selection_revision += 1
+            self.query = {"text": "", "filters": [], "revision": self._query_revision, "count": frame.height}
+            self.dataset = {
+                "revision": uuid.uuid4().hex,
+                "count": frame.height,
+                "modes": list(geometry),
+                "bounds": bounds,
+                "fields": fields,
+                "searchable": self.searchable_columns,
+                "metadata": self.metadata_columns,
+                "clusters": legend,
+                "cluster_count": len(unique) if self.cluster_column else 0,
+                "has_images": bool(self.thumbnail_column and self.thumbnail_column in frame.columns),
+            }
+
+    def set_search(self, text: str) -> None:
+        self._set_query(text, self._filters)
+
+    def set_filters(self, filters: Sequence[dict[str, Any]]) -> None:
+        self._set_query(self._text, list(filters))
+
+    def _set_query(self, text: str, filters: list[dict[str, Any]]) -> None:
+        if not isinstance(text, str) or not isinstance(filters, list):
+            raise ValueError("Query requires string text and a filter list")
+        encoded = json.dumps(filters, allow_nan=False)
+        if len(encoded) > 65536:
+            raise ValueError("Filters exceed the 64 KiB limit")
+        filters = json.loads(encoded)
+        indices = (
+            evaluate(
+                self._indexed,
+                self._row_column,
+                text,
+                filters,
+                self.searchable_columns,
+                self.filterable_columns,
+            )
+            .to_numpy()
+            .astype("<u4", copy=False)
+        )
+        if text == self.query.get("text") and filters == self.query.get("filters"):
+            return
+        self._matches = indices
+        self._selected = np.empty(0, dtype="<u4")
+        self._query_revision += 1
+        self._text, self._filters = text, filters
+        with self.hold_sync():
+            self.selected_count = 0
+            self.selection_revision += 1
+            self.query = {"text": text, "filters": filters, "revision": self._query_revision, "count": len(indices)}
+
+    def set_selection(self, ids: Sequence[str | int], mode: str = "replace") -> None:
+        values = list(ids)
+        rows = self._indexed.filter(pl.col(self.id_column).is_in(values)).get_column(self._row_column).to_numpy()
+        if len(rows) != len(set(values)):
+            raise ValueError("Selection contains unknown IDs")
+        self._select(rows, mode)
+
+    def clear_selection(self) -> None:
+        self._select(np.empty(0, dtype="<u4"), "replace")
+
+    def _select(self, rows: np.ndarray, mode: str) -> None:
+        if mode not in {"replace", "add", "remove"}:
+            raise ValueError("Selection mode must be replace, add or remove")
+        if len(rows) and (rows.min() < 0 or rows.max() >= self._frame.height):
+            raise ValueError("Selection row out of bounds")
+        if mode == "add":
+            selected = np.union1d(self._selected, rows)
+        elif mode == "remove":
+            selected = np.setdiff1d(self._selected, rows)
+        else:
+            selected = np.unique(rows)
+        self._selected = np.asarray(selected, dtype="<u4")
+        with self.hold_sync():
+            self.selected_count = len(self._selected)
+            self.selection_revision += 1
+
+    def _reply(self, request: dict[str, Any], payload: dict[str, Any], buffers: list[bytes] | None = None) -> None:
+        self.send(
+            {
+                "version": 1,
+                "request_id": request.get("request_id"),
+                "dataset_revision": self.dataset["revision"],
+                "query_revision": self.query["revision"],
+                **payload,
+            },
+            buffers=buffers or [],
+        )
+
+    def _message(self, widget: anywidget.AnyWidget, content: dict[str, Any], buffers: list[memoryview]) -> None:
+        del widget
+        if not isinstance(content, dict):
+            return
+        try:
+            if content.get("version") != 1:
+                raise ValueError("Unsupported protocol version")
+            if content.get("dataset_revision") != self.dataset["revision"]:
+                raise ValueError("Dataset changed; reload this view")
+            operation = content.get("op")
+            if (
+                operation in {"select", "select_all", "query", "page", "matches", "facets"}
+                and content.get("query_revision") != self.query["revision"]
+            ):
+                raise ValueError("Query changed; retry with the current query")
+            if operation == "geometry":
+                mode = str(content.get("mode"))
+                positions = self._geometry[mode]
+                start = max(0, int(content.get("start", 0)))
+                end = min(start + 65536, self._frame.height)
+                if start > self._frame.height:
+                    raise ValueError("Invalid geometry offset")
+                self._reply(
+                    content,
+                    {"op": "geometry", "mode": mode, "start": start, "end": end},
+                    [
+                        positions[start:end].tobytes(),
+                        self._clusters[start:end].tobytes(),
+                    ],
+                )
+            elif operation in {"matches", "selection"}:
+                indices = self._matches if operation == "matches" else self._selected
+                start = max(0, int(content.get("start", 0)))
+                end = min(start + 262144, len(indices))
+                self._reply(
+                    content,
+                    {
+                        "op": operation,
+                        "start": start,
+                        "end": end,
+                        "total": len(indices),
+                        "selection_revision": self.selection_revision,
+                    },
+                    [indices[start:end].tobytes()],
+                )
+            elif operation == "query":
+                self._set_query(content.get("text", ""), content.get("filters", []))
+                self._reply(content, {"op": "query", "query": self.query})
+            elif operation == "page":
+                scope = content.get("scope", "all")
+                if scope not in {"all", "selected"}:
+                    raise ValueError("Page scope must be all or selected")
+                if scope == "selected" and content.get("selection_revision") != self.selection_revision:
+                    raise ValueError("Selection changed; retry with the current selection")
+                offset = max(0, int(content.get("offset", 0)))
+                limit = min(100, max(1, int(content.get("limit", 30))))
+                indices = self._selected if scope == "selected" else self._matches
+                offset = min(offset, max(0, (len(indices) - 1) // limit * limit))
+                rows = indices[offset : offset + limit]
+                records = self._frame[rows.tolist(), :].select(self.metadata_columns).to_dicts()
+                self._reply(
+                    content,
+                    {
+                        "op": "page",
+                        "offset": offset,
+                        "scope": scope,
+                        "selection_revision": self.selection_revision,
+                        "rows": [
+                            {
+                                "index": int(index),
+                                "values": {
+                                    key: scalar(value[:2000] if isinstance(value, str) else value)
+                                    for key, value in record.items()
+                                },
+                            }
+                            for index, record in zip(rows, records, strict=True)
+                        ],
+                    },
+                )
+            elif operation == "detail":
+                index = int(content["index"])
+                if index < 0 or index >= self._frame.height:
+                    raise ValueError("Detail index out of bounds")
+                record = self._frame.select(self.metadata_columns).row(index, named=True)
+                self._reply(
+                    content,
+                    {
+                        "op": "detail",
+                        "index": index,
+                        "values": {
+                            key: scalar(value[:100000] if isinstance(value, str) else value)
+                            for key, value in record.items()
+                        },
+                    },
+                )
+            elif operation == "facets":
+                column = content.get("column")
+                if column not in self.filterable_columns:
+                    raise ValueError("Column is not filterable")
+                offset = max(0, int(content.get("offset", 0)))
+                values = self._frame.get_column(column).drop_nulls().unique().sort()
+                self._reply(
+                    content,
+                    {
+                        "op": "facets",
+                        "column": column,
+                        "total": len(values),
+                        "values": [
+                            scalar(value[:2000] if isinstance(value, str) else value)
+                            for value in values.slice(offset, 100)
+                        ],
+                    },
+                )
+            elif operation == "select_all":
+                self._select(self._matches, "replace")
+                self._reply(content, {"op": "selected"})
+            elif operation == "select":
+                if len(buffers) != 1 or len(buffers[0]) > self._frame.height * 4 or len(buffers[0]) % 4:
+                    raise ValueError("Expected a bounded uint32 selection buffer")
+                self._select(np.frombuffer(buffers[0], dtype="<u4"), content.get("mode", "replace"))
+                self._reply(content, {"op": "selected"})
+            elif operation == "image":
+                index = int(content["index"])
+                if index < 0 or index >= self._frame.height:
+                    raise ValueError("Image index out of bounds")
+                column = self.image_column if content.get("full") and self.image_column else self.thumbnail_column
+                if not column or column not in self._frame.columns:
+                    self._reply(content, {"op": "image", "index": index, "mime": None})
+                    return
+                image_bytes = self._frame.get_column(column)[index]
+                if not image_bytes:
+                    self._reply(content, {"op": "image", "index": index, "mime": None})
+                    return
+                if len(image_bytes) > 20 * 1024 * 1024:
+                    raise ValueError("Image exceeds 20 MiB limit")
+                with Image.open(io.BytesIO(image_bytes)) as image:
+                    mime = Image.MIME.get(image.format or "")
+                if mime not in {"image/jpeg", "image/png", "image/webp", "image/gif"}:
+                    raise ValueError("Unsupported image format")
+                self._reply(content, {"op": "image", "index": index, "mime": mime}, [image_bytes])
+            else:
+                raise ValueError(f"Unknown operation: {operation}")
+        except Exception as error:
+            self._reply(content, {"op": "error", "error": str(error)})

embedgl-0.0.1.dist-info/METADATA

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: embedgl
+Version: 0.0.1
+Summary: JupyterLab widget for visualizing embeddings
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/M-Anwar/embedgl
+Project-URL: Issues, https://github.com/M-Anwar/embedgl/issues
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Jupyter :: JupyterLab
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=10.1
+Requires-Dist: numpy
+Requires-Dist: polars<3,>=2.1
+Requires-Dist: anywidget>=0.9.18
+Requires-Dist: traitlets>=5.9
+Dynamic: license-file
+
+# Embedgl
+
+A React/Three.js anywidget for exploring precomputed 2D and 3D projections in JupyterLab or another anywidget-compatible notebook. An eager Polars DataFrame owns the data in Python. Column search and filters determine which points render; image bytes and metadata are requested on demand.
+
+![EmebedGL Demo Image](examples/sample.png)
+
+## Install
+
+Install into the same environment as your notebook kernel:
+
+```sh
+pip install embedgl
+```
+
+For a local checkout, run `pip install -e .` from the repository root. Python 3.12 or newer is required.
+
+The built JavaScript/CSS assets are included under `embedgl/static` in the installed package. Normal notebook use needs neither Node.js nor a frontend server. No separate custom JupyterLab extension is required; the notebook must support ipywidgets/anywidget and WebGL. In JupyterLab, install `jupyterlab_widgets` in the JupyterLab server environment if it is separate from the kernel environment.
+
+## Try It
+
+Run in a notebook cell:
+
+```python
+from embedgl.demo import make_demo
+
+viewer = make_demo()
+viewer
+```
+
+The demo generates a small Polars DataFrame and synthetic receipt thumbnails locally. It does not load source receipt images or any ML models. Open [examples/usage.ipynb](examples/usage.ipynb) in JupyterLab or VS Code after installing the package, select the environment where `embedgl` is installed, and run the cells in order.
+
+## Your DataFrame
+
+Provide precomputed coordinate columns. **The viewer does not compute projections or clusters.**
+
+```python
+from embedgl import EmbeddingViewer
+
+viewer = EmbeddingViewer(
+    frame,
+    id_column="hash_id",
+    coordinates_2d=("umap_x", "umap_y"),
+    coordinates_3d=("umap3_x", "umap3_y", "umap3_z"),
+    cluster_column="cluster",
+    thumbnail_column="thumbnail",
+    image_column="image",
+    searchable_columns=("file_name", "ocr_text"),
+    filterable_columns=("file_name", "cluster", "amount", "reviewed"),
+    metadata_columns=("file_name", "source_path", "amount"),
+    height=700,
+)
+viewer
+```
+
+Pass only columns that exist in your frame. At least one coordinate set is required; omit `coordinates_3d`, `cluster_column`, `image_column`, or other optional mappings when unavailable. 
+
+- IDs must be unique, non-null strings or integers. Original ID types, including 64-bit integers, stay in Python; browser messages use dense uint32 row indices.
+- Coordinates must be finite numeric values with no nulls. The renderer normalizes their scale locally without modifying the frame.
+- Images must be Polars `Binary` columns containing JPEG, PNG, WebP, or GIF bytes. An absent default `thumbnail` column is allowed; pass `thumbnail_column=None` for a point-only view. Filesystem paths and remote URLs are not automatically opened.
+- Search columns must be string-like. Search is case-insensitive literal substring matching across those columns (OR), combined with filters (AND). Empty search matches all rows.
+- Filter columns support strings/categories, numeric values, booleans, dates, and datetimes. Flatten struct fields before configuring them. List/embedding columns are not filterable.
+- Metadata is an explicit scalar-column whitelist. The ID column is always included. The first two configured metadata columns label result rows. Page text is capped at 2,000 characters per value; requested detail text is capped at 100,000. Binary/nested metadata is rejected. Large integers are represented as strings in metadata responses.
+- The DataFrame is treated as an immutable snapshot. Use `replace_data(new_frame)` to load a replacement with the same configured columns. This clears queries, selections, and browser caches.
+
+## Search and Filters From Python
+
+```python
+viewer.set_search("coffee")
+viewer.set_filters(
+    [
+        {"column": "amount", "op": "gte", "value": 10},
+        {"column": "amount", "op": "lte", "value": 75},
+        {"column": "reviewed", "op": "eq", "value": True},
+    ]
+)
+
+viewer.set_search("")
+viewer.set_filters([])
+```
+
+Supported filter operations:
+
+| Operation | Value | Columns |
+| --- | --- | --- |
+| `contains` | String | String/category |
+| `eq` | Scalar | Any configured filter column |
+| `in` | List of scalars, at most 1,000 | Any configured filter column |
+| `gte`, `lte` | Inclusive bound | Numeric/date/datetime |
+| `is_null`, `not_null` | No value | Any configured filter column |
+
+Pass dates/datetimes as ISO strings, with timezone presence matching the column dtype. Boolean values must be actual booleans, not strings. Decimal/integer bounds can be strings to preserve precision. Ordinary comparisons do not match nulls. Filters are limited to 32 predicates and 64 KiB of JSON. Text search is limited to 4,096 characters. The UI offers the first 100 distinct string values as suggestions; custom values remain accepted. The `in` control accepts a JSON array.
+
+Accepted search/filter changes immediately clear selection and hide unmatched points. They do not resend coordinates or automatically move the camera. Use **Fit matching points** to frame the remaining points explicitly. Results retain source-row order and are paginated 30 at a time.
+
+## Selection
+
+```python
+viewer.selected_ids
+selected_frame = viewer.selected_df
+
+viewer.set_selection(["some-stable-id"])
+viewer.set_selection(["another-id"], mode="add")
+viewer.set_selection(["some-stable-id"], mode="remove")
+viewer.clear_selection()
+```
+
+Use the pan/orbit, rectangle-selection, and circular-selection toolbar modes. For circular selection, press at the desired center, drag outward to set the radius, and release to select. The center stays fixed at the initial press position. Clicking a point in pan/orbit or rectangle mode selects the nearest point; result checkboxes and image details also change selection. Hold Shift to add and Alt to remove during canvas selection. **Select all results** includes every matching row, not just the displayed page. In both 2D and 3D, area selection uses projected screen positions. In 3D, rectangles and circles include all matched points inside their screen-space boundary and camera clip volume, including points behind others.
+
+Programmatic selection can include currently filtered-out rows, which stay selected in Python but are not rendered. A subsequent accepted query change clears the complete selection. `selected_df` preserves source-row order. For change notifications, standard widget observation is available:
+
+```python
+def selection_changed(change):
+    print(viewer.selected_count)
+
+
+viewer.observe(selection_changed, names=["selection_revision"])
+```
+
+Cluster labels only assign colors (an eight-color palette, repeated for larger cluster counts). Hover shows up to 12 nearest overlapping screen-space points, not all members of the semantic cluster. Click a preview to inspect its image and whitelisted metadata.
+
+## Frontend Development
+
+Run these commands from the repository root with Node.js 22 and npm:
+
+```sh
+npm ci
+npm run build
+uv sync
+```
+
+The build typechecks the frontend, bundles React, Three.js, icons, and the inline worker into `src/embedgl/static/widget.js` and `src/embedgl/static/widget.css`, and generates `src/embedgl/THIRD_PARTY_LICENSES.txt`. Commit these generated files so installing a checkout or source distribution does not require Node.js. For continuous compilation:
+
+```sh
+npm run watch
+```
+
+For notebook hot reload, set `ANYWIDGET_HMR=1` before importing the widget. Otherwise create a new widget after rebuilding, or restart the kernel if the old module is cached. Run the full build again before releasing; watch mode does not typecheck or regenerate license notices.
+
+## Release Checks
+
+The Python package lives under `src/embedgl`; frontend sources and examples are not importable Python packages. The version is maintained explicitly in `pyproject.toml`, not derived from Git tags. Update it for each release; PyPI does not allow replacing an uploaded version.
+
+From a clean checkout, build and validate with:
+
+```sh
+npm ci
+npm run build
+uv sync --group dev
+uv run python -m unittest discover -s tests -v
+uv run python -m build
+uv run python scripts/check_dist.py
+uv run python -m twine check --strict dist/*
+```
+
+Start with an empty `dist` directory so old releases are not mixed with the new one. The build rejects missing or empty JS, CSS, or third-party notices. The archive check verifies that the wheel and source distribution contain the same compiled assets. Python builds use the prebuilt assets and never download frontend dependencies.
+
+The release-check workflow runs on Linux and Windows, builds the wheel from the source distribution, and runs tests against that wheel outside the checkout. Before uploading, also render `embedgl.demo.make_demo()` in a real JupyterLab notebook and check 2D/3D views, picking, image previews, and selection. Automated Python checks do not verify browser rendering or performance.
+
+### Publish From GitHub
+
+Publishing a non-prerelease GitHub release runs the release-check workflow against the tagged commit. Both Linux and Windows must pass before a separate job uploads the validated Linux-built wheel and source distribution to PyPI. Pushes, pull requests, manual workflow runs, tag pushes alone, draft releases, and releases marked as prereleases do not publish to PyPI. Authentication uses PyPI Trusted Publishing (OIDC); no PyPI API token or GitHub secret is needed.
+
+One-time setup (repository `M-Anwar/embedgl`):
+
+1. In GitHub, open **Settings > Environments > New environment** and create `pypi`. Under its deployment branch/tag rules, select **Selected branches and tags** and add a **tag** rule matching `v*`. Optionally add required reviewers if your repository plan supports them; each upload will then wait for approval.
+2. Log in to PyPI with two-factor authentication enabled. For an existing `embedgl` project you own, open **Manage > Publishing > Add a new publisher**. For a first upload, use [PyPI's pending publisher form](https://pypi.org/manage/account/publishing/) and set the project name to `embedgl`. A pending publisher does not reserve a name; if someone else owns it, you need ownership or a different package name.
+3. Choose GitHub and enter these exact values: owner `M-Anwar`, repository `embedgl`, workflow filename `release-check.yml` (not its path or display name), and environment `pypi`.
+4. Commit and push the workflow and release changes. Keep the workflow on the default branch and on any branch you plan to release. Ensure GitHub Actions is enabled for the repository.
+
+For each release:
+
+1. Set a new, unused `[project].version` in `pyproject.toml`, rebuild and commit frontend assets if they changed, and push the release-ready commit to your chosen branch. Run the release checks and notebook smoke test above.
+2. In GitHub, open **Releases > Draft a new release**. Under **Choose a tag**, enter `v` followed by the exact project version, such as `v1.0` for version `1.0`. Create the new tag on publish and select your release branch in **Target**. When selecting an existing tag, its commit is used regardless of the current branch tip.
+3. Add a title and release notes, leave **Set as a pre-release** unchecked, and click **Publish release**. The workflow rejects tags that do not exactly match the version in the tagged commit; it does not change the version automatically.
+4. Follow **Actions > Release checks**. Approve the `pypi` deployment if required, then verify the new version on [PyPI](https://pypi.org/project/embedgl/).
+
+PyPI does not allow overwriting a published version or reusing deleted distribution filenames. For a corrected release, increment the version and create a new tag/release; do not move an old release tag. A failed run before uploading can be rerun after fixing external setup, but an upload that already succeeded must not be repeated. The workflow deliberately does not ignore existing files.
+
+Manual publishing remains available with `uv run python -m twine upload dist/*` after local validation. Authenticate through your usual secure PyPI workflow; never commit credentials.
+
+## Data Flow and Limitations
+
+The ready view requests coordinates in paced chunks of up to 65,536 points. Geometry is float32 positions plus uint32 cluster codes; row order is implicit. Each requested dimension mode is cached per browser model. All large buffers use custom messages, not synced traits or saved notebook state. Filtering sends only uint32 match indices; selection uses the same compact representation. Images are fetched at most four at a time and held in a 32 MiB browser LRU cache; a single image is limited to 20 MiB.
+
+Three.js renders a buffer-based point cloud. A per-view Web Worker projects matched points and builds a KDBush index after camera motion settles. Hover and rectangle picking are briefly suspended while that index rebuilds. Multiple displays of the same widget share query/selection/data state but have independent cameras. Close/dispose outputs to release their GPU/worker resources.
+
+Operation requires a live, responsive notebook kernel. Saved output is not an offline data export. Long-running notebook computations delay query/image responses; a 30-second timeout exposes a reconnect action. Search/filter evaluation runs synchronously in the kernel in this first version. Browser geometry, per-view GPU buffers, worker indexing, and match masks consume additional memory beyond the Polars frame.
+
+The design targets 100,000–1 million points, but capacity and frame rate depend on hardware and data. Python smoke tests and distribution-content checks are included. Live notebook behavior and million-point performance require separate browser testing and benchmarks.

embedgl-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+embedgl/THIRD_PARTY_LICENSES.txt,sha256=-zpp5haVlkqGqeiT1WSgQuDLiEoPxA6wCY3afEzuNAc,6707
+embedgl/__init__.py,sha256=DFw-Z0_Yud7DzAJV2Y_ppuqforDVS_FgVIIRggRehFo,121
+embedgl/demo.py,sha256=F5eGy5qGXCnctB9VoEK-pJ-AykE4o_NpZBZYfXmdh7c,3238
+embedgl/query.py,sha256=7qjx1kV7nMdBeP_zZcLOs9yjD4iMhiPYFOfdyMmtheE,4677
+embedgl/widget.py,sha256=sqtaE8b5zGiko6kZA3ZPOdx5kMMQPd2vurfprqmRkXU,18107
+embedgl/static/widget.css,sha256=AT5haOcOiBl9jE357CS4y_OswRyGA6Wgu0KXd7-ds4g,9669
+embedgl/static/widget.js,sha256=4YIpQ-w-0hgGDnxPW2qORMtBr09PkW10l1Qk4OZB5fI,1182244
+embedgl-0.0.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+embedgl-0.0.1.dist-info/METADATA,sha256=i-FciNNRv6xXXuvmyzb3Zyn-rJXRoYdn3Wyp05UUK9w,14452
+embedgl-0.0.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+embedgl-0.0.1.dist-info/top_level.txt,sha256=zB1vAMM41ijFFT4CsImL8_oPculWfdODfi3hmnlU8rE,8
+embedgl-0.0.1.dist-info/RECORD,,

embedgl-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+