anywidget-vector 0.2.4__tar.gz → 0.2.6__tar.gz

{anywidget_vector-0.2.4 → anywidget_vector-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anywidget-vector
-Version: 0.2.4
+Version: 0.2.6
 Summary: Interactive 3D vector visualization with query UI for vector databases
 Project-URL: Homepage, https://grafeo.dev/
 Project-URL: Repository, https://github.com/GrafeoDB/anywidget-vector
@@ -48,6 +48,9 @@ Provides-Extra: pandas
 Requires-Dist: pandas>=2.0; extra == 'pandas'
 Provides-Extra: pinecone
 Requires-Dist: pinecone-client>=3.0; extra == 'pinecone'
+Provides-Extra: projection
+Requires-Dist: scikit-learn>=1.3; extra == 'projection'
+Requires-Dist: umap-learn>=0.5; extra == 'projection'
 Provides-Extra: qdrant
 Requires-Dist: qdrant-client>=1.0; extra == 'qdrant'
 Provides-Extra: weaviate
@@ -60,6 +63,8 @@ Interactive 3D vector visualization for Python notebooks.
 
 Works with Marimo, Jupyter, VS Code, Colab, anywhere [anywidget](https://anywidget.dev/) runs.
 
+![anywidget-vector demo](assets/demo.png)
+
 ## Features
 
 - **Universal**: One widget, every notebook environment

{anywidget_vector-0.2.4 → anywidget_vector-0.2.6}/README.md

@@ -4,6 +4,8 @@ Interactive 3D vector visualization for Python notebooks.
 
 Works with Marimo, Jupyter, VS Code, Colab, anywhere [anywidget](https://anywidget.dev/) runs.
 
+![anywidget-vector demo](assets/demo.png)
+
 ## Features
 
 - **Universal**: One widget, every notebook environment

anywidget_vector-0.2.6/examples/test_add_numpy.py

@@ -0,0 +1,98 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "anywidget-vector==0.2.5",
+#     "marimo",
+#     "numpy==2.4.3",
+# ]
+# ///
+
+import marimo
+
+__generated_with = "0.18.4"
+app = marimo.App(width="medium")
+
+
+@app.cell
+def _():
+    import marimo as mo
+
+    return (mo,)
+
+
+@app.cell
+def _():
+    import numpy as np
+
+    from anywidget_vector import VectorSpace
+
+    return VectorSpace, np
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md("""
+    # Test: `add_numpy`
+    """)
+    return
+
+
+@app.cell
+def _(VectorSpace):
+    # Start with an empty widget
+    w = VectorSpace(
+        width=900,
+        height=500,
+        background="#0f0f1a",
+        color_field="group",
+    )
+    w
+    return (w,)
+
+
+@app.cell
+def _(mo, np, w):
+    # Add two numpy clusters
+    rng = np.random.default_rng(42)
+
+    cluster_a = rng.normal(loc=[0.3, 0.3, 0.3], scale=0.1, size=(50, 3))
+    cluster_b = rng.normal(loc=[0.7, 0.7, 0.7], scale=0.1, size=(50, 3))
+
+    w.add_numpy(
+        cluster_a,
+        labels=[f"A-{i}" for i in range(len(cluster_a))],
+        metadata={"group": ["alpha"] * len(cluster_a)},
+    ).add_numpy(
+        cluster_b,
+        labels=[f"B-{i}" for i in range(len(cluster_b))],
+        metadata={"group": ["beta"] * len(cluster_b)},
+    )
+
+    mo.md(f"Added **{len(w.points)}** points total")
+    return
+
+
+@app.cell
+def _(mo, np, w):
+    # Add a third cluster with 2D data (z defaults to 0)
+    rng2 = np.random.default_rng(99)
+    flat = rng2.normal(loc=[0.5, 0.5], scale=0.08, size=(30, 2))
+
+    w.add_numpy(flat, metadata={"group": ["flat"] * len(flat)})
+
+    mo.md(f"Now **{len(w.points)}** points (added 30 flat 2D points)")
+    return
+
+
+@app.cell
+def _(mo, w):
+    # Verify point IDs are unique
+    ids = [p["id"] for p in w.points]
+    unique = len(set(ids))
+    status = "All IDs unique" if unique == len(ids) else f"DUPLICATE IDS: {len(ids) - unique} collisions"
+    mo.md(f"Points: {len(ids)}, Unique IDs: {unique}: **{status}**")
+    return
+
+
+if __name__ == "__main__":
+    app.run()

anywidget_vector-0.2.6/examples/test_projection.py

@@ -0,0 +1,98 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "anywidget-vector",
+#     "marimo",
+#     "numpy",
+#     "scikit-learn",
+# ]
+# ///
+
+import marimo
+
+__generated_with = "0.20.0"
+app = marimo.App(width="medium")
+
+
+@app.cell
+def _():
+    import marimo as mo
+
+    return (mo,)
+
+
+@app.cell
+def _():
+    import numpy as np
+
+    from anywidget_vector import VectorSpace
+
+    return VectorSpace, np
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md("""# Interactive Projection Demo
+
+    High-dimensional data projected to 3D. Switch projections live with the dropdown.
+    """)
+    return
+
+
+@app.cell
+def _(np):
+    # Generate 50-dimensional clustered data
+    rng = np.random.default_rng(42)
+
+    def make_cluster(center, n=80, noise=0.3):
+        return rng.normal(loc=center, scale=noise, size=(n, len(center)))
+
+    n_dims = 50
+    centers = [rng.uniform(-2, 2, size=n_dims) for _ in range(5)]
+    cluster_names = ["alpha", "beta", "gamma", "delta", "epsilon"]
+
+    vectors = np.vstack([make_cluster(c) for c in centers])
+    groups = [name for name, c in zip(cluster_names, centers, strict=True) for _ in range(80)]
+    labels = [f"{g}-{i}" for i, g in enumerate(groups)]
+
+    f"Generated {len(vectors)} points in {n_dims}D across 5 clusters"
+    return vectors, groups, labels
+
+
+@app.cell
+def _(mo):
+    method = mo.ui.dropdown(
+        options=["pca", "tsne"],
+        value="pca",
+        label="Projection method",
+    )
+    method
+    return (method,)
+
+
+@app.cell
+def _(VectorSpace, groups, labels, method, vectors):
+    w = VectorSpace(
+        width=900,
+        height=500,
+        background="#0f0f1a",
+        color_field="group",
+    )
+    w.add_numpy(
+        vectors,
+        labels=labels,
+        metadata={"group": groups},
+    )
+    w.project(method.value)
+    w
+    return (w,)
+
+
+@app.cell
+def _(mo, method, w):
+    mo.md(f"Showing **{method.value.upper()}** projection of {len(w.points)} points")
+    return
+
+
+if __name__ == "__main__":
+    app.run()

{anywidget_vector-0.2.4 → anywidget_vector-0.2.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "anywidget-vector"
-version = "0.2.4"
+version = "0.2.6"
 description = "Interactive 3D vector visualization with query UI for vector databases"
 readme = "README.md"
 license = "Apache-2.0"
@@ -40,6 +40,7 @@ pinecone = ["pinecone-client>=3.0"]
 weaviate = ["weaviate-client>=4.0"]
 lancedb = ["lancedb>=0.1"]
 grafeo = ["grafeo>=0.5"]
+projection = ["scikit-learn>=1.3", "umap-learn>=0.5"]
 embed = []  # Marker extra — WASM loads from CDN on demand
 demo = []  # Marker extra — enables demo mode with pre-populated dataset
 all = [

{anywidget_vector-0.2.4 → anywidget_vector-0.2.6}/src/anywidget_vector/__init__.py

@@ -3,4 +3,4 @@
 from anywidget_vector.widget import VectorSpace
 
 __all__ = ["VectorSpace"]
-__version__ = "0.2.3"
+__version__ = "0.2.5"

{anywidget_vector-0.2.4 → anywidget_vector-0.2.6}/src/anywidget_vector/ui/__init__.py

@@ -123,6 +123,7 @@ function render({{ model, el }}) {{
   const wrapper = document.createElement("div");
   wrapper.className = "avs-wrapper";
   wrapper.style.width = model.get("width") + "px";
+  wrapper.style.height = model.get("height") + "px";
   el.appendChild(wrapper);
 
   let sidebar = null;
@@ -154,7 +155,6 @@ function render({{ model, el }}) {{
 
   const main = document.createElement("div");
   main.className = "avs-main";
-  main.style.height = model.get("height") + "px";
   wrapper.appendChild(main);
 
   // Sidebar (left, explorer panel)

{anywidget_vector-0.2.4 → anywidget_vector-0.2.6}/src/anywidget_vector/ui/canvas.js

@@ -50,15 +50,19 @@ export function createCanvas(model, container, callbacks) {
     scene = new THREE.Scene();
     scene.background = new THREE.Color(model.get("background"));
 
+    // Use actual container dimensions when available, fall back to model values
+    const initW = container.clientWidth || model.get("width");
+    const initH = container.clientHeight || model.get("height");
+
     // Camera
-    const aspect = model.get("width") / model.get("height");
+    const aspect = initW / initH;
     camera = new THREE.PerspectiveCamera(60, aspect, 0.01, 1000);
     const camPos = model.get("camera_position") || [2, 2, 2];
     camera.position.set(camPos[0], camPos[1], camPos[2]);
 
     // Renderer
     renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
-    renderer.setSize(model.get("width"), model.get("height"));
+    renderer.setSize(initW, initH);
     renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
     container.appendChild(renderer.domElement);
 
@@ -100,14 +104,32 @@ export function createCanvas(model, container, callbacks) {
     setupRaycaster();
     setupTooltip();
     setupZoomControls();
-    setupModeControls();
     setupBoxSelection();
+    setupKeyboardShortcuts();
     createPoints();
     createConnections();
     fitToView();
     bindModelEvents();
   }
 
+  function setupKeyboardShortcuts() {
+    container.tabIndex = 0;
+    container.style.outline = "none";
+    container.addEventListener("keydown", (e) => {
+      const tag = e.target.tagName;
+      if (tag === "INPUT" || tag === "SELECT" || tag === "TEXTAREA") return;
+
+      if (e.key === "f" || e.key === "F") {
+        e.preventDefault();
+        fitToView();
+      } else if (e.key === "Escape") {
+        model.set("selected_points", []);
+        model.set("hovered_point", null);
+        model.save_changes();
+      }
+    });
+  }
+
   function setupAxesAndGrid() {
     while (axesGroup.children.length > 0) axesGroup.remove(axesGroup.children[0]);
     if (gridHelper) { scene.remove(gridHelper); gridHelper = null; }
@@ -471,27 +493,19 @@ export function createCanvas(model, container, callbacks) {
     zoomFitBtn.title = "Fit to view";
     zoomFitBtn.addEventListener("click", fitToView);
 
-    zoomControls.appendChild(zoomInBtn);
-    zoomControls.appendChild(zoomOutBtn);
-    zoomControls.appendChild(zoomFitBtn);
-    container.appendChild(zoomControls);
-  }
-
-  function setupModeControls() {
+    // Mode switcher (above zoom buttons, inside same column)
     const modeGroup = document.createElement("div");
     modeGroup.className = "avs-mode-group";
 
     const clickBtn = document.createElement("button");
-    clickBtn.className = "avs-mode-btn avs-mode-active";
+    clickBtn.className = "avs-zoom-btn avs-mode-btn avs-mode-active";
     clickBtn.innerHTML = ICONS.cursor;
     clickBtn.title = "Click / multi-select mode";
-    clickBtn.dataset.mode = "click";
 
     const boxBtn = document.createElement("button");
-    boxBtn.className = "avs-mode-btn";
+    boxBtn.className = "avs-zoom-btn avs-mode-btn";
     boxBtn.innerHTML = ICONS.boxSelect;
     boxBtn.title = "Box select mode";
-    boxBtn.dataset.mode = "box";
 
     function setActiveMode(mode) {
       currentMode = mode;
@@ -513,15 +527,20 @@ export function createCanvas(model, container, callbacks) {
     clickBtn.addEventListener("click", () => setActiveMode("click"));
     boxBtn.addEventListener("click", () => setActiveMode("box"));
 
-    modeGroup.appendChild(clickBtn);
-    modeGroup.appendChild(boxBtn);
-    container.appendChild(modeGroup);
-
     // Sync with model changes from Python side
     model.on("change:selection_mode", () => {
       const mode = model.get("selection_mode") || "click";
       if (mode !== currentMode) setActiveMode(mode);
     });
+
+    modeGroup.appendChild(clickBtn);
+    modeGroup.appendChild(boxBtn);
+
+    zoomControls.appendChild(modeGroup);
+    zoomControls.appendChild(zoomInBtn);
+    zoomControls.appendChild(zoomOutBtn);
+    zoomControls.appendChild(zoomFitBtn);
+    container.appendChild(zoomControls);
   }
 
   function setupBoxSelection() {

{anywidget_vector-0.2.4 → anywidget_vector-0.2.6}/src/anywidget_vector/ui/styles.css

@@ -47,7 +47,7 @@
   display: flex;
   flex-direction: column;
   gap: 2px;
-  z-index: 10;
+  z-index: 25;
 }
 
 .avs-zoom-btn {
@@ -87,37 +87,11 @@
 
 /* === Mode Switcher === */
 .avs-mode-group {
-  position: absolute;
-  bottom: 12px;
-  left: 12px;
   display: flex;
   gap: 2px;
-  z-index: 10;
-}
-
-.avs-mode-btn {
-  width: 32px;
-  height: 32px;
-  border: 1px solid var(--avs-border);
-  background: var(--avs-bg);
-  color: var(--avs-text);
-  cursor: pointer;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  border-radius: 4px;
-  transition: all 0.15s;
-  padding: 0;
-}
-
-.avs-mode-btn:hover {
-  background: var(--avs-surface);
-  border-color: var(--avs-text-muted);
-}
-
-.avs-mode-btn svg {
-  width: 16px;
-  height: 16px;
+  margin-bottom: 4px;
+  border-bottom: 1px solid rgba(255,255,255,0.15);
+  padding-bottom: 6px;
 }
 
 .avs-mode-btn.avs-mode-active {
@@ -159,6 +133,14 @@
   color: var(--avs-text-muted);
 }
 
+.avs-count-badge {
+  font-size: 11px;
+  color: var(--avs-text-muted);
+  white-space: nowrap;
+  flex-shrink: 0;
+  font-variant-numeric: tabular-nums;
+}
+
 .avs-filter-count {
   font-size: 11px;
   font-weight: 600;
@@ -291,11 +273,11 @@
   width: 280px;
 }
 
-.avs-panel-left {
+.avs-panel-left.avs-open {
   border-right: 1px solid var(--avs-border);
 }
 
-.avs-panel-right {
+.avs-panel-right.avs-open {
   border-left: 1px solid var(--avs-border);
 }
 

{anywidget_vector-0.2.4 → anywidget_vector-0.2.6}/src/anywidget_vector/ui/toolbar.js

@@ -39,6 +39,17 @@ export function createToolbar(model, callbacks) {
   filterCount.style.display = "none";
   toolbar.appendChild(filterCount);
 
+  // Point count badge
+  const countBadge = document.createElement("span");
+  countBadge.className = "avs-count-badge";
+  function updatePointCount() {
+    const pts = model.get("points") || [];
+    countBadge.textContent = `${pts.length} points`;
+  }
+  updatePointCount();
+  model.on("change:points", updatePointCount);
+  toolbar.appendChild(countBadge);
+
   // Run button
   const runBtn = document.createElement("button");
   runBtn.className = "avs-btn avs-btn-primary";

{anywidget_vector-0.2.4 → anywidget_vector-0.2.6}/src/anywidget_vector/widget.py

@@ -109,6 +109,7 @@ class VectorSpace(anywidget.AnyWidget):
     def __init__(self, points: list[dict[str, Any]] | None = None, **kwargs: Any) -> None:
         super().__init__(points=points or [], **kwargs)
         self._backend_client: Any = None
+        self._vectors: Any = None  # High-dim vectors for projection (numpy array, not synced to JS)
         self.observe(self._on_execute_query, names=["_execute_query"])
 
     # === Backend Configuration ===
@@ -209,6 +210,158 @@ class VectorSpace(anywidget.AnyWidget):
         self.observe(_handler, names=["selected_points"])
         return callback
 
+    # === Add Points ===
+
+    def add_points(self, data: list[dict[str, Any]]) -> VectorSpace:
+        """Append point dicts to the existing points.
+
+        Args:
+            data: List of point dicts with at least x, y keys.
+
+        Returns:
+            Self for chaining.
+        """
+        self.points = [*self.points, *_normalize_points(data)]
+        return self
+
+    def add_numpy(
+        self,
+        positions: Any,
+        *,
+        ids: list[str] | None = None,
+        labels: list[str] | None = None,
+        metadata: dict[str, list[Any]] | None = None,
+    ) -> VectorSpace:
+        """Append points from a NumPy array.
+
+        For arrays with D > 3 columns, the full vectors are stored internally
+        and PCA is used for the initial 3D coordinates. Call ``project()`` to
+        switch projection methods interactively.
+
+        Args:
+            positions: Array of shape (N, 2), (N, 3), or (N, D) for high-dim data.
+            ids: Optional list of point IDs.
+            labels: Optional list of labels.
+            metadata: Optional dict mapping field names to per-point value lists.
+
+        Returns:
+            Self for chaining.
+        """
+        import numpy as np
+
+        arr = np.asarray(positions, dtype=np.float64)
+        n_samples, n_dims = arr.shape
+
+        # High-dimensional: store vectors and project to 3D
+        if n_dims > 3:
+            if self._vectors is not None:
+                self._vectors = np.vstack([self._vectors, arr])
+            else:
+                self._vectors = arr
+            coords = _pca(arr, n_components=3)
+        else:
+            coords = arr
+
+        offset = len(self.points)
+        new_points = []
+        for i in range(n_samples):
+            point: dict[str, Any] = {
+                "id": ids[i] if ids else f"point_{offset + i}",
+                "x": float(coords[i, 0]),
+                "y": float(coords[i, 1]),
+                "z": float(coords[i, 2]) if coords.shape[1] > 2 else 0.0,
+            }
+            if labels:
+                point["label"] = labels[i]
+            if metadata:
+                for key, values in metadata.items():
+                    point[key] = values[i]
+            new_points.append(point)
+        self.points = [*self.points, *new_points]
+        return self
+
+    # === Projection ===
+
+    def set_vectors(self, vectors: Any) -> VectorSpace:
+        """Store high-dimensional vectors for use with ``project()``.
+
+        Must have the same number of rows as ``self.points``.
+
+        Args:
+            vectors: Array-like of shape (N, D).
+
+        Returns:
+            Self for chaining.
+        """
+        import numpy as np
+
+        self._vectors = np.asarray(vectors, dtype=np.float64)
+        return self
+
+    def project(self, method: str = "pca", *, n_components: int = 3, **kwargs: Any) -> VectorSpace:
+        """Reproject point coordinates using dimensionality reduction.
+
+        Reads vectors from ``set_vectors()`` / ``add_numpy()`` (for D > 3), or
+        falls back to extracting the ``vector`` field from each point dict.
+
+        Supported methods: ``pca``, ``tsne``, ``umap``.
+
+        Args:
+            method: Projection algorithm name.
+            n_components: Target dimensions (2 or 3).
+            **kwargs: Passed to the underlying algorithm.
+
+        Returns:
+            Self for chaining.
+        """
+        vectors = self._resolve_vectors()
+        n_components = min(n_components, vectors.shape[1])
+
+        if method == "pca":
+            coords = _pca(vectors, n_components=n_components)
+        elif method == "tsne":
+            coords = _tsne(vectors, n_components=n_components, **kwargs)
+        elif method == "umap":
+            coords = _umap(vectors, n_components=n_components, **kwargs)
+        else:
+            raise ValueError(f"Unknown projection method: {method!r}. Use 'pca', 'tsne', or 'umap'.")
+
+        # Normalize to roughly [-1, 1] so the scene stays well-framed
+        for col in range(coords.shape[1]):
+            c = coords[:, col]
+            lo, hi = c.min(), c.max()
+            if hi - lo > 0:
+                coords[:, col] = 2 * (c - lo) / (hi - lo) - 1
+
+        points = [dict(p) for p in self.points]
+        for i, p in enumerate(points):
+            p["x"] = float(coords[i, 0])
+            p["y"] = float(coords[i, 1])
+            p["z"] = float(coords[i, 2]) if n_components >= 3 else 0.0
+        self.points = points
+        return self
+
+    def _resolve_vectors(self) -> Any:
+        """Get the vector matrix for projection."""
+        import numpy as np
+
+        if self._vectors is not None:
+            if len(self._vectors) != len(self.points):
+                raise ValueError(
+                    f"Stored vectors ({len(self._vectors)}) don't match point count ({len(self.points)}). "
+                    "Call set_vectors() again after modifying points."
+                )
+            return self._vectors
+
+        # Fall back to point["vector"] fields
+        vecs = [p.get("vector") for p in self.points]
+        if all(v is not None for v in vecs):
+            return np.array(vecs, dtype=np.float64)
+
+        raise ValueError(
+            "No vectors available. Use set_vectors(), add_numpy() with D > 3, or ensure points have a 'vector' field."
+        )
+
     # === Factory Methods ===
 
     @classmethod
@@ -923,3 +1076,36 @@ def _to_list(obj: Any) -> list[Any]:
     if hasattr(obj, "tolist"):
         return obj.tolist()
     return list(obj)
+
+
+# === Projection Helpers ===
+
+
+def _pca(vectors: Any, n_components: int = 3) -> Any:
+    """PCA via SVD (numpy only, no sklearn needed)."""
+    import numpy as np
+
+    x = np.asarray(vectors, dtype=np.float64)
+    x_centered = x - x.mean(axis=0)
+    _u, _s, vt = np.linalg.svd(x_centered, full_matrices=False)
+    return x_centered @ vt[:n_components].T
+
+
+def _tsne(vectors: Any, n_components: int = 3, **kwargs: Any) -> Any:
+    """t-SNE projection (requires scikit-learn)."""
+    try:
+        from sklearn.manifold import TSNE
+    except ImportError:
+        raise ImportError("t-SNE requires scikit-learn: uv add scikit-learn") from None
+    kwargs.setdefault("perplexity", min(30.0, len(vectors) - 1))
+    return TSNE(n_components=n_components, **kwargs).fit_transform(vectors)
+
+
+def _umap(vectors: Any, n_components: int = 3, **kwargs: Any) -> Any:
+    """UMAP projection (requires umap-learn)."""
+    try:
+        from umap import UMAP
+    except ImportError:
+        raise ImportError("UMAP requires umap-learn: uv add umap-learn") from None
+    kwargs.setdefault("n_neighbors", min(15, len(vectors) - 1))
+    return UMAP(n_components=n_components, **kwargs).fit_transform(vectors)