anywidget-vector 0.2.0__tar.gz → 0.2.1__tar.gz

anywidget_vector-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install ruff
+
+      - name: Run ruff check
+        run: ruff check .
+
+      - name: Run ruff format check
+        run: ruff format --check .
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: |
+          pip install twine
+          twine check dist/*

anywidget_vector-0.2.1/.github/workflows/pypi.yml

@@ -0,0 +1,77 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Publish target'
+        required: true
+        default: 'testpypi'
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{anywidget_vector-0.2.0 → anywidget_vector-0.2.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: anywidget-vector
-Version: 0.2.0
-Summary: Interactive vector visualization for Python notebooks using anywidget
+Version: 0.2.1
+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
 Author-email: "S.T. Grond" <widget@grafeo.dev>
@@ -30,7 +30,7 @@ Provides-Extra: dev
 Requires-Dist: marimo>=0.19.7; extra == 'dev'
 Requires-Dist: prek>=0.3.1; extra == 'dev'
 Requires-Dist: pytest>=9.0.2; extra == 'dev'
-Requires-Dist: ruff>=0.14.14; extra == 'dev'
+Requires-Dist: ruff>=0.15.0; extra == 'dev'
 Requires-Dist: ty>=0.0.14; extra == 'dev'
 Provides-Extra: lancedb
 Requires-Dist: lancedb>=0.1; extra == 'lancedb'

anywidget_vector-0.2.1/examples/demo.py

@@ -0,0 +1,274 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "anywidget-vector==0.2.0",
+#     "marimo",
+# ]
+# ///
+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 random
+
+    from anywidget_vector import VectorSpace
+
+    return VectorSpace, random
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md("""
+    # anywidget-vector Demo
+
+    Interactive 3D vector visualization with distance metrics and query UI.
+    """)
+    return
+
+
+@app.cell
+def _(VectorSpace, random):
+    # Generate sample clustered data
+    random.seed(42)
+
+    def generate_cluster(center, n=20, spread=0.15):
+        points = []
+        for i in range(n):
+            points.append(
+                {
+                    "x": center[0] + random.gauss(0, spread),
+                    "y": center[1] + random.gauss(0, spread),
+                    "z": center[2] + random.gauss(0, spread),
+                    "cluster": center[3],
+                }
+            )
+        return points
+
+    # Create 4 clusters
+    clusters = [
+        (0.3, 0.3, 0.3, "A"),
+        (0.7, 0.3, 0.7, "B"),
+        (0.3, 0.7, 0.7, "C"),
+        (0.7, 0.7, 0.3, "D"),
+    ]
+
+    points = []
+    for center in clusters:
+        points.extend(generate_cluster(center))
+
+    # Add IDs and labels
+    for i, p in enumerate(points):
+        p["id"] = f"point_{i}"
+        p["label"] = f"Point {i} ({p['cluster']})"
+        p["importance"] = random.random()
+
+    # Create widget with color by cluster
+    widget = VectorSpace(
+        points=points,
+        color_field="cluster",
+        size_field="importance",
+        size_range=[0.02, 0.06],
+        width=800,
+        height=500,
+        background="#0f0f1a",
+    )
+    widget
+    return points, widget
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md("""
+    ## Distance Features
+
+    Click on a point above, then run the cells below to explore distance metrics.
+    """)
+    return
+
+
+@app.cell
+def _(widget):
+    # Get the currently selected point
+    selected = widget.selected_points
+    selected_id = selected[0] if selected else "point_0"
+    f"Selected point: {selected_id}"
+    return (selected_id,)
+
+
+@app.cell
+def _(selected_id, widget):
+    # Find 5 nearest neighbors using Euclidean distance
+    neighbors_euclidean = widget.find_neighbors(selected_id, k=5, metric="euclidean")
+    neighbors_euclidean
+    return
+
+
+@app.cell
+def _(selected_id, widget):
+    # Find 5 nearest neighbors using Cosine distance
+    neighbors_cosine = widget.find_neighbors(selected_id, k=5, metric="cosine")
+    neighbors_cosine
+    return
+
+
+@app.cell
+def _(VectorSpace, points):
+    # Create a second widget showing neighbor connections
+    widget2 = VectorSpace(
+        points=points,
+        color_field="cluster",
+        width=800,
+        height=500,
+        background="#0f0f1a",
+        # Enable k-nearest neighbor connections
+        show_connections=True,
+        k_neighbors=3,
+        distance_metric="euclidean",
+        connection_color="#44ff88",
+        connection_opacity=0.4,
+    )
+    widget2
+    return
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md("""
+    ## Color by Distance
+
+    The widget below colors points by distance from a reference point.
+    """)
+    return
+
+
+@app.cell
+def _(VectorSpace, points):
+    # Create widget and color by distance from first point
+    widget3 = VectorSpace(
+        points=[dict(p) for p in points],  # Copy points
+        width=800,
+        height=500,
+        background="#0f0f1a",
+        color_scale="plasma",
+    )
+    widget3.color_by_distance("point_0", metric="euclidean")
+    widget3.show_neighbors("point_0", k=5)
+    widget3
+    return
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md("""
+    ## Different Shapes
+
+    Using shapes to encode an additional dimension.
+    """)
+    return
+
+
+@app.cell
+def _(VectorSpace, points):
+    # Create widget with shape mapping
+    widget4 = VectorSpace(
+        points=points,
+        color_field="cluster",
+        shape_field="cluster",
+        shape_map={
+            "A": "sphere",
+            "B": "cube",
+            "C": "cone",
+            "D": "octahedron",
+        },
+        size_range=[0.04, 0.04],  # Fixed size
+        width=800,
+        height=500,
+        background="#0f0f1a",
+    )
+    widget4
+    return
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md("""
+    ## Query UI
+
+    The widget below shows the query interface for vector database backends.
+    Enable `show_query_input=True` to show the toolbar.
+
+    **Supported backends:**
+    - Browser-side (REST API): Qdrant, Pinecone, Weaviate
+    - Python-side: Chroma, LanceDB, Grafeo
+
+    **Query types:**
+    - Text Search (requires embedding API)
+    - Find Similar (by vector ID)
+    - Raw Vector ([0.1, 0.2, ...])
+    - Filter (JSON filter expressions)
+    """)
+    return
+
+
+@app.cell
+def _(VectorSpace, points):
+    # Create widget with query UI enabled
+    widget5 = VectorSpace(
+        points=points,
+        color_field="cluster",
+        width=800,
+        height=500,
+        background="#0f0f1a",
+        # Enable query UI
+        show_query_input=True,
+        show_settings=True,
+        # Default to Qdrant backend
+        backend="qdrant",
+    )
+    widget5
+    return
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md("""
+    ### Python-side Backend Example
+
+    For Python-side backends like Chroma, configure the client directly:
+
+    ```python
+    import chromadb
+
+    client = chromadb.Client()
+    collection = client.get_or_create_collection("my_vectors")
+
+    widget = VectorSpace(
+        show_query_input=True,
+        show_settings=True,
+    )
+    widget.set_backend("chroma", collection)
+
+    # Optional: set custom embedding function for text search
+    def my_embed(text):
+        # Your embedding logic here
+        return [0.1, 0.2, 0.3, ...]
+
+    widget.set_embedding(my_embed)
+    ```
+    """)
+    return
+
+
+if __name__ == "__main__":
+    app.run()

{anywidget_vector-0.2.0 → anywidget_vector-0.2.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "anywidget-vector"
-version = "0.2.0"
-description = "Interactive vector visualization for Python notebooks using anywidget"
+version = "0.2.1"
+description = "Interactive 3D vector visualization with query UI for vector databases"
 readme = "README.md"
 license = { text = "Apache-2.0" }
 requires-python = ">=3.12"
@@ -28,7 +28,7 @@ dependencies = [
 dev = [
     "prek>=0.3.1",
     "pytest>=9.0.2",
-    "ruff>=0.14.14",
+    "ruff>=0.15.0",
     "ty>=0.0.14",
     "marimo>=0.19.7",
 ]

{anywidget_vector-0.2.0 → anywidget_vector-0.2.1}/src/anywidget_vector/__init__.py

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

anywidget_vector-0.2.1/src/anywidget_vector/backends/__init__.py

@@ -0,0 +1,103 @@
+"""Vector database backend adapters.
+
+Each backend has its own query format matching its native API:
+- Qdrant: JSON with vector, filter, limit
+- Pinecone: JSON with vector, filter, topK
+- Weaviate: GraphQL
+- Chroma: Python dict (query_embeddings, where, n_results)
+- LanceDB: SQL-like expressions
+- Grafeo: Grafeo query format
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class VectorBackend(Protocol):
+    """Protocol for vector database backends."""
+
+    name: str
+    side: str  # "browser" or "python"
+    query_language: str  # e.g., "json", "graphql", "sql", "python"
+
+    def execute(self, query: str, config: dict[str, Any]) -> list[dict[str, Any]]:
+        """Execute a query and return points."""
+        ...
+
+
+# Backend registry with metadata
+BACKENDS: dict[str, dict[str, Any]] = {
+    "qdrant": {
+        "name": "Qdrant",
+        "side": "browser",
+        "query_language": "json",
+        "placeholder": '{"vector": [...], "limit": 10}',
+        "help": "JSON: vector, filter, limit, recommend, ids",
+    },
+    "pinecone": {
+        "name": "Pinecone",
+        "side": "browser",
+        "query_language": "json",
+        "placeholder": '{"vector": [...], "topK": 10}',
+        "help": "JSON: vector, filter, topK, namespace",
+    },
+    "weaviate": {
+        "name": "Weaviate",
+        "side": "browser",
+        "query_language": "graphql",
+        "placeholder": "{ Get { Class(limit: 10) { ... } } }",
+        "help": "GraphQL with nearVector, nearText, where",
+    },
+    "chroma": {
+        "name": "Chroma",
+        "side": "python",
+        "query_language": "dict",
+        "placeholder": '{"query_embeddings": [...], "n_results": 10}',
+        "help": "Dict: query_embeddings, where, n_results",
+    },
+    "lancedb": {
+        "name": "LanceDB",
+        "side": "python",
+        "query_language": "sql",
+        "placeholder": "category = 'tech' AND year > 2020",
+        "help": "SQL WHERE clause for filtering",
+    },
+    "grafeo": {
+        "name": "Grafeo",
+        "side": "python",
+        "query_language": "grafeo",
+        "placeholder": "MATCH (n:Vector) RETURN n LIMIT 10",
+        "help": "Grafeo query language",
+    },
+}
+
+
+def get_backend_info(name: str) -> dict[str, Any] | None:
+    """Get backend configuration by name."""
+    return BACKENDS.get(name)
+
+
+def is_browser_backend(name: str) -> bool:
+    """Check if backend runs in browser."""
+    info = BACKENDS.get(name)
+    return info is not None and info.get("side") == "browser"
+
+
+def is_python_backend(name: str) -> bool:
+    """Check if backend runs in Python."""
+    info = BACKENDS.get(name)
+    return info is not None and info.get("side") == "python"
+
+
+def get_query_placeholder(name: str) -> str:
+    """Get example query placeholder for backend."""
+    info = BACKENDS.get(name)
+    return info.get("placeholder", "") if info else ""
+
+
+def get_query_help(name: str) -> str:
+    """Get query help text for backend."""
+    info = BACKENDS.get(name)
+    return info.get("help", "") if info else ""

anywidget_vector-0.2.1/src/anywidget_vector/backends/chroma/__init__.py

@@ -0,0 +1,27 @@
+"""Chroma backend adapter.
+
+Query Format (dict):
+    # Query by embeddings
+    {"query_embeddings": [[0.1, 0.2, ...]], "n_results": 10}
+
+    # With where filter
+    {
+        "query_embeddings": [[0.1, 0.2, ...]],
+        "where": {"category": "tech"},
+        "n_results": 10
+    }
+
+    # Get by IDs
+    {"ids": ["id1", "id2"]}
+
+    # Get with filter only
+    {"where": {"category": "tech"}, "limit": 100}
+
+Where operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin
+Combined: $and, $or
+"""
+
+from anywidget_vector.backends.chroma.client import execute_query
+from anywidget_vector.backends.chroma.converter import build_where, to_points
+
+__all__ = ["to_points", "build_where", "execute_query"]

anywidget_vector-0.2.1/src/anywidget_vector/backends/chroma/client.py

@@ -0,0 +1,60 @@
+"""Chroma Python client."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from anywidget_vector.backends.chroma.converter import to_points
+
+
+def execute_query(
+    collection: Any,
+    query: str | dict[str, Any],
+) -> list[dict[str, Any]]:
+    """Execute query against Chroma collection.
+
+    Args:
+        collection: Chroma collection object
+        query: Query dict or JSON string
+
+    Returns:
+        List of points
+    """
+    if isinstance(query, str):
+        query = json.loads(query)
+
+    # Get by IDs
+    if "ids" in query:
+        response = collection.get(
+            ids=query["ids"],
+            include=["embeddings", "metadatas", "documents"],
+        )
+        return to_points(response)
+
+    # Query by embeddings
+    if "query_embeddings" in query:
+        response = collection.query(
+            query_embeddings=query["query_embeddings"],
+            n_results=query.get("n_results", 10),
+            where=query.get("where"),
+            where_document=query.get("where_document"),
+            include=["embeddings", "metadatas", "documents", "distances"],
+        )
+        return to_points(response)
+
+    # Get with filter
+    if "where" in query:
+        response = collection.get(
+            where=query["where"],
+            limit=query.get("limit", 100),
+            include=["embeddings", "metadatas", "documents"],
+        )
+        return to_points(response)
+
+    # Get all (with limit)
+    response = collection.get(
+        limit=query.get("limit", 100),
+        include=["embeddings", "metadatas", "documents"],
+    )
+    return to_points(response)