anywidget-vector 0.1.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.1.0 → anywidget_vector-0.2.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: anywidget-vector
-Version: 0.1.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'
@@ -264,6 +264,73 @@ widget = VectorSpace(
 )
 ```
 
+## Distance Metrics
+
+Compute distances and visualize similarity relationships between points.
+
+### Supported Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `euclidean` | Straight-line distance (L2 norm) |
+| `cosine` | Angle-based distance (1 - cosine similarity) |
+| `manhattan` | Sum of absolute differences (L1 norm) |
+| `dot_product` | Negative dot product (higher = closer) |
+
+### Color by Distance
+
+```python
+# Color points by distance from a reference
+widget.color_by_distance("point_a")
+widget.color_by_distance("point_a", metric="cosine")
+```
+
+### Find Neighbors
+
+```python
+# Find k nearest neighbors
+neighbors = widget.find_neighbors("point_a", k=5)
+# Returns: [("point_b", 0.1), ("point_c", 0.2), ...]
+
+# Find neighbors within distance threshold
+neighbors = widget.find_neighbors("point_a", threshold=0.5)
+```
+
+### Show Connections
+
+```python
+# Draw lines to k-nearest neighbors
+widget.show_neighbors("point_a", k=5)
+
+# Draw lines to all points within threshold
+widget.show_neighbors("point_a", threshold=0.3)
+
+# Manual connection settings
+widget = VectorSpace(
+    points=data,
+    show_connections=True,
+    k_neighbors=3,
+    distance_metric="cosine",
+    connection_color="#00ff00",
+    connection_opacity=0.5,
+)
+```
+
+### Compute Distances
+
+```python
+# Get distances from reference to all points
+distances = widget.compute_distances("point_a")
+# Returns: {"point_b": 0.1, "point_c": 0.5, ...}
+
+# Use high-dimensional vectors (not just x,y,z)
+distances = widget.compute_distances(
+    "point_a",
+    metric="cosine",
+    vector_field="embedding"  # Use full embedding vector
+)
+```
+
 ## Export
 
 ```python

{anywidget_vector-0.1.0 → anywidget_vector-0.2.1}/README.md

@@ -216,6 +216,73 @@ widget = VectorSpace(
 )
 ```
 
+## Distance Metrics
+
+Compute distances and visualize similarity relationships between points.
+
+### Supported Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `euclidean` | Straight-line distance (L2 norm) |
+| `cosine` | Angle-based distance (1 - cosine similarity) |
+| `manhattan` | Sum of absolute differences (L1 norm) |
+| `dot_product` | Negative dot product (higher = closer) |
+
+### Color by Distance
+
+```python
+# Color points by distance from a reference
+widget.color_by_distance("point_a")
+widget.color_by_distance("point_a", metric="cosine")
+```
+
+### Find Neighbors
+
+```python
+# Find k nearest neighbors
+neighbors = widget.find_neighbors("point_a", k=5)
+# Returns: [("point_b", 0.1), ("point_c", 0.2), ...]
+
+# Find neighbors within distance threshold
+neighbors = widget.find_neighbors("point_a", threshold=0.5)
+```
+
+### Show Connections
+
+```python
+# Draw lines to k-nearest neighbors
+widget.show_neighbors("point_a", k=5)
+
+# Draw lines to all points within threshold
+widget.show_neighbors("point_a", threshold=0.3)
+
+# Manual connection settings
+widget = VectorSpace(
+    points=data,
+    show_connections=True,
+    k_neighbors=3,
+    distance_metric="cosine",
+    connection_color="#00ff00",
+    connection_opacity=0.5,
+)
+```
+
+### Compute Distances
+
+```python
+# Get distances from reference to all points
+distances = widget.compute_distances("point_a")
+# Returns: {"point_b": 0.1, "point_c": 0.5, ...}
+
+# Use high-dimensional vectors (not just x,y,z)
+distances = widget.compute_distances(
+    "point_a",
+    metric="cosine",
+    vector_field="embedding"  # Use full embedding vector
+)
+```
+
 ## Export
 
 ```python

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.1.0 → anywidget_vector-0.2.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "anywidget-vector"
-version = "0.1.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.1.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.1.0"
+__version__ = "0.2.1"