anywidget-vector 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

anywidget_vector/__init__.py

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

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/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/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)

anywidget_vector/backends/chroma/converter.py

@@ -0,0 +1,86 @@
+"""Chroma result conversion and filter building."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def to_points(response: dict[str, Any]) -> list[dict[str, Any]]:
+    """Convert Chroma response to points format."""
+    # Handle query results (nested lists) vs get results (flat lists)
+    is_query = "distances" in response
+
+    ids = response.get("ids", [[]])[0] if is_query else response.get("ids", [])
+    embeddings = response.get("embeddings", [[]])[0] if is_query else response.get("embeddings", [])
+    metadatas = response.get("metadatas", [[]])[0] if is_query else response.get("metadatas", [])
+    distances = response.get("distances", [[]])[0] if is_query else []
+    documents = response.get("documents", [[]])[0] if is_query else response.get("documents", [])
+
+    points = []
+    for i, id_ in enumerate(ids):
+        point: dict[str, Any] = {"id": str(id_)}
+
+        # Score from distance (invert since distance = dissimilarity)
+        if distances and i < len(distances):
+            point["score"] = 1 / (1 + distances[i])
+
+        # Embeddings -> coordinates
+        if embeddings and i < len(embeddings) and embeddings[i]:
+            vec = embeddings[i]
+            point["x"] = float(vec[0]) if len(vec) > 0 else 0
+            point["y"] = float(vec[1]) if len(vec) > 1 else 0
+            point["z"] = float(vec[2]) if len(vec) > 2 else 0
+            point["vector"] = vec
+
+        # Document content
+        if documents and i < len(documents) and documents[i]:
+            point["document"] = documents[i]
+
+        # Metadata
+        if metadatas and i < len(metadatas) and metadatas[i]:
+            point.update(metadatas[i])
+
+        points.append(point)
+
+    return points
+
+
+def build_where(conditions: list[tuple[str, str, Any]]) -> dict[str, Any]:
+    """Build Chroma where filter from conditions.
+
+    Chroma uses MongoDB-style operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin
+    """
+    op_map = {
+        "=": "$eq",
+        "!=": "$ne",
+        ">": "$gt",
+        ">=": "$gte",
+        "<": "$lt",
+        "<=": "$lte",
+        ":": "$in",
+    }
+
+    if len(conditions) == 0:
+        return {}
+
+    if len(conditions) == 1:
+        field, op, value = conditions[0]
+        chroma_op = op_map.get(op, "$eq")
+        if chroma_op == "$eq":
+            return {field: value}
+        if chroma_op == "$in" and not isinstance(value, list):
+            value = [value]
+        return {field: {chroma_op: value}}
+
+    # Multiple conditions: $and
+    and_list = []
+    for field, op, value in conditions:
+        chroma_op = op_map.get(op, "$eq")
+        if chroma_op == "$eq":
+            and_list.append({field: value})
+        else:
+            if chroma_op == "$in" and not isinstance(value, list):
+                value = [value]
+            and_list.append({field: {chroma_op: value}})
+
+    return {"$and": and_list}

anywidget_vector/backends/grafeo/__init__.py

@@ -0,0 +1,20 @@
+"""Grafeo backend adapter.
+
+Query Format (Grafeo Query Language):
+    # Get vectors with limit
+    MATCH (n:Vector) RETURN n LIMIT 10
+
+    # Filter by property
+    MATCH (n:Vector {category: "tech"}) RETURN n LIMIT 10
+
+    # Vector similarity (placeholder - depends on Grafeo API)
+    MATCH (n:Vector) WHERE similarity(n.embedding, $vector) > 0.8 RETURN n
+
+    # Connected nodes
+    MATCH (n:Vector)-[r]->(m) RETURN n, r, m LIMIT 10
+"""
+
+from anywidget_vector.backends.grafeo.client import execute_query
+from anywidget_vector.backends.grafeo.converter import to_points
+
+__all__ = ["to_points", "execute_query"]

anywidget_vector/backends/grafeo/client.py

@@ -0,0 +1,33 @@
+"""Grafeo Python client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from anywidget_vector.backends.grafeo.converter import to_points
+
+
+def execute_query(
+    client: Any,
+    query: str,
+) -> list[dict[str, Any]]:
+    """Execute query against Grafeo.
+
+    Args:
+        client: Grafeo client/session object
+        query: Grafeo query string
+
+    Returns:
+        List of points
+    """
+    # Execute the query - actual API depends on Grafeo implementation
+    if hasattr(client, "query"):
+        results = client.query(query)
+    elif hasattr(client, "run"):
+        results = client.run(query)
+    elif hasattr(client, "execute"):
+        results = client.execute(query)
+    else:
+        raise ValueError("Grafeo client must have query(), run(), or execute() method")
+
+    return to_points(results)

anywidget_vector/backends/grafeo/converter.py

@@ -0,0 +1,46 @@
+"""Grafeo result conversion."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def to_points(results: Any) -> list[dict[str, Any]]:
+    """Convert Grafeo results to points format."""
+    # Handle different result types
+    if hasattr(results, "to_dict"):
+        results = results.to_dict("records")
+    elif hasattr(results, "records"):
+        results = [dict(r) for r in results.records()]
+    elif not isinstance(results, list):
+        results = list(results)
+
+    points = []
+    for i, item in enumerate(results):
+        if isinstance(item, dict):
+            point: dict[str, Any] = {"id": str(item.get("id", f"point_{i}"))}
+
+            # Look for vector/embedding
+            vector = item.get("vector") or item.get("embedding")
+            if vector:
+                vec = list(vector) if hasattr(vector, "__iter__") else [vector]
+                point["x"] = float(vec[0]) if len(vec) > 0 else 0
+                point["y"] = float(vec[1]) if len(vec) > 1 else 0
+                point["z"] = float(vec[2]) if len(vec) > 2 else 0
+                point["vector"] = vec
+            else:
+                point["x"] = float(item.get("x", 0))
+                point["y"] = float(item.get("y", 0))
+                point["z"] = float(item.get("z", 0))
+
+            # Add all other fields
+            for k, v in item.items():
+                if k not in ("id", "vector", "embedding", "x", "y", "z"):
+                    point[k] = v
+
+            points.append(point)
+        else:
+            # Raw value
+            points.append({"id": f"point_{i}", "data": item, "x": 0, "y": 0, "z": 0})
+
+    return points

anywidget_vector/backends/lancedb/__init__.py

@@ -0,0 +1,22 @@
+"""LanceDB backend adapter.
+
+Query Format:
+    # Vector search (pass vector separately)
+    {"vector": [0.1, 0.2, ...], "limit": 10}
+
+    # With SQL filter
+    {"vector": [...], "where": "category = 'tech' AND year > 2020", "limit": 10}
+
+    # Filter only (no vector)
+    {"where": "category = 'tech'", "limit": 100}
+
+    # Full-text search
+    {"fts": "search query", "limit": 10}
+
+SQL WHERE supports: =, !=, <, >, <=, >=, AND, OR, IN, LIKE, IS NULL, IS NOT NULL
+"""
+
+from anywidget_vector.backends.lancedb.client import execute_query
+from anywidget_vector.backends.lancedb.converter import to_points
+
+__all__ = ["to_points", "execute_query"]

anywidget_vector/backends/lancedb/client.py

@@ -0,0 +1,56 @@
+"""LanceDB Python client."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from anywidget_vector.backends.lancedb.converter import to_points
+
+
+def execute_query(
+    table: Any,
+    query: str | dict[str, Any],
+) -> list[dict[str, Any]]:
+    """Execute query against LanceDB table.
+
+    Args:
+        table: LanceDB table object
+        query: Query dict or JSON string
+
+    Returns:
+        List of points
+    """
+    if isinstance(query, str):
+        query = json.loads(query)
+
+    limit = query.get("limit", 100)
+
+    # Vector search
+    if "vector" in query:
+        search = table.search(query["vector"])
+        if "where" in query:
+            search = search.where(query["where"])
+        results = search.limit(limit).to_list()
+        return to_points(results)
+
+    # Full-text search
+    if "fts" in query:
+        search = table.search(query["fts"], query_type="fts")
+        if "where" in query:
+            search = search.where(query["where"])
+        results = search.limit(limit).to_list()
+        return to_points(results)
+
+    # Filter only
+    if "where" in query:
+        # Use pandas for filtered scan
+        df = table.to_pandas()
+        # Simple eval for WHERE clause (in production, use proper SQL parser)
+        # For now, return all and let filter happen client-side
+        results = df.head(limit).to_dict("records")
+        return to_points(results)
+
+    # Get all
+    results = table.to_pandas().head(limit).to_dict("records")
+    return to_points(results)

anywidget_vector/backends/lancedb/converter.py

@@ -0,0 +1,71 @@
+"""LanceDB result conversion."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def to_points(results: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Convert LanceDB results to points format."""
+    points = []
+
+    for i, row in enumerate(results):
+        point: dict[str, Any] = {"id": str(row.get("id", f"point_{i}"))}
+
+        # Distance -> score
+        if "_distance" in row:
+            point["score"] = 1 / (1 + row["_distance"])
+
+        # Find vector field
+        vector = None
+        for key in ("vector", "embedding", "embeddings", "_vec"):
+            if key in row and row[key] is not None:
+                vector = row[key]
+                break
+
+        if vector is not None:
+            vec = list(vector) if hasattr(vector, "__iter__") else [vector]
+            point["x"] = float(vec[0]) if len(vec) > 0 else 0
+            point["y"] = float(vec[1]) if len(vec) > 1 else 0
+            point["z"] = float(vec[2]) if len(vec) > 2 else 0
+            point["vector"] = vec
+
+        # Add other fields
+        skip_keys = {"id", "vector", "embedding", "embeddings", "_vec", "_distance"}
+        for k, v in row.items():
+            if k not in skip_keys:
+                point[k] = v
+
+        points.append(point)
+
+    return points
+
+
+def build_where(conditions: list[tuple[str, str, Any]]) -> str:
+    """Build SQL WHERE clause from conditions.
+
+    Returns SQL string compatible with LanceDB.
+    """
+    if not conditions:
+        return ""
+
+    parts = []
+    for field, op, value in conditions:
+        if op == "~":
+            # LIKE for partial match
+            parts.append(f"{field} LIKE '%{value}%'")
+        elif op == ":":
+            # IN for array contains
+            if isinstance(value, list):
+                values = ", ".join(f"'{v}'" if isinstance(v, str) else str(v) for v in value)
+            else:
+                values = f"'{value}'" if isinstance(value, str) else str(value)
+            parts.append(f"{field} IN ({values})")
+        else:
+            # Standard operators
+            if isinstance(value, str):
+                parts.append(f"{field} {op} '{value}'")
+            else:
+                parts.append(f"{field} {op} {value}")
+
+    return " AND ".join(parts)

anywidget_vector/backends/pinecone/__init__.py

@@ -0,0 +1,21 @@
+"""Pinecone backend adapter.
+
+Query Format (JSON):
+    # Similarity search
+    {"vector": [0.1, 0.2, ...], "topK": 10}
+
+    # With filter
+    {"vector": [...], "filter": {"category": {"$eq": "tech"}}, "topK": 10}
+
+    # With namespace
+    {"vector": [...], "topK": 10, "namespace": "my-namespace"}
+
+    # Fetch by IDs
+    {"ids": ["id1", "id2"]}
+
+Filter operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin
+"""
+
+from anywidget_vector.backends.pinecone.converter import build_filter, to_points
+
+__all__ = ["to_points", "build_filter"]

anywidget_vector/backends/pinecone/client.js

@@ -0,0 +1,45 @@
+// Pinecone browser-side client
+
+export async function executeQuery(query, config) {
+  const { url, apiKey, namespace } = config;
+  const headers = { "Content-Type": "application/json", "Api-Key": apiKey };
+
+  const parsed = typeof query === "string" ? JSON.parse(query) : query;
+
+  if (parsed.ids) {
+    // Fetch by IDs
+    const resp = await fetch(`${url}/vectors/fetch?${parsed.ids.map(id => `ids=${id}`).join("&")}`, {
+      method: "GET",
+      headers,
+    });
+    if (!resp.ok) throw new Error(`Pinecone error: ${await resp.text()}`);
+    return await resp.json();
+  }
+
+  // Query
+  const body = {
+    vector: parsed.vector,
+    topK: parsed.topK || parsed.limit || 10,
+    includeMetadata: true,
+    includeValues: true,
+    filter: parsed.filter,
+    namespace: parsed.namespace || namespace,
+  };
+
+  const resp = await fetch(`${url}/query`, { method: "POST", headers, body: JSON.stringify(body) });
+  if (!resp.ok) throw new Error(`Pinecone error: ${await resp.text()}`);
+  return await resp.json();
+}
+
+export function toPoints(response) {
+  const matches = response.matches || [];
+  return matches.map(m => ({
+    id: m.id,
+    score: m.score,
+    x: m.values?.[0] ?? m.metadata?.x ?? 0,
+    y: m.values?.[1] ?? m.metadata?.y ?? 0,
+    z: m.values?.[2] ?? m.metadata?.z ?? 0,
+    vector: m.values,
+    ...m.metadata,
+  }));
+}

anywidget_vector/backends/pinecone/converter.py

@@ -0,0 +1,62 @@
+"""Pinecone result conversion and filter building."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def to_points(response: dict[str, Any]) -> list[dict[str, Any]]:
+    """Convert Pinecone response to points format."""
+    matches = response.get("matches") or []
+
+    points = []
+    for m in matches:
+        point: dict[str, Any] = {"id": m.get("id", "")}
+
+        if "score" in m:
+            point["score"] = m["score"]
+
+        values = m.get("values", [])
+        metadata = m.get("metadata", {})
+
+        if values:
+            point["x"] = float(values[0]) if len(values) > 0 else 0
+            point["y"] = float(values[1]) if len(values) > 1 else 0
+            point["z"] = float(values[2]) if len(values) > 2 else 0
+            point["vector"] = values
+        else:
+            point["x"] = float(metadata.get("x", 0))
+            point["y"] = float(metadata.get("y", 0))
+            point["z"] = float(metadata.get("z", 0))
+
+        point.update(metadata)
+        points.append(point)
+
+    return points
+
+
+def build_filter(conditions: list[tuple[str, str, Any]]) -> dict[str, Any]:
+    """Build Pinecone filter from conditions.
+
+    Pinecone uses MongoDB-style operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin
+    """
+    filter_dict = {}
+
+    op_map = {
+        "=": "$eq",
+        "!=": "$ne",
+        ">": "$gt",
+        ">=": "$gte",
+        "<": "$lt",
+        "<=": "$lte",
+        ":": "$in",  # Array contains
+    }
+
+    for field, op, value in conditions:
+        pinecone_op = op_map.get(op)
+        if pinecone_op:
+            if pinecone_op == "$in" and not isinstance(value, list):
+                value = [value]
+            filter_dict[field] = {pinecone_op: value}
+
+    return filter_dict