lsmvec-client 0.1.0__tar.gz

lsmvec_client-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,134 @@
+# 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/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-0.1.0/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-0.1.0/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/lsmvec_client.egg-info/PKG-INFO

@@ -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/lsmvec_client.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+lsmvec_client/__init__.py
+lsmvec_client/client.py
+lsmvec_client/errors.py
+lsmvec_client.egg-info/PKG-INFO
+lsmvec_client.egg-info/SOURCES.txt
+lsmvec_client.egg-info/dependency_links.txt
+lsmvec_client.egg-info/requires.txt
+lsmvec_client.egg-info/top_level.txt
+tests/test_client.py

lsmvec_client-0.1.0/lsmvec_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lsmvec_client-0.1.0/lsmvec_client.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest>=7
+
+[numpy]
+numpy>=1.20

lsmvec_client-0.1.0/lsmvec_client.egg-info/top_level.txt

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

lsmvec_client-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lsmvec-client"
+version = "0.1.0"
+description = "Python client for the LSM-Vec vector database HTTP API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "Apache-2.0"}
+authors = [{name = "LSM-Vec"}]
+# No required runtime dependencies — the client uses only the Python
+# standard library (urllib, json, struct). numpy is optional and only
+# used for the bulk_build convenience path.
+dependencies = []
+
+[project.optional-dependencies]
+numpy = ["numpy>=1.20"]
+dev = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["lsmvec_client*"]

lsmvec_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lsmvec_client-0.1.0/tests/test_client.py

@@ -0,0 +1,90 @@
+"""Integration test for the LSM-Vec Python client.
+
+Requires a running lsm_vec_http server. Point it via env:
+
+    LSMVEC_TEST_URL=http://localhost:8000 python3 tests/test_client.py
+
+The server must be started fresh (empty DB) with the matching dim
+(default 8 below). This is a plain-assert script (no pytest needed)
+so it runs in any environment.
+"""
+
+import os
+import sys
+
+# Allow running from the sdk/python dir without install.
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from lsmvec_client import Client, NotFound, InvalidArgument  # noqa: E402
+
+URL = os.environ.get("LSMVEC_TEST_URL", "http://localhost:8000")
+DIM = int(os.environ.get("LSMVEC_TEST_DIM", "8"))
+
+
+def vec(seed):
+    return [float((seed + i) % 10) * 0.1 for i in range(DIM)]
+
+
+def main():
+    c = Client(api_key="test-key", base_url=URL)
+
+    assert c.health(), "server health check failed"
+    print("[ok] health")
+
+    # Insert + get round-trip.
+    c.insert(1, vec(1), metadata={"name": "one"})
+    c.insert(2, vec(2))
+    got = c.get(1)
+    assert got["id"] == 1, got
+    assert len(got["vector"]) == DIM, got
+    print("[ok] insert + get")
+
+    # Payload.
+    pl = c.get_payload(1)
+    assert pl.get("name") == "one", pl
+    c.merge_payload(1, {"score": 42})
+    pl = c.get_payload(1)
+    assert pl.get("name") == "one" and pl.get("score") == 42, pl
+    print("[ok] payload get + merge")
+
+    # Search.
+    hits = c.search(vec(1), k=2)
+    assert len(hits) >= 1, hits
+    assert hits[0].id == 1, "nearest to vec(1) should be id 1, got %r" % hits
+    print("[ok] search (top hit id=%d dist=%.4f)" % (hits[0].id, hits[0].distance))
+
+    # Upsert then re-get. Stored vectors are SQ8-quantized (8-bit), so
+    # the round-trip is lossy — tolerance must accommodate ~range/255
+    # (~0.01 for these small magnitudes), not exact equality.
+    c.upsert(1, vec(5))
+    got = c.get(1)
+    assert abs(got["vector"][0] - vec(5)[0]) < 0.02, got
+    print("[ok] upsert")
+
+    # Delete + NotFound.
+    c.delete(2)
+    try:
+        c.get(2)
+        assert False, "expected NotFound after delete"
+    except NotFound:
+        pass
+    print("[ok] delete + NotFound")
+
+    # Wrong-dim insert → InvalidArgument.
+    try:
+        c.insert(99, [0.1, 0.2])  # wrong dim
+        assert False, "expected InvalidArgument for wrong dim"
+    except InvalidArgument:
+        pass
+    print("[ok] wrong-dim rejected")
+
+    # Stats.
+    s = c.stats()
+    assert "total_inserts_ever" in s, s
+    print("[ok] stats (total_inserts_ever=%s)" % s["total_inserts_ever"])
+
+    print("\nALL PASSED")
+
+
+if __name__ == "__main__":
+    main()