lsmvec-client 0.1.0__py3-none-any.whl

lsmvec_client/__init__.py

@@ -0,0 +1,34 @@
+"""LSM-Vec Python client.
+
+A thin, dependency-free client for the LSM-Vec HTTP server.
+
+    from lsmvec_client import Client
+    c = Client(api_key="sk-live-...", base_url="https://api.lsmvec.com")
+    c.insert(1, [0.1, 0.2, ...])
+    hits = c.search([0.1, 0.2, ...], k=10)
+"""
+
+from .client import Client, SearchResult
+from .errors import (
+    InvalidArgument,
+    LSMVecError,
+    NotFound,
+    PayloadTooLarge,
+    RateLimited,
+    ServerError,
+    Unauthorized,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "SearchResult",
+    "LSMVecError",
+    "InvalidArgument",
+    "Unauthorized",
+    "NotFound",
+    "PayloadTooLarge",
+    "RateLimited",
+    "ServerError",
+]

lsmvec_client/client.py

@@ -0,0 +1,246 @@
+"""LSM-Vec HTTP client.
+
+Thin wrapper over the LSM-Vec REST API (see docs/TRIAL_LAUNCH_PLAN.md
+§5.3). Uses only the Python standard library — no third-party
+dependencies required. numpy is optional and only used as a
+convenience for `bulk_build` (lists work too).
+
+Example:
+    from lsmvec_client import Client
+    c = Client(api_key="sk-live-...", base_url="http://localhost:8000")
+    c.insert(1, [0.1, 0.2, ...], metadata={"title": "doc"})
+    hits = c.search([0.1, 0.2, ...], k=10)
+    for h in hits:
+        print(h.id, h.distance)
+"""
+
+import json
+import struct
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from .errors import LSMVecError, from_status
+
+__all__ = ["Client", "SearchResult"]
+
+Vector = Union[Sequence[float], "numpy.ndarray"]  # noqa: F821
+
+
+@dataclass
+class SearchResult:
+    id: int
+    distance: float
+
+
+class Client:
+    """Client for a single LSM-Vec HTTP server (one trial user/container)."""
+
+    def __init__(
+        self,
+        api_key: str = "",
+        base_url: str = "http://localhost:8000",
+        timeout: float = 30.0,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ---- internal request helper ----
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[Any] = None,
+        raw_body: Optional[bytes] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+        parse_json: bool = True,
+    ):
+        url = self.base_url + path
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = "Bearer " + self.api_key
+
+        data = None
+        if raw_body is not None:
+            data = raw_body
+            headers["Content-Type"] = "application/octet-stream"
+        elif json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if extra_headers:
+            headers.update(extra_headers)
+
+        req = urllib.request.Request(url, data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                body = resp.read()
+                if not parse_json or not body:
+                    return resp.status, None
+                return resp.status, json.loads(body.decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            body = e.read()
+            code = None
+            message = e.reason or "http error"
+            try:
+                parsed = json.loads(body.decode("utf-8"))
+                code = parsed.get("code")
+                message = parsed.get("error", message)
+            except Exception:
+                if body:
+                    message = body.decode("utf-8", "replace")
+            raise from_status(e.code, code, message) from None
+        except urllib.error.URLError as e:
+            raise LSMVecError("connection failed: " + str(e.reason)) from None
+
+    @staticmethod
+    def _to_list(vector: Vector) -> List[float]:
+        # numpy array → list, list stays list.
+        if hasattr(vector, "tolist"):
+            return vector.tolist()
+        return list(vector)
+
+    # ---- vectors ----
+
+    def insert(
+        self,
+        id: int,
+        vector: Vector,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        body: Dict[str, Any] = {"id": int(id), "vector": self._to_list(vector)}
+        if metadata is not None:
+            body["metadata"] = metadata
+        self._request("POST", "/v1/vectors", json_body=body, parse_json=False)
+
+    def upsert(self, id: int, vector: Vector) -> None:
+        self._request(
+            "PUT",
+            "/v1/vectors/%d" % int(id),
+            json_body={"vector": self._to_list(vector)},
+            parse_json=False,
+        )
+
+    def get(self, id: int) -> Dict[str, Any]:
+        _, body = self._request("GET", "/v1/vectors/%d" % int(id))
+        return body
+
+    def delete(self, id: int) -> None:
+        self._request("DELETE", "/v1/vectors/%d" % int(id), parse_json=False)
+
+    # ---- payload ----
+
+    def get_payload(self, id: int) -> Dict[str, Any]:
+        _, body = self._request("GET", "/v1/vectors/%d/payload" % int(id))
+        return body
+
+    def set_payload(self, id: int, payload: Dict[str, Any]) -> None:
+        self._request(
+            "PUT",
+            "/v1/vectors/%d/payload" % int(id),
+            json_body=payload,
+            parse_json=False,
+        )
+
+    def merge_payload(self, id: int, partial: Dict[str, Any]) -> None:
+        """RFC 7396 merge-patch: keys in `partial` overwrite; null deletes."""
+        self._request(
+            "PATCH",
+            "/v1/vectors/%d/payload" % int(id),
+            json_body=partial,
+            parse_json=False,
+        )
+
+    # ---- search ----
+
+    def search(
+        self,
+        vector: Vector,
+        k: int = 10,
+        ef_search: Optional[int] = None,
+        filter: Optional[Dict[str, Any]] = None,
+    ) -> List[SearchResult]:
+        body: Dict[str, Any] = {"vector": self._to_list(vector), "k": int(k)}
+        if ef_search is not None:
+            body["ef_search"] = int(ef_search)
+        if filter is not None:
+            body["filter"] = filter
+        _, parsed = self._request("POST", "/v1/search", json_body=body)
+        results = parsed.get("results", []) if parsed else []
+        return [SearchResult(id=r["id"], distance=r["distance"]) for r in results]
+
+    # ---- bulk build (initial-load only) ----
+
+    def bulk_build(self, vectors, dim: Optional[int] = None, threads: int = 0) -> Dict[str, Any]:
+        """Build the entire index from a batch of vectors in one call.
+
+        `vectors` may be a 2-D numpy array (n, dim) or a list of
+        equal-length float lists. The DB must be empty — bulk build is
+        initial-load only.
+
+        Returns the server's timing report dict
+        {n, elapsed_ms, vectors_per_sec, threads}.
+        """
+        # Normalize to a flat float32 byte blob + (n, dim).
+        if hasattr(vectors, "shape"):  # numpy array
+            import numpy as np  # local import; numpy optional otherwise
+
+            arr = np.ascontiguousarray(vectors, dtype=np.float32)
+            if arr.ndim != 2:
+                raise ValueError("vectors must be a 2-D array (n, dim)")
+            n, d = arr.shape
+            if dim is not None and dim != d:
+                raise ValueError("dim=%d does not match array dim=%d" % (dim, d))
+            blob = arr.tobytes()
+        else:  # list of lists
+            rows = list(vectors)
+            n = len(rows)
+            if n == 0:
+                raise ValueError("vectors is empty")
+            d = len(rows[0])
+            if dim is not None and dim != d:
+                raise ValueError("dim=%d does not match row length=%d" % (dim, d))
+            flat = []
+            for row in rows:
+                if len(row) != d:
+                    raise ValueError("all rows must have the same length")
+                flat.extend(row)
+            blob = struct.pack("<%df" % (n * d), *flat)
+
+        headers = {
+            "X-LSMVec-N": str(n),
+            "X-LSMVec-Dim": str(d),
+        }
+        if threads > 0:
+            headers["X-LSMVec-Threads"] = str(threads)
+
+        _, parsed = self._request(
+            "POST",
+            "/v1/build/bulk",
+            raw_body=blob,
+            extra_headers=headers,
+        )
+        return parsed
+
+    # ---- diagnostics ----
+
+    def stats(self) -> Dict[str, Any]:
+        _, body = self._request("GET", "/v1/stats")
+        return body
+
+    def health(self) -> bool:
+        try:
+            status, _ = self._request("GET", "/health", parse_json=False)
+            return status == 200
+        except LSMVecError:
+            return False
+
+    def ready(self) -> bool:
+        try:
+            status, _ = self._request("GET", "/ready", parse_json=False)
+            return status == 200
+        except LSMVecError:
+            return False

lsmvec_client/errors.py

@@ -0,0 +1,63 @@
+"""Exception hierarchy for the LSM-Vec client.
+
+HTTP status codes map to typed exceptions so callers can catch the
+specific failure they care about:
+
+    400 -> InvalidArgument
+    401 -> Unauthorized
+    404 -> NotFound
+    413 -> PayloadTooLarge
+    429 -> RateLimited
+    5xx -> ServerError
+    other / network -> LSMVecError (base)
+"""
+
+
+class LSMVecError(Exception):
+    """Base class for all client errors."""
+
+    def __init__(self, message, *, status=None, code=None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class InvalidArgument(LSMVecError):
+    """400 — malformed request (bad vector, wrong dim, bad JSON)."""
+
+
+class Unauthorized(LSMVecError):
+    """401 — missing or invalid API key."""
+
+
+class NotFound(LSMVecError):
+    """404 — id does not exist / index empty."""
+
+
+class PayloadTooLarge(LSMVecError):
+    """413 — request body exceeds the server's limit."""
+
+
+class RateLimited(LSMVecError):
+    """429 — too many requests; back off and retry."""
+
+
+class ServerError(LSMVecError):
+    """5xx — server-side failure."""
+
+
+def from_status(status, code, message):
+    """Build the right exception subtype from an HTTP status."""
+    if status == 400:
+        return InvalidArgument(message, status=status, code=code)
+    if status == 401:
+        return Unauthorized(message, status=status, code=code)
+    if status == 404:
+        return NotFound(message, status=status, code=code)
+    if status == 413:
+        return PayloadTooLarge(message, status=status, code=code)
+    if status == 429:
+        return RateLimited(message, status=status, code=code)
+    if 500 <= status < 600:
+        return ServerError(message, status=status, code=code)
+    return LSMVecError(message, status=status, code=code)

lsmvec_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: lsmvec-client
+Version: 0.1.0
+Summary: Python client for the LSM-Vec vector database HTTP API
+Author: LSM-Vec
+License: Apache-2.0
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.20; extra == "numpy"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# lsmvec-client — Python client for LSM-Vec
+
+A thin, dependency-free Python client for the LSM-Vec vector database
+HTTP API. Uses only the Python standard library; `numpy` is optional
+(a convenience for `bulk_build`).
+
+## Install
+
+```bash
+pip install lsmvec-client            # core, zero dependencies
+pip install lsmvec-client[numpy]     # + numpy for bulk_build convenience
+```
+
+Or run straight from the repo without installing:
+
+```python
+import sys; sys.path.insert(0, "sdk/python")
+from lsmvec_client import Client
+```
+
+## Quickstart
+
+```python
+from lsmvec_client import Client
+
+client = Client(
+    api_key="sk-live-...",                 # sent as Bearer token
+    base_url="https://api.lsmvec.com",     # or http://localhost:8000 for local
+)
+
+# Insert with optional metadata
+client.insert(1, [0.10, 0.20, 0.30, ...], metadata={"title": "intro"})
+
+# Search
+hits = client.search([0.10, 0.20, 0.30, ...], k=10)
+for h in hits:
+    print(h.id, h.distance)
+
+# Filtered search (metadata predicate, same syntax as the HTTP API)
+hits = client.search(
+    [0.10, 0.20, ...], k=10,
+    filter={"$and": [{"category": {"$eq": "docs"}}]},
+)
+```
+
+## Bulk build (initial load)
+
+The fastest way to populate a **new, empty** database. Builds the
+whole index in memory (RNN-Descent) and writes it in one pass —
+2-3× faster than per-vector inserts and higher recall. Initial-load
+only; the DB must be empty.
+
+```python
+import numpy as np
+from lsmvec_client import Client
+
+client = Client(base_url="http://localhost:8000")
+
+vectors = np.random.rand(100_000, 128).astype(np.float32)
+report = client.bulk_build(vectors, threads=4)
+print(report)   # {'n': 100000, 'elapsed_ms': ..., 'vectors_per_sec': ..., 'threads': 4}
+```
+
+`bulk_build` also accepts a plain list of equal-length float lists
+(no numpy required):
+
+```python
+rows = [[0.1, 0.2, 0.3, 0.4], [0.5, 0.6, 0.7, 0.8], ...]
+client.bulk_build(rows)
+```
+
+For incremental updates on an already-built index, use `insert()` /
+`upsert()` instead — `bulk_build` rejects a non-empty DB.
+
+## API
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `insert(id, vector, metadata=None)` | `POST /v1/vectors` | metadata is any JSON object |
+| `upsert(id, vector)` | `PUT /v1/vectors/:id` | insert-or-replace vector |
+| `get(id) -> dict` | `GET /v1/vectors/:id` | `{"id", "vector"}` |
+| `delete(id)` | `DELETE /v1/vectors/:id` | |
+| `get_payload(id) -> dict` | `GET /v1/vectors/:id/payload` | |
+| `set_payload(id, payload)` | `PUT /v1/vectors/:id/payload` | replace |
+| `merge_payload(id, partial)` | `PATCH /v1/vectors/:id/payload` | RFC 7396 merge |
+| `search(vector, k=10, ef_search=None, filter=None) -> [SearchResult]` | `POST /v1/search` | |
+| `bulk_build(vectors, dim=None, threads=0) -> dict` | `POST /v1/build/bulk` | empty DB only |
+| `stats() -> dict` | `GET /v1/stats` | tombstone / bloom counters |
+| `health() -> bool` | `GET /health` | |
+| `ready() -> bool` | `GET /ready` | DB open + responsive |
+
+`search` returns a list of `SearchResult(id: int, distance: float)`.
+
+## Errors
+
+HTTP status codes map to typed exceptions (all subclass `LSMVecError`):
+
+| Status | Exception |
+|---|---|
+| 400 | `InvalidArgument` |
+| 401 | `Unauthorized` |
+| 404 | `NotFound` |
+| 413 | `PayloadTooLarge` |
+| 429 | `RateLimited` |
+| 5xx | `ServerError` |
+
+```python
+from lsmvec_client import NotFound
+
+try:
+    client.get(999999)
+except NotFound:
+    print("no such id")
+```
+
+## Notes
+
+- Vectors are stored with 8-bit scalar quantization (SQ8). `get()`
+  returns the dequantized vector, which differs from the input by
+  up to ~`range/255` per element. Distances and recall are computed
+  on the quantized form.
+- `id` is a 64-bit unsigned integer.
+- The client is synchronous and connection-per-request (stdlib
+  `urllib`). For high-throughput batch ingestion, prefer
+  `bulk_build` over a loop of `insert`.
+
+## Testing
+
+Against a running server:
+
+```bash
+LSMVEC_TEST_URL=http://localhost:8000 LSMVEC_TEST_DIM=8 \
+    python3 sdk/python/tests/test_client.py
+```

lsmvec_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+lsmvec_client/__init__.py,sha256=sDDO-QJUuiPUXwgUGXqSMwIOFwr5mpJcOnMKRHgzozM,680
+lsmvec_client/client.py,sha256=b5YBP5zX-CiaOAWyp-xNvQeycUZRZu7AS0PATRHyJlg,8074
+lsmvec_client/errors.py,sha256=hKCO5Ue5cLQ5_MfiMScu3oyZ0vmvva2zKrdizrsPsAw,1779
+lsmvec_client-0.1.0.dist-info/METADATA,sha256=KA_PB7JywXJ59e-tuQ815p0s1S3CSEll9e8DFA--Hz0,4333
+lsmvec_client-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+lsmvec_client-0.1.0.dist-info/top_level.txt,sha256=yv_1Z78oFcVaa7qWw9pidDXF5xGeD951By32Tp52Z9Q,14
+lsmvec_client-0.1.0.dist-info/RECORD,,

lsmvec_client-0.1.0.dist-info/WHEEL

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

lsmvec_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+lsmvec_client