massengine 1.1.3__tar.gz

massengine-1.1.3/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/
+venv/
+.DS_Store

massengine-1.1.3/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 MassEngine
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

massengine-1.1.3/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: massengine
+Version: 1.1.3
+Summary: Official Python SDK for the MassEngine vector and hybrid search database.
+Project-URL: Homepage, https://massengine.com
+Project-URL: Documentation, https://massengine.com/docs
+Project-URL: Repository, https://github.com/massengine-dev/massengine-python
+Author-email: MassEngine <dev@massengine.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: bm25,embeddings,hybrid-search,massengine,rag,vector-database
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# MassEngine Python SDK (`massengine`)
+
+Official zero-dependency Python client for [MassEngine](https://massengine.com) — the sub-5ms filtered and hybrid vector search database.
+
+## Installation
+
+```bash
+pip install massengine
+```
+
+## Quickstart
+
+```python
+from massengine import MassEngineClient, Doc
+
+# Connect to a local quickstart cluster (http://localhost:8080) or cloud gateway:
+client = MassEngineClient(
+    base_url="http://localhost:8080",
+    api_key="mk_your_tenant_or_meadm_admin_key",
+)
+
+# 1. Ingest vectors + structured metadata
+client.ingest(
+    "acme-prod",
+    [
+        Doc(
+            id="doc-1",
+            vector=[0.12, -0.44, 0.88, 0.05],
+            category=1,
+            metadata={"department": "security", "clearance": 3, "tags": ["soc2", "policy"]},
+        )
+    ],
+)
+
+# 2. Hybrid dense + BM25 search with rich metadata filter operators
+res = client.search(
+    "acme-prod",
+    vector=[0.12, -0.44, 0.88, 0.05],
+    query_text="soc2 policy",
+    hybrid_alpha=0.7,
+    k=10,
+    min_score=0.5,
+    metadata_filter={
+        "department": {"$in": ["security", "legal"]},
+        "clearance": {"$gte": 2},
+        "tags": {"$contains": "soc2"},
+    },
+)
+print(res["hits"])
+
+# 3. In-place metadata patching without re-embedding
+client.patch_doc(
+    "acme-prod",
+    "doc-1",
+    metadata={"clearance": 4, "reviewed": True},
+)
+
+# 4. Inspect tenant quota & billable usage
+usage = client.get_tenant_usage("acme-prod")
+print(usage)
+```
+
+## License
+
+Apache License 2.0

massengine-1.1.3/README.md

@@ -0,0 +1,65 @@
+# MassEngine Python SDK (`massengine`)
+
+Official zero-dependency Python client for [MassEngine](https://massengine.com) — the sub-5ms filtered and hybrid vector search database.
+
+## Installation
+
+```bash
+pip install massengine
+```
+
+## Quickstart
+
+```python
+from massengine import MassEngineClient, Doc
+
+# Connect to a local quickstart cluster (http://localhost:8080) or cloud gateway:
+client = MassEngineClient(
+    base_url="http://localhost:8080",
+    api_key="mk_your_tenant_or_meadm_admin_key",
+)
+
+# 1. Ingest vectors + structured metadata
+client.ingest(
+    "acme-prod",
+    [
+        Doc(
+            id="doc-1",
+            vector=[0.12, -0.44, 0.88, 0.05],
+            category=1,
+            metadata={"department": "security", "clearance": 3, "tags": ["soc2", "policy"]},
+        )
+    ],
+)
+
+# 2. Hybrid dense + BM25 search with rich metadata filter operators
+res = client.search(
+    "acme-prod",
+    vector=[0.12, -0.44, 0.88, 0.05],
+    query_text="soc2 policy",
+    hybrid_alpha=0.7,
+    k=10,
+    min_score=0.5,
+    metadata_filter={
+        "department": {"$in": ["security", "legal"]},
+        "clearance": {"$gte": 2},
+        "tags": {"$contains": "soc2"},
+    },
+)
+print(res["hits"])
+
+# 3. In-place metadata patching without re-embedding
+client.patch_doc(
+    "acme-prod",
+    "doc-1",
+    metadata={"clearance": 4, "reviewed": True},
+)
+
+# 4. Inspect tenant quota & billable usage
+usage = client.get_tenant_usage("acme-prod")
+print(usage)
+```
+
+## License
+
+Apache License 2.0

massengine-1.1.3/massengine/__init__.py

@@ -0,0 +1,19 @@
+"""Official Python client SDK for MassEngine."""
+
+from .client import (
+    MassEngineClient,
+    MassEngineError,
+    Doc,
+    SDK_VERSION,
+    SearchRequest,
+    TenantQuota,
+)
+
+__all__ = [
+    "MassEngineClient",
+    "MassEngineError",
+    "Doc",
+    "SearchRequest",
+    "TenantQuota",
+]
+__version__ = SDK_VERSION

massengine-1.1.3/massengine/client.py

@@ -0,0 +1,537 @@
+"""Zero-dependency Python HTTP/JSON client for MassEngine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import ssl
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Union
+import urllib.error
+import urllib.parse
+import urllib.request
+
+SDK_VERSION = "1.1.3"
+USER_AGENT = f"massengine-python/{SDK_VERSION}"
+DEFAULT_MAX_RESPONSE_BYTES = 64 * 1024 * 1024  # 64 MiB
+MAX_ERROR_RESPONSE_BYTES = 65536               # 64 KiB
+_MAX_LINE_READ_CHUNK = 4 * 1024 * 1024
+
+
+class MassEngineError(Exception):
+    """Raised when the MassEngine gateway returns a non-2xx HTTP status."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        super().__init__(f"massengine api (status {status_code}): {message}")
+        self.status_code = status_code
+        self.message = message
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Prevents urllib from following HTTP redirects and leaking Authorization headers."""
+
+    def redirect_request(
+        self,
+        req: urllib.request.Request,
+        fp: Any,
+        code: int,
+        msg: str,
+        headers: Any,
+        newurl: str,
+    ) -> None:
+        return None
+
+
+@dataclass
+class Doc:
+    """Represents a vector document for ingestion or export."""
+
+    id: str
+    vector: Sequence[float]
+    date: Optional[int] = None
+    category: Optional[int] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {
+            "id": self.id,
+            "vector": list(self.vector),
+        }
+        if self.date is not None:
+            out["date"] = int(self.date)
+        if self.category is not None:
+            out["category"] = int(self.category)
+        if self.metadata is not None:
+            out["metadata"] = self.metadata
+        return out
+
+
+@dataclass
+class SearchRequest:
+    """Specifies a single vector, lexical, or hybrid query."""
+
+    tenant: str
+    k: int = 10
+    vector: Optional[Sequence[float]] = None
+    query_text: Optional[str] = None
+    hybrid_alpha: Optional[float] = None
+    metadata_filter: Optional[Dict[str, Any]] = None
+    offset: int = 0
+    min_score: Optional[float] = None
+    rerank_pool: Optional[int] = None
+    nprobe: Optional[int] = None
+    min_date: Optional[int] = None
+    max_date: Optional[int] = None
+    category: Optional[int] = None
+    categories: Optional[Sequence[int]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {
+            "tenant": self.tenant,
+            "k": self.k,
+        }
+        if self.vector is not None:
+            out["vector"] = list(self.vector)
+        if self.query_text:
+            out["query_text"] = self.query_text
+        if self.hybrid_alpha is not None:
+            out["hybrid_alpha"] = float(self.hybrid_alpha)
+        if self.metadata_filter is not None:
+            out["metadata_filter"] = self.metadata_filter
+        if self.offset:
+            out["offset"] = int(self.offset)
+        if self.min_score is not None:
+            out["min_score"] = float(self.min_score)
+        if self.rerank_pool:
+            out["rerank_pool"] = int(self.rerank_pool)
+        if self.nprobe:
+            out["nprobe"] = int(self.nprobe)
+        if self.min_date is not None:
+            out["min_date"] = int(self.min_date)
+        if self.max_date is not None:
+            out["max_date"] = int(self.max_date)
+        if self.category is not None:
+            out["category"] = int(self.category)
+        if self.categories:
+            out["categories"] = [int(c) for c in self.categories]
+        return out
+
+
+@dataclass
+class TenantQuota:
+    """Configures a tenant's commercial plan tier, limits, and suspension status."""
+
+    plan: str = ""
+    max_docs: int = 0
+    max_qps: float = 0.0
+    burst: int = 0
+    suspended: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "plan": self.plan,
+            "max_docs": int(self.max_docs),
+            "max_qps": float(self.max_qps),
+            "burst": int(self.burst),
+            "suspended": bool(self.suspended),
+        }
+
+
+class MassEngineClient:
+    """Official Python SDK client for the MassEngine HTTP REST API."""
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8081",
+        api_key: Optional[str] = None,
+        timeout: float = 30.0,
+        max_response_bytes: int = DEFAULT_MAX_RESPONSE_BYTES,
+    ) -> None:
+        self.base_url = self._validate_base_url(base_url)
+        self._api_key = self._validate_api_key(api_key)
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:
+            raise ValueError("timeout must be a positive number")
+        if isinstance(max_response_bytes, bool) or not isinstance(max_response_bytes, int) or max_response_bytes <= 0:
+            raise ValueError("max_response_bytes must be a positive integer")
+        self.timeout = float(timeout)
+        self.max_response_bytes = max_response_bytes
+
+        ssl_ctx = ssl.create_default_context()
+        ssl_ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+        self._opener = urllib.request.build_opener(
+            _NoRedirectHandler(),
+            urllib.request.HTTPSHandler(context=ssl_ctx),
+        )
+
+    def __repr__(self) -> str:
+        masked = "***" if self._api_key else None
+        return f"MassEngineClient(base_url={self.base_url!r}, api_key={masked!r})"
+
+    @staticmethod
+    def _validate_base_url(base_url: str) -> str:
+        if not isinstance(base_url, str) or not base_url.strip():
+            raise ValueError("base_url must be a valid http or https URL")
+        cleaned = base_url.strip().rstrip("/")
+        if any(ord(ch) <= 0x20 or ord(ch) == 0x7F for ch in cleaned):
+            raise ValueError("base_url contains invalid characters")
+        parsed = urllib.parse.urlsplit(cleaned)
+        if (
+            parsed.scheme not in ("http", "https")
+            or not parsed.netloc
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise ValueError("base_url must use http or https scheme with a valid host")
+        return cleaned
+
+    @staticmethod
+    def _validate_api_key(api_key: Optional[str]) -> Optional[str]:
+        if api_key is None or api_key == "":
+            return None
+        if not isinstance(api_key, str):
+            raise ValueError("invalid api_key format")
+        trimmed = api_key.strip(" \t")
+        if not trimmed or not all(0x21 <= ord(ch) <= 0x7E for ch in trimmed):
+            raise ValueError("invalid api_key format")
+        return trimmed
+
+    def _headers(self, content_type: Optional[str] = "application/json") -> Dict[str, str]:
+        hdrs: Dict[str, str] = {"User-Agent": USER_AGENT}
+        if content_type:
+            hdrs["Content-Type"] = content_type
+        if self._api_key:
+            hdrs["Authorization"] = f"Bearer {self._api_key}"
+        return hdrs
+
+    def _read_bounded(self, resp: Any) -> bytes:
+        raw: bytes = resp.read(self.max_response_bytes + 1)
+        if len(raw) > self.max_response_bytes:
+            status = int(getattr(resp, "status", 200) or 200)
+            raise MassEngineError(
+                status,
+                f"response body exceeds max_response_bytes ({self.max_response_bytes})",
+            )
+        return raw
+
+    @staticmethod
+    def _decode_error(e: urllib.error.HTTPError) -> MassEngineError:
+        try:
+            raw_err = e.read(MAX_ERROR_RESPONSE_BYTES).decode("utf-8", errors="replace")
+        finally:
+            try:
+                e.close()
+            except Exception:
+                pass
+        msg = raw_err.strip()
+        try:
+            parsed = json.loads(raw_err)
+            if isinstance(parsed, dict) and parsed.get("error"):
+                msg = str(parsed["error"])
+        except Exception:
+            pass
+        return MassEngineError(e.code, msg)
+
+    def _request_json(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Any] = None,
+    ) -> Any:
+        data: Optional[bytes] = None
+        content_type: Optional[str] = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            content_type = "application/json"
+
+        req = urllib.request.Request(
+            url=f"{self.base_url}{path}",
+            data=data,
+            headers=self._headers(content_type),
+            method=method,
+        )
+        try:
+            with self._opener.open(req, timeout=self.timeout) as resp:
+                status = int(getattr(resp, "status", 200) or 200)
+                raw = self._read_bounded(resp)
+                if status < 200 or status >= 300:
+                    raise MassEngineError(status, raw.decode("utf-8", errors="replace").strip())
+                if not raw:
+                    return None
+                return json.loads(raw.decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            raise self._decode_error(e) from None
+
+    @staticmethod
+    def _esc(segment: str) -> str:
+        if not isinstance(segment, str) or segment in ("", ".", ".."):
+            raise ValueError("invalid URL path segment")
+        if any(ord(ch) < 0x20 or ord(ch) == 0x7F for ch in segment):
+            raise ValueError("invalid control character in URL path segment")
+        return urllib.parse.quote(segment, safe="")
+
+    @classmethod
+    def _esc_tenant(cls, tenant: str) -> str:
+        if not isinstance(tenant, str) or "/" in tenant or "\\" in tenant:
+            raise ValueError("invalid tenant identifier")
+        return cls._esc(tenant)
+
+    @classmethod
+    def _esc_doc_id(cls, doc_id: str) -> str:
+        if doc_id == "batch-get":
+            raise ValueError("reserved document identifier")
+        return cls._esc(doc_id)
+
+    def ingest(
+        self,
+        tenant: str,
+        docs: Sequence[Union[Doc, Dict[str, Any]]],
+    ) -> Dict[str, Any]:
+        """Inserts or upserts a batch of documents into `tenant`."""
+        serialized = [d.to_dict() if isinstance(d, Doc) else d for d in docs]
+        return self._request_json(
+            "POST",
+            f"/v1/tenants/{self._esc_tenant(tenant)}/ingest",
+            {"docs": serialized},
+        )
+
+    def search(
+        self,
+        tenant: str,
+        *,
+        vector: Optional[Sequence[float]] = None,
+        query_text: Optional[str] = None,
+        k: int = 10,
+        hybrid_alpha: Optional[float] = None,
+        metadata_filter: Optional[Dict[str, Any]] = None,
+        offset: int = 0,
+        min_score: Optional[float] = None,
+        rerank_pool: Optional[int] = None,
+        nprobe: Optional[int] = None,
+        min_date: Optional[int] = None,
+        max_date: Optional[int] = None,
+        category: Optional[int] = None,
+        categories: Optional[Sequence[int]] = None,
+    ) -> Dict[str, Any]:
+        """Executes a dense vector, lexical BM25, or hybrid query."""
+        sr = SearchRequest(
+            tenant=tenant,
+            k=k,
+            vector=vector,
+            query_text=query_text,
+            hybrid_alpha=hybrid_alpha,
+            metadata_filter=metadata_filter,
+            offset=offset,
+            min_score=min_score,
+            rerank_pool=rerank_pool,
+            nprobe=nprobe,
+            min_date=min_date,
+            max_date=max_date,
+            category=category,
+            categories=categories,
+        )
+        return self._request_json("POST", "/v1/search", sr.to_dict())
+
+    def batch_search(
+        self,
+        queries: Sequence[Union[SearchRequest, Dict[str, Any]]],
+    ) -> Dict[str, Any]:
+        """Executes multiple search queries in a single round-trip."""
+        serialized = [
+            q.to_dict() if isinstance(q, SearchRequest) else q for q in queries
+        ]
+        return self._request_json("POST", "/v1/search/batch", {"queries": serialized})
+
+    def get_doc(self, tenant: str, doc_id: str) -> Dict[str, Any]:
+        """Fetches a document's metadata by ID."""
+        return self._request_json(
+            "GET",
+            f"/v1/tenants/{self._esc_tenant(tenant)}/docs/{self._esc_doc_id(doc_id)}",
+        )
+
+    def patch_doc(
+        self,
+        tenant: str,
+        doc_id: str,
+        *,
+        metadata: Optional[Dict[str, Any]] = None,
+        date: Optional[int] = None,
+        category: Optional[int] = None,
+        replace_metadata: bool = False,
+    ) -> Dict[str, Any]:
+        """Updates a document's metadata, date, or category in place without re-embedding."""
+        body: Dict[str, Any] = {}
+        if metadata is not None:
+            body["metadata"] = metadata
+        if date is not None:
+            body["date"] = int(date)
+        if category is not None:
+            body["category"] = int(category)
+        if replace_metadata:
+            body["replace_metadata"] = True
+        return self._request_json(
+            "PATCH",
+            f"/v1/tenants/{self._esc_tenant(tenant)}/docs/{self._esc_doc_id(doc_id)}",
+            body,
+        )
+
+    def batch_get_docs(self, tenant: str, ids: Sequence[str]) -> List[Dict[str, Any]]:
+        """Fetches multiple documents by ID in a single request."""
+        resp = self._request_json(
+            "POST",
+            f"/v1/tenants/{self._esc_tenant(tenant)}/docs/batch-get",
+            {"ids": list(ids)},
+        )
+        return resp.get("docs", [])
+
+    def delete_doc(self, tenant: str, doc_id: str) -> Dict[str, Any]:
+        """Deletes a document by ID."""
+        return self._request_json(
+            "DELETE",
+            f"/v1/tenants/{self._esc_tenant(tenant)}/docs/{self._esc_doc_id(doc_id)}",
+        )
+
+    def import_tenant(
+        self,
+        tenant: str,
+        docs: Iterable[Union[Doc, Dict[str, Any]]],
+    ) -> int:
+        """Streams a collection of documents into `tenant` via NDJSON."""
+        esc_tenant = self._esc_tenant(tenant)
+        lines = [
+            json.dumps(d.to_dict() if isinstance(d, Doc) else d) for d in docs
+        ]
+        payload = ("\n".join(lines) + "\n").encode("utf-8")
+        req = urllib.request.Request(
+            url=f"{self.base_url}/v1/tenants/{esc_tenant}/import",
+            data=payload,
+            headers=self._headers("application/x-ndjson"),
+            method="POST",
+        )
+        try:
+            with self._opener.open(req, timeout=self.timeout) as resp:
+                raw = self._read_bounded(resp)
+                out = json.loads(raw.decode("utf-8"))
+                return int(out.get("imported", 0))
+        except urllib.error.HTTPError as e:
+            raise self._decode_error(e) from None
+
+    def export_tenant(self, tenant: str) -> List[Dict[str, Any]]:
+        """Exports all live documents belonging to `tenant` via streaming NDJSON."""
+        esc_tenant = self._esc_tenant(tenant)
+        req = urllib.request.Request(
+            url=f"{self.base_url}/v1/tenants/{esc_tenant}/export",
+            headers=self._headers(None),
+            method="GET",
+        )
+        try:
+            with self._opener.open(req, timeout=self.timeout) as resp:
+                status = int(getattr(resp, "status", 200) or 200)
+                docs: List[Dict[str, Any]] = []
+                total_bytes = 0
+                buf = b""
+                while True:
+                    remaining = self.max_response_bytes - total_bytes + 1
+                    read_limit = min(remaining, _MAX_LINE_READ_CHUNK)
+                    chunk: bytes = resp.readline(max(1, read_limit))
+                    if not chunk:
+                        break
+                    total_bytes += len(chunk)
+                    if total_bytes > self.max_response_bytes:
+                        raise MassEngineError(
+                            status,
+                            f"response body exceeds max_response_bytes ({self.max_response_bytes})",
+                        )
+                    buf += chunk
+                    if buf.endswith(b"\n"):
+                        line = buf.decode("utf-8").strip()
+                        buf = b""
+                        if line:
+                            docs.append(json.loads(line))
+                if buf:
+                    line = buf.decode("utf-8").strip()
+                    if line:
+                        docs.append(json.loads(line))
+                return docs
+        except urllib.error.HTTPError as e:
+            raise self._decode_error(e) from None
+
+    def create_tenant_key(self, tenant: str, key: str = "") -> str:
+        """Creates or registers a tenant-scoped RBAC API key (requires admin key)."""
+        resp = self._request_json(
+            "POST",
+            f"/v1/tenants/{self._esc_tenant(tenant)}/keys",
+            {"key": key},
+        )
+        return str(resp["key"])
+
+    def revoke_tenant_key(self, tenant: str, key: str) -> Dict[str, Any]:
+        """Revokes a tenant-scoped RBAC API key (requires admin key)."""
+        return self._request_json(
+            "DELETE",
+            f"/v1/tenants/{self._esc_tenant(tenant)}/keys",
+            {"key": key},
+        )
+
+    def set_tenant_quota(
+        self,
+        tenant: str,
+        quota: Union[TenantQuota, Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Sets a tenant's plan tier, max_docs cap, max_qps limit, and suspension status."""
+        q_dict = quota.to_dict() if isinstance(quota, TenantQuota) else quota
+        resp = self._request_json(
+            "PUT",
+            f"/v1/tenants/{self._esc_tenant(tenant)}/quota",
+            q_dict,
+        )
+        return resp.get("quota", resp)
+
+    def get_tenant_quota(self, tenant: str) -> Dict[str, Any]:
+        """Retrieves the active quota configuration for `tenant`."""
+        resp = self._request_json(
+            "GET",
+            f"/v1/tenants/{self._esc_tenant(tenant)}/quota",
+        )
+        return resp.get("quota", resp)
+
+    def get_tenant_usage(self, tenant: str) -> Dict[str, Any]:
+        """Returns cumulative billable read/write counters and live doc count for `tenant`."""
+        return self._request_json(
+            "GET",
+            f"/v1/tenants/{self._esc_tenant(tenant)}/usage",
+        )
+
+    def list_usage(self) -> Dict[str, Any]:
+        """Returns the cluster-wide billable usage report across all tenants (admin key)."""
+        return self._request_json("GET", "/v1/usage")
+
+    def list_tenants(self) -> List[Dict[str, Any]]:
+        """Lists all known tenants sorted by name (admin key)."""
+        resp = self._request_json("GET", "/v1/tenants")
+        return resp.get("tenants", [])
+
+    def get_tenant(self, tenant: str) -> Dict[str, Any]:
+        """Returns document and storage volume metadata for `tenant`."""
+        return self._request_json("GET", f"/v1/tenants/{self._esc_tenant(tenant)}")
+
+    def delete_tenant(self, tenant: str) -> int:
+        """Deletes all documents and state for `tenant` (admin key)."""
+        resp = self._request_json("DELETE", f"/v1/tenants/{self._esc_tenant(tenant)}")
+        return int(resp.get("docs_deleted", 0))
+
+    def flush(self) -> Dict[str, Any]:
+        """Persists buffered writes to durable storage (admin key)."""
+        return self._request_json("POST", "/v1/flush")
+
+    def compact(self) -> Dict[str, Any]:
+        """Optimizes storage segments (admin key)."""
+        return self._request_json("POST", "/v1/compact")
+
+    def ready(self) -> Dict[str, Any]:
+        """Checks service readiness."""
+        return self._request_json("GET", "/v1/ready")
+
+    def health(self) -> Dict[str, Any]:
+        """Checks gateway health."""
+        return self._request_json("GET", "/v1/health")

massengine-1.1.3/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "massengine"
+version = "1.1.3"
+description = "Official Python SDK for the MassEngine vector and hybrid search database."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [
+  { name = "MassEngine", email = "dev@massengine.com" }
+]
+keywords = ["vector-database", "hybrid-search", "rag", "embeddings", "bm25", "massengine"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Database",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://massengine.com"
+Documentation = "https://massengine.com/docs"
+Repository = "https://github.com/massengine-dev/massengine-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["massengine"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/massengine",
+  "/tests",
+  "/LICENSE",
+  "/README.md",
+  "/pyproject.toml",
+]

massengine-1.1.3/tests/test_client.py

@@ -0,0 +1,237 @@
+"""Self-contained unit & integration test suite for the MassEngine Python SDK."""
+
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json
+import socket
+import threading
+import time
+import unittest
+
+from massengine import Doc, MassEngineClient, MassEngineError, SearchRequest, TenantQuota
+
+
+class _MockGatewayHandler(BaseHTTPRequestHandler):
+    last_user_agent: str = ""
+    redirect_target_url: str = ""
+
+    def log_message(self, format: str, *args: object) -> None:
+        return
+
+    def _send(self, code: int, payload: object, content_type: str = "application/json") -> None:
+        raw = payload if isinstance(payload, bytes) else json.dumps(payload).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(raw)))
+        self.end_headers()
+        self.wfile.write(raw)
+
+    def do_GET(self) -> None:
+        _MockGatewayHandler.last_user_agent = self.headers.get("User-Agent", "")
+        auth = self.headers.get("Authorization", "")
+        if self.path == "/v1/health":
+            self._send(200, {"status": "ok"})
+        elif self.path == "/v1/ready":
+            self._send(200, {"ready": True})
+        elif self.path == "/v1/tenants/redirect-me":
+            self.send_response(302)
+            self.send_header("Location", _MockGatewayHandler.redirect_target_url)
+            self.send_header("Content-Length", "0")
+            self.end_headers()
+        elif self.path == "/v1/tenants/oversized":
+            self._send(200, {"tenant": "oversized", "pad": "x" * 2048})
+        elif self.path.endswith("/usage"):
+            self._send(200, {"tenant": "acme", "plan": "pro", "live_docs": 2, "read_units": 4, "write_units": 3})
+        elif self.path.endswith("/export"):
+            ndjson = b'{"id":"py-1","vector":[1.0,0.0]}\n{"id":"py-2","vector":[0.0,1.0]}\n'
+            self._send(200, ndjson, "application/x-ndjson")
+        elif self.path.endswith("/docs/py-1"):
+            if auth == "Bearer revoked":
+                self._send(401, {"error": "unauthorized"})
+            else:
+                self._send(200, {"id": "py-1", "tenant": "acme", "metadata": {"tier": "gold"}})
+        else:
+            self._send(404, {"error": "not found"})
+
+    def do_PUT(self) -> None:
+        length = int(self.headers.get("Content-Length", "0"))
+        body = json.loads(self.rfile.read(length).decode("utf-8"))
+        self._send(200, {"tenant": "acme", "quota": body})
+
+    def do_POST(self) -> None:
+        length = int(self.headers.get("Content-Length", "0"))
+        raw = self.rfile.read(length).decode("utf-8")
+        if self.path == "/v1/flush":
+            time.sleep(0.15)
+            self._send(200, {"flushed": True})
+        elif self.path.endswith("/keys"):
+            self._send(200, {"tenant": "acme", "key": "mk_test_key_123"})
+        elif self.path.endswith("/ingest"):
+            body = json.loads(raw)
+            self._send(200, {"ingested": len(body["docs"]), "degraded": False})
+        elif self.path == "/v1/search":
+            self._send(200, {"hits": [{"id": "py-1", "doc_id": 1, "score": 0.99, "shard": 0}], "took_ms": 1.2})
+        elif self.path == "/v1/search/batch":
+            self._send(200, {"results": [{"hits": [{"id": "py-1"}]}, {"hits": [{"id": "py-2"}]}]})
+        else:
+            self._send(200, {"ok": True})
+
+    def do_PATCH(self) -> None:
+        length = int(self.headers.get("Content-Length", "0"))
+        body = json.loads(self.rfile.read(length).decode("utf-8"))
+        self._send(200, {"id": "py-2", "category": body.get("category", 0), "metadata": body.get("metadata", {})})
+
+    def do_DELETE(self) -> None:
+        self._send(200, {"deleted": True, "docs_deleted": 2, "revoked": True})
+
+
+class _RedirectTrapHandler(BaseHTTPRequestHandler):
+    contacted: bool = False
+    leaked_auth: str = ""
+
+    def log_message(self, format: str, *args: object) -> None:
+        return
+
+    def do_GET(self) -> None:
+        _RedirectTrapHandler.contacted = True
+        _RedirectTrapHandler.leaked_auth = self.headers.get("Authorization", "")
+        self.send_response(200)
+        self.end_headers()
+
+
+class TestMassEngineClient(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.trap_httpd = HTTPServer(("127.0.0.1", 0), _RedirectTrapHandler)
+        trap_port = cls.trap_httpd.server_address[1]
+        _MockGatewayHandler.redirect_target_url = f"http://127.0.0.1:{trap_port}/steal"
+        cls.trap_thread = threading.Thread(target=cls.trap_httpd.serve_forever, daemon=True)
+        cls.trap_thread.start()
+
+        cls.httpd = HTTPServer(("127.0.0.1", 0), _MockGatewayHandler)
+        port = cls.httpd.server_address[1]
+        cls.base_url = f"http://127.0.0.1:{port}"
+        cls.thread = threading.Thread(target=cls.httpd.serve_forever, daemon=True)
+        cls.thread.start()
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.httpd.shutdown()
+        cls.httpd.server_close()
+        cls.trap_httpd.shutdown()
+        cls.trap_httpd.server_close()
+
+    def test_sdk_lifecycle_and_user_agent(self) -> None:
+        admin = MassEngineClient(base_url=self.base_url, api_key="  admin-key  ")
+        self.assertEqual(admin.health()["status"], "ok")
+        self.assertEqual(_MockGatewayHandler.last_user_agent, "massengine-python/1.1.3")
+        self.assertTrue(admin.ready()["ready"])
+        self.assertNotIn("admin-key", repr(admin))
+
+        q = admin.set_tenant_quota("acme", TenantQuota(plan="pro", max_docs=100, max_qps=500.0))
+        self.assertEqual(q["plan"], "pro")
+        self.assertEqual(q["max_docs"], 100)
+
+        t_key = admin.create_tenant_key("acme")
+        self.assertTrue(t_key.startswith("mk_"))
+
+        client = MassEngineClient(base_url=self.base_url, api_key=t_key)
+        ing = client.ingest(
+            "acme",
+            [
+                Doc(id="py-1", vector=[1.0, 0.0], category=2, metadata={"tier": "gold"}),
+                Doc(id="py-2", vector=[0.0, 1.0], category=3, metadata={"tier": "silver"}),
+            ],
+        )
+        self.assertEqual(ing["ingested"], 2)
+
+        sr = client.search(
+            "acme",
+            vector=[1.0, 0.0],
+            k=5,
+            metadata_filter={"tier": {"$eq": "gold"}},
+        )
+        self.assertEqual(len(sr["hits"]), 1)
+        self.assertEqual(sr["hits"][0]["id"], "py-1")
+
+        bs = client.batch_search(
+            [
+                SearchRequest(tenant="acme", vector=[1.0, 0.0], k=1),
+                SearchRequest(tenant="acme", vector=[0.0, 1.0], k=1),
+            ]
+        )
+        self.assertEqual(len(bs["results"]), 2)
+
+        patched = client.patch_doc("acme", "py-2", category=9, metadata={"tier": "gold"})
+        self.assertEqual(patched["category"], 9)
+
+        exported = client.export_tenant("acme")
+        self.assertEqual(len(exported), 2)
+
+        usage = client.get_tenant_usage("acme")
+        self.assertEqual(usage["plan"], "pro")
+        self.assertEqual(usage["live_docs"], 2)
+
+        revoked_client = MassEngineClient(base_url=self.base_url, api_key="revoked")
+        with self.assertRaises(MassEngineError) as ctx:
+            revoked_client.get_doc("acme", "py-1")
+        self.assertEqual(ctx.exception.status_code, 401)
+
+    def test_dot_segment_and_control_char_rejection(self) -> None:
+        client = MassEngineClient(base_url=self.base_url, api_key="mk_valid")
+        for bad_tenant in ["", ".", "..", "acme/evil", "acme\\evil", "acme\x00", "acme\n", "acme\x7f", 123]:
+            with self.assertRaises(ValueError):
+                client.get_tenant(bad_tenant)  # type: ignore[arg-type]
+            with self.assertRaises(ValueError):
+                client.get_doc(bad_tenant, "doc-1")  # type: ignore[arg-type]
+
+        for bad_doc_id in ["", ".", "..", "batch-get", "doc\x00", "doc\r\n", "doc\x7f", None]:
+            with self.assertRaises(ValueError):
+                client.get_doc("acme", bad_doc_id)  # type: ignore[arg-type]
+            with self.assertRaises(ValueError):
+                client.delete_doc("acme", bad_doc_id)  # type: ignore[arg-type]
+
+    def test_redirect_blocked_no_auth_leak(self) -> None:
+        _RedirectTrapHandler.contacted = False
+        _RedirectTrapHandler.leaked_auth = ""
+        client = MassEngineClient(base_url=self.base_url, api_key="mk_secret_token")
+        with self.assertRaises(MassEngineError) as ctx:
+            client.get_tenant("redirect-me")
+        self.assertEqual(ctx.exception.status_code, 302)
+        self.assertFalse(_RedirectTrapHandler.contacted)
+        self.assertEqual(_RedirectTrapHandler.leaked_auth, "")
+
+    def test_invalid_url_and_apikey_no_leak(self) -> None:
+        for bad_url in ["ftp://example.com", "file:///etc/passwd", "javascript:alert(1)", "http://u:p@example.com"]:
+            with self.assertRaises(ValueError):
+                MassEngineClient(base_url=bad_url)
+
+        secret = "mk_top_secret_value_999"
+        for bad_key in [
+            f"{secret}\r\nX-Injected: 1",
+            f"{secret}\n",
+            f"{secret}\x00",
+            f"{secret} space",
+            "   ",
+        ]:
+            with self.assertRaises(ValueError) as ctx:
+                MassEngineClient(base_url=self.base_url, api_key=bad_key)
+            self.assertNotIn(secret, str(ctx.exception))
+
+    def test_timeout_and_max_response_bytes(self) -> None:
+        small_client = MassEngineClient(base_url=self.base_url, max_response_bytes=128)
+        with self.assertRaises(MassEngineError) as ctx:
+            small_client.get_tenant("oversized")
+        self.assertIn("max_response_bytes", str(ctx.exception))
+
+        tiny_export_client = MassEngineClient(base_url=self.base_url, max_response_bytes=20)
+        with self.assertRaises(MassEngineError) as ctx2:
+            tiny_export_client.export_tenant("acme")
+        self.assertIn("max_response_bytes", str(ctx2.exception))
+
+        fast_client = MassEngineClient(base_url=self.base_url, timeout=0.03)
+        with self.assertRaises((TimeoutError, socket.timeout, OSError)):
+            fast_client.flush()
+
+
+if __name__ == "__main__":
+    unittest.main()