vectorizer-sdk 3.0.0__tar.gz → 3.2.0__tar.gz

{vectorizer_sdk-3.0.0 → vectorizer_sdk-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vectorizer_sdk
-Version: 3.0.0
+Version: 3.2.0
 Summary: Python SDK for Vectorizer - Semantic search, vector operations, and the VectorizerRPC binary transport (default in v3.x)
 Author-email: HiveLLM Team <team@hivellm.org>
 License: Apache-2.0
@@ -58,9 +58,38 @@ Dynamic: license-file
 A comprehensive Python SDK for the Vectorizer semantic search service.
 
 **Package**: `vectorizer_sdk` (PEP 625 compliant)
-**Version**: 3.0.0
+**Version**: 3.2.0
 **PyPI**: https://pypi.org/project/vectorizer-sdk/
 
+## v3.2 — backpressure-aware client (HTTP 429 + `Retry-After`)
+
+The REST `VectorizerClient` honors server-side bulk-upsert
+backpressure shipped in Vectorizer 3.2.0
+([#263](https://github.com/hivellm/vectorizer/issues/263)). On HTTP
+`429 Too Many Requests` the client parses `Retry-After` (seconds
+form, 1 s default, 30 s cap), sleeps, and retries up to 3 times
+before raising a typed `RateLimitError`. Pre-3.2.0 clients bounced
+429s into a generic 5xx and lost the retry budget. Identical
+semantics ship in every first-party SDK (Rust, Python, TypeScript,
+Go, C#) — see `tests/test_retry_after_parse.py`.
+
+## v3.1 — `/insert_vectors` + stable client-id upserts
+
+- `insert_vectors(collection, vectors, public_key=None)` — bulk-
+  insert pre-computed embeddings with caller-supplied vector ids.
+  Skips the embedding pipeline entirely.
+- `insert` / `insert_texts`: the request `id` is now used verbatim
+  as the stored `Vector.id` (non-chunked) or as `<id>#<chunk_index>`
+  (chunked). Re-running the same payload upserts in place instead
+  of duplicating.
+- Chunked vectors expose a flat payload layout (`{content,
+  file_path, chunk_index, parent_id, ...user_metadata}`). Legacy
+  nested payloads from ≤ 3.0.x stay readable during the deprecation
+  window.
+
+Client-id contract: non-empty, length ≤ 256, no leading/trailing
+whitespace, must not contain `#`.
+
 ## v3.0 — VectorizerRPC is the default transport
 
 Starting with v3.0, the recommended transport is **VectorizerRPC**: a
@@ -79,6 +108,8 @@ import vectorizer_sdk
 
 async def main():
     client = await vectorizer_sdk.connect_async("vectorizer://127.0.0.1:15503")
+    # `hello` and `search_basic` are RPC-only (not available on the legacy
+    # REST `VectorizerClient`).
     await client.hello(vectorizer_sdk.HelloPayload(client_name="my-app"))
     print(await client.list_collections())
     hits = await client.search_basic("docs", "vector database", limit=5)
@@ -140,7 +171,7 @@ for a runnable end-to-end example.
 pip install vectorizer-sdk
 
 # Or specific version
-pip install vectorizer-sdk==3.0.0
+pip install vectorizer-sdk==3.2.0
 ```
 
 ## Package Layout (v3.x)
@@ -477,6 +508,11 @@ related = await client.get_related_files(
 
 ### Summarization Operations
 
+> WARNING: The `/summarize/*` REST endpoints are documented but not yet wired
+> server-side (see `DOC_GAP_ANALYSIS`). The SDK methods below
+> (`summarize_text`, `summarize_context`) will fail until server wiring is
+> complete.
+
 #### Summarize Text
 Summarize text using various methods:
 
@@ -509,6 +545,11 @@ summary = await client.summarize_context(
 
 ### Workspace Management
 
+> WARNING: `add_workspace`, `list_workspaces`, and `remove_workspace` are
+> exposed via the REST transport through dynamic `__getattr__` delegation,
+> but they are not first-class SDK methods yet. They work at runtime but
+> won't autocomplete in IDEs. A future release will add explicit methods.
+
 #### Add Workspace
 Add a new workspace:
 
@@ -537,6 +578,11 @@ await client.remove_workspace(
 
 ### Backup Operations
 
+> WARNING: `create_backup`, `list_backups`, and `restore_backup` are
+> exposed via the REST transport through dynamic `__getattr__` delegation,
+> but they are not first-class SDK methods yet. They work at runtime but
+> won't autocomplete in IDEs. A future release will add explicit methods.
+
 #### Create Backup
 Create a backup of collections:
 
@@ -664,8 +710,11 @@ await client.create_collection("documents", dimension=768)
 await client.insert_texts("documents", [
     {"id": "doc1", "text": "Sample document", "metadata": {"source": "api"}}
 ])
-await client.update_vector("documents", "doc1", metadata={"updated": True})
-await client.delete_vector("documents", "doc1")
+# Update-via-reinsert: re-call `insert_texts` with the same id to replace the record.
+await client.insert_texts("documents", [
+    {"id": "doc1", "text": "Sample document (updated)", "metadata": {"updated": True}}
+])
+await client.delete_vectors("documents", ["doc1"])
 
 # Reads automatically go to replicas (load balanced)
 results = await client.search_vectors("documents", query="sample", limit=10)
@@ -702,7 +751,7 @@ The SDK automatically classifies operations:
 
 | Operation Type | Routed To | Methods |
 |---------------|-----------|---------|
-| **Writes** | Always Master | `insert_texts`, `insert_vectors`, `update_vector`, `delete_vector`, `create_collection`, `delete_collection` |
+| **Writes** | Always Master | `insert_texts`, `insert_vectors`, `delete_vectors`, `create_collection`, `delete_collection` |
 | **Reads** | Based on `read_preference` | `search_vectors`, `get_vector`, `list_collections`, `intelligent_search`, `semantic_search`, `hybrid_search` |
 
 #### Standalone Mode (Single Node)

{vectorizer_sdk-3.0.0 → vectorizer_sdk-3.2.0}/README.md

@@ -7,9 +7,38 @@
 A comprehensive Python SDK for the Vectorizer semantic search service.
 
 **Package**: `vectorizer_sdk` (PEP 625 compliant)
-**Version**: 3.0.0
+**Version**: 3.2.0
 **PyPI**: https://pypi.org/project/vectorizer-sdk/
 
+## v3.2 — backpressure-aware client (HTTP 429 + `Retry-After`)
+
+The REST `VectorizerClient` honors server-side bulk-upsert
+backpressure shipped in Vectorizer 3.2.0
+([#263](https://github.com/hivellm/vectorizer/issues/263)). On HTTP
+`429 Too Many Requests` the client parses `Retry-After` (seconds
+form, 1 s default, 30 s cap), sleeps, and retries up to 3 times
+before raising a typed `RateLimitError`. Pre-3.2.0 clients bounced
+429s into a generic 5xx and lost the retry budget. Identical
+semantics ship in every first-party SDK (Rust, Python, TypeScript,
+Go, C#) — see `tests/test_retry_after_parse.py`.
+
+## v3.1 — `/insert_vectors` + stable client-id upserts
+
+- `insert_vectors(collection, vectors, public_key=None)` — bulk-
+  insert pre-computed embeddings with caller-supplied vector ids.
+  Skips the embedding pipeline entirely.
+- `insert` / `insert_texts`: the request `id` is now used verbatim
+  as the stored `Vector.id` (non-chunked) or as `<id>#<chunk_index>`
+  (chunked). Re-running the same payload upserts in place instead
+  of duplicating.
+- Chunked vectors expose a flat payload layout (`{content,
+  file_path, chunk_index, parent_id, ...user_metadata}`). Legacy
+  nested payloads from ≤ 3.0.x stay readable during the deprecation
+  window.
+
+Client-id contract: non-empty, length ≤ 256, no leading/trailing
+whitespace, must not contain `#`.
+
 ## v3.0 — VectorizerRPC is the default transport
 
 Starting with v3.0, the recommended transport is **VectorizerRPC**: a
@@ -28,6 +57,8 @@ import vectorizer_sdk
 
 async def main():
     client = await vectorizer_sdk.connect_async("vectorizer://127.0.0.1:15503")
+    # `hello` and `search_basic` are RPC-only (not available on the legacy
+    # REST `VectorizerClient`).
     await client.hello(vectorizer_sdk.HelloPayload(client_name="my-app"))
     print(await client.list_collections())
     hits = await client.search_basic("docs", "vector database", limit=5)
@@ -89,7 +120,7 @@ for a runnable end-to-end example.
 pip install vectorizer-sdk
 
 # Or specific version
-pip install vectorizer-sdk==3.0.0
+pip install vectorizer-sdk==3.2.0
 ```
 
 ## Package Layout (v3.x)
@@ -426,6 +457,11 @@ related = await client.get_related_files(
 
 ### Summarization Operations
 
+> WARNING: The `/summarize/*` REST endpoints are documented but not yet wired
+> server-side (see `DOC_GAP_ANALYSIS`). The SDK methods below
+> (`summarize_text`, `summarize_context`) will fail until server wiring is
+> complete.
+
 #### Summarize Text
 Summarize text using various methods:
 
@@ -458,6 +494,11 @@ summary = await client.summarize_context(
 
 ### Workspace Management
 
+> WARNING: `add_workspace`, `list_workspaces`, and `remove_workspace` are
+> exposed via the REST transport through dynamic `__getattr__` delegation,
+> but they are not first-class SDK methods yet. They work at runtime but
+> won't autocomplete in IDEs. A future release will add explicit methods.
+
 #### Add Workspace
 Add a new workspace:
 
@@ -486,6 +527,11 @@ await client.remove_workspace(
 
 ### Backup Operations
 
+> WARNING: `create_backup`, `list_backups`, and `restore_backup` are
+> exposed via the REST transport through dynamic `__getattr__` delegation,
+> but they are not first-class SDK methods yet. They work at runtime but
+> won't autocomplete in IDEs. A future release will add explicit methods.
+
 #### Create Backup
 Create a backup of collections:
 
@@ -613,8 +659,11 @@ await client.create_collection("documents", dimension=768)
 await client.insert_texts("documents", [
     {"id": "doc1", "text": "Sample document", "metadata": {"source": "api"}}
 ])
-await client.update_vector("documents", "doc1", metadata={"updated": True})
-await client.delete_vector("documents", "doc1")
+# Update-via-reinsert: re-call `insert_texts` with the same id to replace the record.
+await client.insert_texts("documents", [
+    {"id": "doc1", "text": "Sample document (updated)", "metadata": {"updated": True}}
+])
+await client.delete_vectors("documents", ["doc1"])
 
 # Reads automatically go to replicas (load balanced)
 results = await client.search_vectors("documents", query="sample", limit=10)
@@ -651,7 +700,7 @@ The SDK automatically classifies operations:
 
 | Operation Type | Routed To | Methods |
 |---------------|-----------|---------|
-| **Writes** | Always Master | `insert_texts`, `insert_vectors`, `update_vector`, `delete_vector`, `create_collection`, `delete_collection` |
+| **Writes** | Always Master | `insert_texts`, `insert_vectors`, `delete_vectors`, `create_collection`, `delete_collection` |
 | **Reads** | Based on `read_preference` | `search_vectors`, `get_vector`, `list_collections`, `intelligent_search`, `semantic_search`, `hybrid_search` |
 
 #### Standalone Mode (Single Node)

{vectorizer_sdk-3.0.0 → vectorizer_sdk-3.2.0}/pyproject.toml

@@ -1,110 +1,110 @@
-[build-system]
-requires = ["setuptools>=61.0", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "vectorizer_sdk"
-version = "3.0.0"
-description = "Python SDK for Vectorizer - Semantic search, vector operations, and the VectorizerRPC binary transport (default in v3.x)"
-readme = "README.md"
-requires-python = ">=3.8"
-license = {text = "Apache-2.0"}
-authors = [
-    {name = "HiveLLM Team", email = "team@hivellm.org"}
-]
-keywords = [
-    "vectorizer",
-    "semantic-search",
-    "embeddings",
-    "machine-learning",
-    "ai",
-    "search",
-    "vectors",
-    "similarity",
-    "hivellm",
-    "umicp"
-]
-classifiers = [
-    "Development Status :: 5 - Production/Stable",
-    "Intended Audience :: Developers",
-    "Operating System :: OS Independent",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Topic :: Software Development :: Libraries :: Python Modules",
-    "Topic :: Scientific/Engineering :: Artificial Intelligence",
-    "Topic :: Text Processing :: Indexing",
-    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
-]
-
-dependencies = [
-    "aiohttp>=3.10.0",
-    "msgpack>=1.1.0",
-]
-
-[project.optional-dependencies]
-umicp = [
-    "umicp-python>=0.1.3",
-]
-dev = [
-    "pytest>=8.0.0",
-    "pytest-asyncio>=0.24.0",
-    "pytest-cov>=5.0.0",
-    "black>=25.0.0",
-    "isort>=5.13.0",
-    "flake8>=7.0.0",
-    "mypy>=1.11.0",
-    "pre-commit>=4.0.0",
-]
-docs = [
-    "sphinx>=7.0.0",
-    "sphinx-rtd-theme>=2.0.0",
-    "myst-parser>=3.0.0",
-]
-test = [
-    "pytest>=8.0.0",
-    "pytest-asyncio>=0.24.0",
-    "pytest-cov>=5.0.0",
-    "httpx>=0.27.0",
-]
-
-[project.urls]
-Homepage = "https://github.com/hivellm/vectorizer"
-Documentation = "https://github.com/hivellm/vectorizer/tree/main/docs"
-Repository = "https://github.com/hivellm/vectorizer"
-Issues = "https://github.com/hivellm/vectorizer/issues"
-
-[project.scripts]
-vectorizer-cli = "cli:main"
-
-[tool.setuptools.packages.find]
-include = ["*"]
-exclude = ["tests*", "examples*", "docs*"]
-
-[tool.setuptools.package-data]
-"*" = ["py.typed"]
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]
-python_files = ["test_*.py"]
-python_classes = ["Test*"]
-python_functions = ["test_*"]
-
-[tool.black]
-line-length = 100
-target-version = ['py38', 'py39', 'py310', 'py311', 'py312']
-
-[tool.isort]
-profile = "black"
-line_length = 100
-
-[tool.mypy]
-python_version = "3.8"
-warn_return_any = true
-warn_unused_configs = true
-disallow_untyped_defs = false
-
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vectorizer_sdk"
+version = "3.2.0"
+description = "Python SDK for Vectorizer - Semantic search, vector operations, and the VectorizerRPC binary transport (default in v3.x)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "Apache-2.0"}
+authors = [
+    {name = "HiveLLM Team", email = "team@hivellm.org"}
+]
+keywords = [
+    "vectorizer",
+    "semantic-search",
+    "embeddings",
+    "machine-learning",
+    "ai",
+    "search",
+    "vectors",
+    "similarity",
+    "hivellm",
+    "umicp"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Indexing",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+
+dependencies = [
+    "aiohttp>=3.10.0",
+    "msgpack>=1.1.0",
+]
+
+[project.optional-dependencies]
+umicp = [
+    "umicp-python>=0.1.3",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=5.0.0",
+    "black>=25.0.0",
+    "isort>=5.13.0",
+    "flake8>=7.0.0",
+    "mypy>=1.11.0",
+    "pre-commit>=4.0.0",
+]
+docs = [
+    "sphinx>=7.0.0",
+    "sphinx-rtd-theme>=2.0.0",
+    "myst-parser>=3.0.0",
+]
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=5.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/hivellm/vectorizer"
+Documentation = "https://github.com/hivellm/vectorizer/tree/main/docs"
+Repository = "https://github.com/hivellm/vectorizer"
+Issues = "https://github.com/hivellm/vectorizer/issues"
+
+[project.scripts]
+vectorizer-cli = "cli:main"
+
+[tool.setuptools.packages.find]
+include = ["*"]
+exclude = ["tests*", "examples*", "docs*"]
+
+[tool.setuptools.package-data]
+"*" = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.black]
+line-length = 100
+target-version = ['py38', 'py39', 'py310', 'py311', 'py312']
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+

vectorizer_sdk-3.2.0/tests/test_retry_after_parse.py

@@ -0,0 +1,51 @@
+"""Retry-After header parser tests for the Python SDK (issue #263, phase9 §7).
+
+The full retry loop is exercised end-to-end at the server level by
+``crates/vectorizer-server/tests/backpressure_429.rs``; here we only
+lock in the value-parsing edges that determine how aggressively the
+SDK backs off.
+
+These constants are kept in sync with ``utils/http_client.py``:
+
+  - missing/unparseable header  -> 1 s default
+  - ``Retry-After: 0``          -> 1 s default (never busy-loop)
+  - capped at 30 s so a misconfigured server cannot pin the client
+"""
+
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from utils.http_client import _parse_retry_after  # type: ignore[import-not-found]
+
+
+class TestRetryAfterParse(unittest.TestCase):
+    def test_missing_header_returns_default(self) -> None:
+        self.assertEqual(_parse_retry_after(None), 1)
+
+    def test_empty_or_whitespace_returns_default(self) -> None:
+        self.assertEqual(_parse_retry_after(""), 1)
+        self.assertEqual(_parse_retry_after("   "), 1)
+
+    def test_zero_returns_default_to_avoid_busy_loop(self) -> None:
+        self.assertEqual(_parse_retry_after("0"), 1)
+
+    def test_unparseable_string_returns_default(self) -> None:
+        self.assertEqual(_parse_retry_after("not-a-number"), 1)
+
+    def test_small_values_pass_through_verbatim(self) -> None:
+        self.assertEqual(_parse_retry_after("3"), 3)
+        self.assertEqual(_parse_retry_after("7"), 7)
+        self.assertEqual(_parse_retry_after(" 5 "), 5)
+
+    def test_large_values_are_capped_at_30s(self) -> None:
+        # If this assertion ever flips, audit _RETRY_AFTER_MAX_SECONDS
+        # in utils/http_client.py first.
+        self.assertEqual(_parse_retry_after("3600"), 30)
+        self.assertEqual(_parse_retry_after("31"), 30)
+
+
+if __name__ == "__main__":
+    unittest.main()

vectorizer_sdk-3.2.0/utils/http_client.py

@@ -0,0 +1,212 @@
+"""
+HTTP client utility for making API requests using aiohttp.
+"""
+
+from typing import Optional, Dict, Any
+import aiohttp
+import asyncio
+import logging
+
+try:
+    from ..exceptions import (
+        NetworkError,
+        ServerError,
+        AuthenticationError,
+        RateLimitError,
+    )
+except ImportError:
+    from exceptions import (
+        NetworkError,
+        ServerError,
+        AuthenticationError,
+        RateLimitError,
+    )
+
+# Issue #263: cap Retry-After respect at this many seconds so a
+# misconfigured server can't pin a client into a half-hour sleep.
+_RETRY_AFTER_MAX_SECONDS = 30
+# Floor for parsed Retry-After so a `0` or missing header still yields
+# a noticeable backoff rather than busy-looping the server.
+_RETRY_AFTER_DEFAULT_SECONDS = 1
+
+logger = logging.getLogger(__name__)
+
+
+class HTTPClient:
+    """HTTP transport client."""
+    
+    def __init__(
+        self,
+        base_url: str = "http://localhost:15002",
+        api_key: Optional[str] = None,
+        timeout: int = 30,
+        max_retries: int = 3
+    ):
+        """
+        Initialize HTTP client.
+        
+        Args:
+            base_url: Base URL for HTTP API
+            api_key: API key for authentication
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retry attempts
+        """
+        self.base_url = base_url.rstrip('/')
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._session: Optional[aiohttp.ClientSession] = None
+    
+    async def _ensure_session(self):
+        """Ensure aiohttp session is created."""
+        if self._session is None or self._session.closed:
+            headers = {"Content-Type": "application/json"}
+            if self.api_key:
+                # JWT shape → `Authorization: Bearer`; anything else
+                # (raw API keys from `POST /auth/keys`) → `X-API-Key`.
+                # Server middleware won't fall back Bearer → api_key,
+                # so routing has to happen client-side.
+                parts = self.api_key.split(".")
+                if len(parts) == 3 and all(p for p in parts):
+                    headers["Authorization"] = f"Bearer {self.api_key}"
+                else:
+                    headers["X-API-Key"] = self.api_key
+            
+            timeout_config = aiohttp.ClientTimeout(total=self.timeout)
+            self._session = aiohttp.ClientSession(
+                headers=headers,
+                timeout=timeout_config
+            )
+    
+    async def close(self):
+        """Close the HTTP session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+            self._session = None
+    
+    async def request(
+        self,
+        method: str,
+        path: str,
+        data: Optional[Dict[str, Any]] = None
+    ) -> Any:
+        """
+        Make an HTTP request.
+
+        Honors `Retry-After` on 429 responses (issue #263): the client
+        sleeps for the header's value (capped) and retries up to
+        ``max_retries`` times. After exhaustion a ``RateLimitError`` is
+        raised so callers can surface the back-pressure to the user.
+
+        Args:
+            method: HTTP method
+            path: API endpoint path
+            data: Request data
+
+        Returns:
+            Response data
+        """
+        await self._ensure_session()
+
+        url = f"{self.base_url}{path}"
+        attempts_remaining = self.max_retries
+        last_429_text: Optional[str] = None
+
+        while True:
+            try:
+                async with self._session.request(
+                    method,
+                    url,
+                    json=data if data else None,
+                ) as response:
+                    if response.status == 429:
+                        last_429_text = await response.text()
+                        if attempts_remaining <= 0:
+                            raise RateLimitError(
+                                f"HTTP 429 after {self.max_retries} retries: "
+                                f"{last_429_text}"
+                            )
+                        delay = _parse_retry_after(
+                            response.headers.get("Retry-After")
+                        )
+                        logger.info(
+                            "Vectorizer 429 — sleeping %.1fs before retry "
+                            "(remaining attempts=%d)",
+                            delay,
+                            attempts_remaining,
+                        )
+                        attempts_remaining -= 1
+                        await asyncio.sleep(delay)
+                        continue
+
+                    if response.status >= 400:
+                        error_text = await response.text()
+                        raise self._handle_error(response.status, error_text)
+
+                    content_type = response.headers.get('Content-Type', '')
+                    if 'application/json' in content_type:
+                        return await response.json()
+                    return await response.text()
+
+            except (ServerError, AuthenticationError, RateLimitError):
+                raise
+            except aiohttp.ClientError as e:
+                raise NetworkError(f"HTTP request failed: {e}")
+            except asyncio.TimeoutError:
+                raise NetworkError("Request timeout")
+            except Exception as e:
+                raise NetworkError(f"Unknown error: {e}")
+    
+    async def get(self, path: str) -> Any:
+        """Make a GET request."""
+        return await self.request("GET", path)
+    
+    async def post(self, path: str, data: Optional[Dict[str, Any]] = None) -> Any:
+        """Make a POST request."""
+        return await self.request("POST", path, data)
+    
+    async def put(self, path: str, data: Optional[Dict[str, Any]] = None) -> Any:
+        """Make a PUT request."""
+        return await self.request("PUT", path, data)
+    
+    async def delete(self, path: str) -> Any:
+        """Make a DELETE request."""
+        return await self.request("DELETE", path)
+    
+    def _handle_error(self, status: int, error_text: str) -> Exception:
+        """Handle HTTP errors and convert to appropriate exceptions."""
+        message = f"HTTP {status}: {error_text}"
+
+        if status == 401:
+            return AuthenticationError(message)
+        elif status == 403:
+            return AuthenticationError("Access forbidden")
+        elif status == 404:
+            return ServerError("Resource not found")
+        elif status == 429:
+            # 429 is handled in `request()` via Retry-After; reaching
+            # here means the caller bypassed retry handling, so
+            # surface a typed RateLimitError instead of a generic 5xx.
+            return RateLimitError(message)
+        elif status in (500, 502, 503, 504):
+            return ServerError(message)
+        else:
+            return ServerError(message)
+
+
+def _parse_retry_after(value: Optional[str]) -> float:
+    """Parse a ``Retry-After`` header value (seconds form only).
+
+    Returns a sane default + caps an unreasonably large server hint
+    so a misconfigured server can't pin a client into a long sleep.
+    """
+    if not value:
+        return _RETRY_AFTER_DEFAULT_SECONDS
+    try:
+        seconds = float(value.strip())
+    except ValueError:
+        return _RETRY_AFTER_DEFAULT_SECONDS
+    if seconds <= 0:
+        return _RETRY_AFTER_DEFAULT_SECONDS
+    return min(seconds, _RETRY_AFTER_MAX_SECONDS)
+

{vectorizer_sdk-3.0.0 → vectorizer_sdk-3.2.0}/vectorizer/_base.py

@@ -112,6 +112,22 @@ class RestTransport(Transport):
         await self._http.close()
 
 
+def _looks_like_jwt(token: str) -> bool:
+    """Cheap JWT shape sniff: three non-empty base64url-encoded segments
+    joined by ``.``. Raw Vectorizer API keys (from ``POST /auth/keys``)
+    are a single alphanumeric string and fail this check, so they get
+    routed to ``X-API-Key`` rather than ``Authorization: Bearer``.
+
+    The server's auth middleware treats every ``Bearer`` string as a
+    JWT and never falls back to the API-key validator, so sending a
+    raw key under ``Bearer`` silently 401s. This sniff keeps the public
+    ``api_key`` config field unchanged while routing each credential
+    down the header the server actually accepts.
+    """
+    parts = token.split(".")
+    return len(parts) == 3 and all(p for p in parts)
+
+
 @dataclass
 class AuthState:
     """Bearer-token + API-key state shared across surface clients."""
@@ -121,7 +137,9 @@ class AuthState:
     def headers(self) -> dict:
         if not self.api_key:
             return {}
-        return {"Authorization": f"Bearer {self.api_key}"}
+        if _looks_like_jwt(self.api_key):
+            return {"Authorization": f"Bearer {self.api_key}"}
+        return {"X-API-Key": self.api_key}
 
 
 @dataclass

{vectorizer_sdk-3.0.0 → vectorizer_sdk-3.2.0}/vectorizer/auth.py

@@ -22,7 +22,8 @@ class AuthClient(_ApiBase):
 
         from vectorizer import RestTransport, AuthClient
         auth = AuthClient(RestTransport("http://localhost:15002"), api_key="sk-...")
-        print(auth.headers())  # -> {"Authorization": "Bearer sk-..."}
+        print(auth.headers())  # raw API key → {"X-API-Key": "sk-..."}
+        #                      # JWT            → {"Authorization": "Bearer <jwt>"}
 
     In the :class:`vectorizer.VectorizerClient` facade this is the
     surface that owns the API key and surfaces it via :attr:`api_key`
@@ -47,3 +48,28 @@ class AuthClient(_ApiBase):
     def set_api_key(self, api_key: Optional[str]) -> None:
         """Replace the current API key — affects future request headers."""
         self._auth.api_key = api_key
+
+    async def login(self, username: str, password: str) -> str:
+        """Exchange ``(username, password)`` for a JWT via
+        ``POST /auth/login`` and return the raw ``access_token``.
+
+        The token is **not** stored on ``self`` — to use it for
+        subsequent requests, call :meth:`set_api_key` with the token
+        (``AuthState.headers`` sniffs the JWT shape and routes it onto
+        ``Authorization: Bearer …`` automatically).
+
+        When the server runs with ``auth.enabled: false`` this
+        endpoint returns 404 — dev servers without auth don't need
+        to call :meth:`login` at all.
+        """
+        data = await self._transport.post(
+            "/auth/login",
+            {"username": username, "password": password},
+        )
+        token = data.get("access_token") if isinstance(data, dict) else None
+        if not isinstance(token, str) or not token:
+            raise ValueError(
+                "login response missing `access_token`; server payload: "
+                f"{data!r}"
+            )
+        return token

{vectorizer_sdk-3.0.0 → vectorizer_sdk-3.2.0}/vectorizer/client.py

@@ -274,7 +274,16 @@ class VectorizerClient:
             if self._session is None or self._session.closed:
                 headers = {}
                 if self.api_key:
-                    headers["Authorization"] = f"Bearer {self.api_key}"
+                    # Route JWTs to `Authorization: Bearer` and raw API
+                    # keys to `X-API-Key`. Server middleware treats
+                    # every Bearer string as a JWT and won't fall back
+                    # to the API-key validator — sending a raw key as
+                    # Bearer silently 401s on every gated route.
+                    from ._base import _looks_like_jwt
+                    if _looks_like_jwt(self.api_key):
+                        headers["Authorization"] = f"Bearer {self.api_key}"
+                    else:
+                        headers["X-API-Key"] = self.api_key
 
                 timeout = aiohttp.ClientTimeout(total=self.timeout)
                 self._session = aiohttp.ClientSession(

{vectorizer_sdk-3.0.0 → vectorizer_sdk-3.2.0}/vectorizer/vectors.py

@@ -112,6 +112,15 @@ class VectorsClient(_ApiBase):
         """
         Get a specific vector by ID.
 
+        .. warning::
+           **Server caveat (observed on ``hivehub/vectorizer:3.0.x``):**
+           this endpoint currently returns HTTP 200 with a synthetic
+           uniform-vector payload (``[0.1, 0.1, ...]``) even for ids
+           that don't exist. Callers that need real miss detection
+           should probe via :meth:`list_vectors` or search and not
+           trust a successful response as proof of existence until
+           the server fix ships.
+
         Args:
             collection: Collection name
             vector_id: Vector ID
@@ -125,6 +134,44 @@ class VectorsClient(_ApiBase):
             ServerError: If service returns error
         """
         return await self._transport.get(f"/collections/{collection}/vectors/{vector_id}")
+
+    async def insert_text_batch(
+        self,
+        collection: str,
+        texts: List[Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Insert a batch of **texts** into a collection. The server
+        embeds each entry with the collection's configured provider
+        (BM25 default, FastEmbed ONNX when selected in ``config.yml``).
+
+        Wire contract: ``POST /insert_texts`` with
+        ``{"collection": ..., "texts": [...]}`` payload. The collection
+        is a top-level JSON field, **not** a path segment.
+
+        Per-entry ``id``: the server **reassigns** every inserted
+        vector a server-generated UUID. The original client id
+        round-trips on the response as ``client_id``. Callers that
+        need idempotency by client id should key off the returned
+        ``results[].client_id``, not the server-assigned UUID.
+
+        Distinct from :meth:`insert_texts` on this class, which takes
+        :class:`Vector` objects with pre-computed embeddings and hits
+        the raw-vector write path.
+
+        Args:
+            collection: Collection name.
+            texts: Entries of shape
+                ``{"id": "...", "text": "...", "metadata": {...}}``.
+
+        Returns:
+            Raw ``/insert_texts`` response dict with fields
+            ``collection``, ``count``, ``inserted``, ``failed``,
+            ``results``.
+        """
+        if not texts:
+            raise ValidationError("texts list cannot be empty")
+        payload = {"collection": collection, "texts": texts}
+        return await self._transport.post("/insert_texts", data=payload)
     async def delete_vectors(self, collection: str, vector_ids: List[str]) -> bool:
         """
         Delete vectors from a collection.

{vectorizer_sdk-3.0.0 → vectorizer_sdk-3.2.0}/vectorizer_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vectorizer_sdk
-Version: 3.0.0
+Version: 3.2.0
 Summary: Python SDK for Vectorizer - Semantic search, vector operations, and the VectorizerRPC binary transport (default in v3.x)
 Author-email: HiveLLM Team <team@hivellm.org>
 License: Apache-2.0
@@ -58,9 +58,38 @@ Dynamic: license-file
 A comprehensive Python SDK for the Vectorizer semantic search service.
 
 **Package**: `vectorizer_sdk` (PEP 625 compliant)
-**Version**: 3.0.0
+**Version**: 3.2.0
 **PyPI**: https://pypi.org/project/vectorizer-sdk/
 
+## v3.2 — backpressure-aware client (HTTP 429 + `Retry-After`)
+
+The REST `VectorizerClient` honors server-side bulk-upsert
+backpressure shipped in Vectorizer 3.2.0
+([#263](https://github.com/hivellm/vectorizer/issues/263)). On HTTP
+`429 Too Many Requests` the client parses `Retry-After` (seconds
+form, 1 s default, 30 s cap), sleeps, and retries up to 3 times
+before raising a typed `RateLimitError`. Pre-3.2.0 clients bounced
+429s into a generic 5xx and lost the retry budget. Identical
+semantics ship in every first-party SDK (Rust, Python, TypeScript,
+Go, C#) — see `tests/test_retry_after_parse.py`.
+
+## v3.1 — `/insert_vectors` + stable client-id upserts
+
+- `insert_vectors(collection, vectors, public_key=None)` — bulk-
+  insert pre-computed embeddings with caller-supplied vector ids.
+  Skips the embedding pipeline entirely.
+- `insert` / `insert_texts`: the request `id` is now used verbatim
+  as the stored `Vector.id` (non-chunked) or as `<id>#<chunk_index>`
+  (chunked). Re-running the same payload upserts in place instead
+  of duplicating.
+- Chunked vectors expose a flat payload layout (`{content,
+  file_path, chunk_index, parent_id, ...user_metadata}`). Legacy
+  nested payloads from ≤ 3.0.x stay readable during the deprecation
+  window.
+
+Client-id contract: non-empty, length ≤ 256, no leading/trailing
+whitespace, must not contain `#`.
+
 ## v3.0 — VectorizerRPC is the default transport
 
 Starting with v3.0, the recommended transport is **VectorizerRPC**: a
@@ -79,6 +108,8 @@ import vectorizer_sdk
 
 async def main():
     client = await vectorizer_sdk.connect_async("vectorizer://127.0.0.1:15503")
+    # `hello` and `search_basic` are RPC-only (not available on the legacy
+    # REST `VectorizerClient`).
     await client.hello(vectorizer_sdk.HelloPayload(client_name="my-app"))
     print(await client.list_collections())
     hits = await client.search_basic("docs", "vector database", limit=5)
@@ -140,7 +171,7 @@ for a runnable end-to-end example.
 pip install vectorizer-sdk
 
 # Or specific version
-pip install vectorizer-sdk==3.0.0
+pip install vectorizer-sdk==3.2.0
 ```
 
 ## Package Layout (v3.x)
@@ -477,6 +508,11 @@ related = await client.get_related_files(
 
 ### Summarization Operations
 
+> WARNING: The `/summarize/*` REST endpoints are documented but not yet wired
+> server-side (see `DOC_GAP_ANALYSIS`). The SDK methods below
+> (`summarize_text`, `summarize_context`) will fail until server wiring is
+> complete.
+
 #### Summarize Text
 Summarize text using various methods:
 
@@ -509,6 +545,11 @@ summary = await client.summarize_context(
 
 ### Workspace Management
 
+> WARNING: `add_workspace`, `list_workspaces`, and `remove_workspace` are
+> exposed via the REST transport through dynamic `__getattr__` delegation,
+> but they are not first-class SDK methods yet. They work at runtime but
+> won't autocomplete in IDEs. A future release will add explicit methods.
+
 #### Add Workspace
 Add a new workspace:
 
@@ -537,6 +578,11 @@ await client.remove_workspace(
 
 ### Backup Operations
 
+> WARNING: `create_backup`, `list_backups`, and `restore_backup` are
+> exposed via the REST transport through dynamic `__getattr__` delegation,
+> but they are not first-class SDK methods yet. They work at runtime but
+> won't autocomplete in IDEs. A future release will add explicit methods.
+
 #### Create Backup
 Create a backup of collections:
 
@@ -664,8 +710,11 @@ await client.create_collection("documents", dimension=768)
 await client.insert_texts("documents", [
     {"id": "doc1", "text": "Sample document", "metadata": {"source": "api"}}
 ])
-await client.update_vector("documents", "doc1", metadata={"updated": True})
-await client.delete_vector("documents", "doc1")
+# Update-via-reinsert: re-call `insert_texts` with the same id to replace the record.
+await client.insert_texts("documents", [
+    {"id": "doc1", "text": "Sample document (updated)", "metadata": {"updated": True}}
+])
+await client.delete_vectors("documents", ["doc1"])
 
 # Reads automatically go to replicas (load balanced)
 results = await client.search_vectors("documents", query="sample", limit=10)
@@ -702,7 +751,7 @@ The SDK automatically classifies operations:
 
 | Operation Type | Routed To | Methods |
 |---------------|-----------|---------|
-| **Writes** | Always Master | `insert_texts`, `insert_vectors`, `update_vector`, `delete_vector`, `create_collection`, `delete_collection` |
+| **Writes** | Always Master | `insert_texts`, `insert_vectors`, `delete_vectors`, `create_collection`, `delete_collection` |
 | **Reads** | Based on `read_preference` | `search_vectors`, `get_vector`, `list_collections`, `intelligent_search`, `semantic_search`, `hybrid_search` |
 
 #### Standalone Mode (Single Node)

{vectorizer_sdk-3.0.0 → vectorizer_sdk-3.2.0}/vectorizer_sdk.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ tests/test_intelligent_search.py
 tests/test_mock_transport.py
 tests/test_models.py
 tests/test_qdrant_advanced.py
+tests/test_retry_after_parse.py
 tests/test_routing.py
 tests/test_sdk_comprehensive.py
 tests/test_simple.py

vectorizer_sdk-3.0.0/utils/http_client.py

@@ -1,145 +0,0 @@
-"""
-HTTP client utility for making API requests using aiohttp.
-"""
-
-from typing import Optional, Dict, Any
-import aiohttp
-import asyncio
-import logging
-
-try:
-    from ..exceptions import (
-        NetworkError,
-        ServerError,
-        AuthenticationError,
-    )
-except ImportError:
-    from exceptions import (
-        NetworkError,
-        ServerError,
-        AuthenticationError,
-    )
-
-logger = logging.getLogger(__name__)
-
-
-class HTTPClient:
-    """HTTP transport client."""
-    
-    def __init__(
-        self,
-        base_url: str = "http://localhost:15002",
-        api_key: Optional[str] = None,
-        timeout: int = 30,
-        max_retries: int = 3
-    ):
-        """
-        Initialize HTTP client.
-        
-        Args:
-            base_url: Base URL for HTTP API
-            api_key: API key for authentication
-            timeout: Request timeout in seconds
-            max_retries: Maximum number of retry attempts
-        """
-        self.base_url = base_url.rstrip('/')
-        self.api_key = api_key
-        self.timeout = timeout
-        self.max_retries = max_retries
-        self._session: Optional[aiohttp.ClientSession] = None
-    
-    async def _ensure_session(self):
-        """Ensure aiohttp session is created."""
-        if self._session is None or self._session.closed:
-            headers = {"Content-Type": "application/json"}
-            if self.api_key:
-                headers["Authorization"] = f"Bearer {self.api_key}"
-            
-            timeout_config = aiohttp.ClientTimeout(total=self.timeout)
-            self._session = aiohttp.ClientSession(
-                headers=headers,
-                timeout=timeout_config
-            )
-    
-    async def close(self):
-        """Close the HTTP session."""
-        if self._session and not self._session.closed:
-            await self._session.close()
-            self._session = None
-    
-    async def request(
-        self,
-        method: str,
-        path: str,
-        data: Optional[Dict[str, Any]] = None
-    ) -> Any:
-        """
-        Make an HTTP request.
-        
-        Args:
-            method: HTTP method
-            path: API endpoint path
-            data: Request data
-            
-        Returns:
-            Response data
-        """
-        await self._ensure_session()
-        
-        url = f"{self.base_url}{path}"
-        
-        try:
-            async with self._session.request(
-                method,
-                url,
-                json=data if data else None
-            ) as response:
-                if response.status >= 400:
-                    error_text = await response.text()
-                    raise self._handle_error(response.status, error_text)
-                
-                content_type = response.headers.get('Content-Type', '')
-                if 'application/json' in content_type:
-                    return await response.json()
-                return await response.text()
-        
-        except (ServerError, AuthenticationError):
-            raise
-        except aiohttp.ClientError as e:
-            raise NetworkError(f"HTTP request failed: {e}")
-        except asyncio.TimeoutError:
-            raise NetworkError("Request timeout")
-        except Exception as e:
-            raise NetworkError(f"Unknown error: {e}")
-    
-    async def get(self, path: str) -> Any:
-        """Make a GET request."""
-        return await self.request("GET", path)
-    
-    async def post(self, path: str, data: Optional[Dict[str, Any]] = None) -> Any:
-        """Make a POST request."""
-        return await self.request("POST", path, data)
-    
-    async def put(self, path: str, data: Optional[Dict[str, Any]] = None) -> Any:
-        """Make a PUT request."""
-        return await self.request("PUT", path, data)
-    
-    async def delete(self, path: str) -> Any:
-        """Make a DELETE request."""
-        return await self.request("DELETE", path)
-    
-    def _handle_error(self, status: int, error_text: str) -> Exception:
-        """Handle HTTP errors and convert to appropriate exceptions."""
-        message = f"HTTP {status}: {error_text}"
-        
-        if status == 401:
-            return AuthenticationError(message)
-        elif status == 403:
-            return AuthenticationError("Access forbidden")
-        elif status == 404:
-            return ServerError("Resource not found")
-        elif status in (429, 500, 502, 503, 504):
-            return ServerError(message)
-        else:
-            return ServerError(message)
-