embed-client 4.0.28__tar.gz → 4.0.30__tar.gz

{embed_client-4.0.28/embed_client.egg-info → embed_client-4.0.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: embed-client
-Version: 4.0.28
+Version: 4.0.30
 Summary: Async client for the Embedding Service API. Canonical class: EmbeddingClient (JSON-RPC via mcp-proxy-adapter >=8.10).
 Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
 License-Expression: MIT
@@ -104,6 +104,8 @@ Public queue-oriented helpers include **`embed`**, **`wait_for_job`**, **`job_st
 
 **`embed_file` vs local JSON without shared server disk:** use **`embed_file`** with a server-visible **`input_file`** when the input already exists on the service host. For a **`json_array`** file that exists only on the client machine (no shared filesystem), use the CLI **`embed-file-json`** subcommand (or **`embed_file_from_local_json_file`**) so the client validates, uploads through the adapter, resolves **`storage_path`** via **`get_upload_session`**, then runs **`embed_file`** with that path and **`format=json_array`**. For Markdown sources (e.g. with YAML front matter), run **`prepare-embed-file-json`** first to emit a valid **`json_array`** (array of strings): the body is split **only** on blank lines (**`\n\n`**) into paragraph-sized strings, with per-paragraph UTF-8 size limits and **no** automatic oversize split — oversized paragraphs require editing the source or raising the byte cap; then **`embed-file-json`**. Add **`--show-progress`** to stream server WebSocket/status lines to stderr during the job wait (see **`CLI_README.md`**).
 
+**Vectorization backends (server 4.0.29+):** **`embed`** and **`embed_file`** take **`backend="local"|"external"`** (omitted = the server's configured default; `external` is the macsc service). **`model_offload()`** moves the resident local model VRAM -> RAM (pinned against the GPU watcher) and **`model_load(model=None, device=None, wait=None)`** moves it back (`wait=False` returns at once while the load continues, `wait=True` blocks until it is in VRAM). A local request while the model is not in VRAM is refused at once with `-32001 MODEL_LOADING` (the load runs in the background; retry), a backend the server mode does not admit with `-32002 BACKEND_MODE_MISMATCH`, an external failure with `-32003`. Refusals of `model_offload`/`model_load` arrive as **`EmbedAPIError`** carrying the server error object. Every embed result carries `backend`; external results also carry `usage`.
+
 ## Documentation
 
 - **[CONFIGURATION.md](CONFIGURATION.md)** — JSON config schema, protocols, validation

{embed_client-4.0.28 → embed_client-4.0.30}/README.md

@@ -57,6 +57,8 @@ Public queue-oriented helpers include **`embed`**, **`wait_for_job`**, **`job_st
 
 **`embed_file` vs local JSON without shared server disk:** use **`embed_file`** with a server-visible **`input_file`** when the input already exists on the service host. For a **`json_array`** file that exists only on the client machine (no shared filesystem), use the CLI **`embed-file-json`** subcommand (or **`embed_file_from_local_json_file`**) so the client validates, uploads through the adapter, resolves **`storage_path`** via **`get_upload_session`**, then runs **`embed_file`** with that path and **`format=json_array`**. For Markdown sources (e.g. with YAML front matter), run **`prepare-embed-file-json`** first to emit a valid **`json_array`** (array of strings): the body is split **only** on blank lines (**`\n\n`**) into paragraph-sized strings, with per-paragraph UTF-8 size limits and **no** automatic oversize split — oversized paragraphs require editing the source or raising the byte cap; then **`embed-file-json`**. Add **`--show-progress`** to stream server WebSocket/status lines to stderr during the job wait (see **`CLI_README.md`**).
 
+**Vectorization backends (server 4.0.29+):** **`embed`** and **`embed_file`** take **`backend="local"|"external"`** (omitted = the server's configured default; `external` is the macsc service). **`model_offload()`** moves the resident local model VRAM -> RAM (pinned against the GPU watcher) and **`model_load(model=None, device=None, wait=None)`** moves it back (`wait=False` returns at once while the load continues, `wait=True` blocks until it is in VRAM). A local request while the model is not in VRAM is refused at once with `-32001 MODEL_LOADING` (the load runs in the background; retry), a backend the server mode does not admit with `-32002 BACKEND_MODE_MISMATCH`, an external failure with `-32003`. Refusals of `model_offload`/`model_load` arrive as **`EmbedAPIError`** carrying the server error object. Every embed result carries `backend`; external results also carry `usage`.
+
 ## Documentation
 
 - **[CONFIGURATION.md](CONFIGURATION.md)** — JSON config schema, protocols, validation

{embed_client-4.0.28 → embed_client-4.0.30}/embed_client/__init__.py

@@ -27,7 +27,7 @@ try:
     __version__ = version("embed-client")
 except PackageNotFoundError:
     # Editable checkout without install metadata (e.g. some unit-test sandboxes).
-    __version__ = "4.0.28"
+    __version__ = "4.0.30"
 
 __all__ = [
     "EmbeddingClient",

{embed_client-4.0.28 → embed_client-4.0.30}/embed_client/embedding_client.py

@@ -636,6 +636,7 @@ class EmbeddingClient:
         wait_timeout: int = 60,
         poll_interval: float = 1.0,
         use_push: bool = True,
+        backend: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
         Generate embeddings for texts (via queue).
@@ -660,13 +661,19 @@ class EmbeddingClient:
             wait_timeout: Max time to wait (seconds); 0 = no timeout.
             poll_interval: Unused (kept for API compatibility).
             use_push: Unused; WS is always used when wait=True.
+            backend: ``"local"`` (model on the server host) or ``"external"``
+                (macsc) for this request; ``None`` takes the server's configured
+                default. A backend the server mode does not admit is refused
+                (-32002 BACKEND_MODE_MISMATCH); a local request while the model
+                is not in VRAM is refused (-32001 MODEL_LOADING) and the load
+                continues in the background, so retry it.
 
         Returns:
             If wait=False: ``{"job_id", "status", "message"}``; when the server hit
             its synchronous execution cap and fell back to the queue, responses may
             include ``queued_after_timeout: true`` (mcp-proxy-adapter >= 8.10).
             If wait=True: {"results": [...], "model", "dimension"} (and optional
-            "device" and timing fields such as ``timing_total_seconds``,
+            "device", "backend" and timing fields such as ``timing_total_seconds``,
             ``timing_encode_seconds``, ``timing_tokenization_seconds``,
             ``timing_median_per_text_encode_seconds``), matching server embed
             result data.
@@ -710,6 +717,8 @@ class EmbeddingClient:
             params["aggregation_method"] = aggregation_method
         if parts is not None:
             params["parts"] = parts
+        if backend is not None:
+            params["backend"] = backend
 
         # When wait=True use execute_async("embed_execute") for in-process execution
         # (no queue, no worker spawn) to avoid large per-request delay.
@@ -1069,6 +1078,7 @@ class EmbeddingClient:
         device: Optional[str] = None,
         error_policy: Optional[str] = None,
         aggregation_method: Optional[str] = None,
+        backend: Optional[str] = None,
         wait: bool = True,
         wait_timeout: int = 600,
         download_to: Optional[str] = None,
@@ -1100,6 +1110,8 @@ class EmbeddingClient:
             aggregation_method: Same semantics as :meth:`embed`: resolved by
                 priority call -> config -> constant when omitted; applied
                 per-item, one line/array entry at a time.
+            backend: Same semantics as :meth:`embed` (``"local"``/``"external"``;
+                ``None`` = server default).
             wait: If True, block until job completes (WebSocket).
             wait_timeout: Seconds for wait (0 treated as 600 for WS wait).
             download_to: If set, write the downloaded result JSON to this path. If
@@ -1147,6 +1159,8 @@ class EmbeddingClient:
             params["error_policy"] = EMBED_COMMAND_SCHEMA_DEFAULT_ERROR_POLICY
         if aggregation_method is not None:
             params["aggregation_method"] = aggregation_method
+        if backend is not None:
+            params["backend"] = backend
 
         response = await self.client.jsonrpc_call("embed_file", params)
         if "error" in response:
@@ -1347,7 +1361,9 @@ class EmbeddingClient:
         List available models (shape matches server models command result.data).
 
         Returns:
-            {"models": [...]} with name, dimension, supported_dimensions, max_tokens.
+            {"models": [...], "mode", "default_backend", "external"}; each entry has
+            name, dimension, supported_dimensions, max_tokens, backend and (local
+            entries) residency.
 
         Raises:
             EmbedClientError: If models request fails
@@ -1366,6 +1382,81 @@ class EmbeddingClient:
 
         return result.get("data", {})
 
+    async def _service_command(
+        self, command: str, params: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Run a synchronous service command and return its ``data``.
+
+        A refusal (error response or ``success: false``) is raised as
+        :class:`EmbedAPIError` carrying the server's own error object, whose
+        ``code``/``data.code`` name the refusal (for example MODEL_LOADING).
+        """
+        response = await self.client.jsonrpc_call(command, params)
+        if isinstance(response, dict) and response.get("error") is not None:
+            raise EmbedAPIError(response["error"])
+        result = response.get("result") if isinstance(response, dict) else None
+        if not isinstance(result, dict):
+            raise EmbedAPIError(f"Command {command!r} returned {response!r}")
+        if result.get("success") is False:
+            raise EmbedAPIError(result.get("error") or result)
+        data = result.get("data")
+        return data if isinstance(data, dict) else result
+
+    async def model_offload(self, model: Optional[str] = None) -> Dict[str, Any]:
+        """Move the resident local model VRAM -> RAM and pin it there.
+
+        The GPU watcher does not move it back; ``model_load`` (or a local
+        request, which starts the load in the background) does. Idempotent.
+        Available in server modes ``local`` and ``mixed``.
+
+        Args:
+            model: Local model to offload; defaults to the resident model.
+
+        Returns:
+            ``{model, dimension, residency: "ram", previous_residency, device:
+            "cpu", changed, vram_released_mb}``.
+
+        Raises:
+            EmbedAPIError: -32602 invalid parameter or MODEL_NOT_RESIDENT,
+                -32001 MODEL_LOADING, -32002 BACKEND_MODE_MISMATCH (mode external).
+        """
+        params: Dict[str, Any] = {}
+        if model is not None:
+            params["model"] = model
+        return await self._service_command("model_offload", params)
+
+    async def model_load(
+        self,
+        model: Optional[str] = None,
+        device: Optional[str] = None,
+        wait: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """Move a local model RAM -> VRAM (or load it from disk).
+
+        Args:
+            model: Local model to load; defaults to the server's ``embedding.model_name``.
+            device: ``"auto"`` (server default), ``"cuda"`` or ``"cuda:N"``.
+            wait: ``False`` (server default) returns at once with residency
+                ``"loading"`` while the load continues in the background;
+                ``True`` blocks until the model is in VRAM or the load failed.
+
+        Returns:
+            ``{model, dimension, residency: "loading"|"vram", previous_residency,
+            device, changed, async}``.
+
+        Raises:
+            EmbedAPIError: -32602 invalid parameter, -32603 NO_GPU_AVAILABLE or
+                MODEL_LOAD_FAILED, -32002 BACKEND_MODE_MISMATCH (mode external).
+        """
+        params: Dict[str, Any] = {}
+        if model is not None:
+            params["model"] = model
+        if device is not None:
+            params["device"] = device
+        if wait is not None:
+            params["wait"] = wait
+        return await self._service_command("model_load", params)
+
     async def list_commands(self) -> Dict[str, Any]:
         """
         List available commands.

{embed_client-4.0.28 → embed_client-4.0.30/embed_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: embed-client
-Version: 4.0.28
+Version: 4.0.30
 Summary: Async client for the Embedding Service API. Canonical class: EmbeddingClient (JSON-RPC via mcp-proxy-adapter >=8.10).
 Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
 License-Expression: MIT
@@ -104,6 +104,8 @@ Public queue-oriented helpers include **`embed`**, **`wait_for_job`**, **`job_st
 
 **`embed_file` vs local JSON without shared server disk:** use **`embed_file`** with a server-visible **`input_file`** when the input already exists on the service host. For a **`json_array`** file that exists only on the client machine (no shared filesystem), use the CLI **`embed-file-json`** subcommand (or **`embed_file_from_local_json_file`**) so the client validates, uploads through the adapter, resolves **`storage_path`** via **`get_upload_session`**, then runs **`embed_file`** with that path and **`format=json_array`**. For Markdown sources (e.g. with YAML front matter), run **`prepare-embed-file-json`** first to emit a valid **`json_array`** (array of strings): the body is split **only** on blank lines (**`\n\n`**) into paragraph-sized strings, with per-paragraph UTF-8 size limits and **no** automatic oversize split — oversized paragraphs require editing the source or raising the byte cap; then **`embed-file-json`**. Add **`--show-progress`** to stream server WebSocket/status lines to stderr during the job wait (see **`CLI_README.md`**).
 
+**Vectorization backends (server 4.0.29+):** **`embed`** and **`embed_file`** take **`backend="local"|"external"`** (omitted = the server's configured default; `external` is the macsc service). **`model_offload()`** moves the resident local model VRAM -> RAM (pinned against the GPU watcher) and **`model_load(model=None, device=None, wait=None)`** moves it back (`wait=False` returns at once while the load continues, `wait=True` blocks until it is in VRAM). A local request while the model is not in VRAM is refused at once with `-32001 MODEL_LOADING` (the load runs in the background; retry), a backend the server mode does not admit with `-32002 BACKEND_MODE_MISMATCH`, an external failure with `-32003`. Refusals of `model_offload`/`model_load` arrive as **`EmbedAPIError`** carrying the server error object. Every embed result carries `backend`; external results also carry `usage`.
+
 ## Documentation
 
 - **[CONFIGURATION.md](CONFIGURATION.md)** — JSON config schema, protocols, validation

{embed_client-4.0.28 → embed_client-4.0.30}/embed_client.egg-info/SOURCES.txt

@@ -227,5 +227,6 @@ tests/test_local_json_embed_file.py
 tests/test_md_embed_file_prep.py
 tests/test_security_matrix.py
 tests/test_ssl_manager.py
+tests/test_vectorization_modes_client.py
 tests/test_wait_for_job_ws_fallback.py
 tests/test_with_auth.py

{embed_client-4.0.28 → embed_client-4.0.30}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "embed-client"
-version = "4.0.28"
+version = "4.0.30"
 description = """Async client for the Embedding Service API. Canonical class: EmbeddingClient (JSON-RPC via mcp-proxy-adapter >=8.10).
 
 Public API highlights:

embed_client-4.0.30/tests/test_vectorization_modes_client.py

@@ -0,0 +1,120 @@
+"""
+Client surface of the server's vectorization modes: the ``backend`` parameter of
+embed / embed_file and the model_offload / model_load commands.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from embed_client.embedding_client import EmbeddingClient
+from embed_client.exceptions import EmbedAPIError
+
+
+def _client() -> EmbeddingClient:
+    return EmbeddingClient(protocol="http", host="127.0.0.1", port=8080)
+
+
+def _ok(data):
+    return {"result": {"success": True, "data": data}}
+
+
+@pytest.mark.asyncio
+async def test_embed_forwards_backend_only_when_supplied():
+    client = _client()
+    client.client.jsonrpc_call = AsyncMock(return_value=_ok({"job_id": "j1"}))
+
+    await client.embed(["a"], backend="external")
+    _method, params = client.client.jsonrpc_call.await_args.args
+    assert params["backend"] == "external"
+
+    await client.embed(["a"])
+    _method, params = client.client.jsonrpc_call.await_args.args
+    assert "backend" not in params
+
+
+@pytest.mark.asyncio
+async def test_embed_file_forwards_backend_only_when_supplied():
+    client = _client()
+    client.client.jsonrpc_call = AsyncMock(return_value=_ok({"job_id": "j1"}))
+
+    await client.embed_file("/srv/input.txt", backend="local", wait=False)
+    method, params = client.client.jsonrpc_call.await_args.args
+    assert method == "embed_file"
+    assert params["backend"] == "local"
+
+    await client.embed_file("/srv/input.txt", wait=False)
+    _method, params = client.client.jsonrpc_call.await_args.args
+    assert "backend" not in params
+
+
+@pytest.mark.asyncio
+async def test_embed_wait_true_carries_backend_to_embed_execute():
+    client = _client()
+    seen = {}
+
+    async def fake(params, wait_timeout):
+        seen.update(params)
+        return {"results": [], "model": "m", "dimension": 1, "backend": "external"}
+
+    client._embed_via_execute_async = fake
+    result = await client.embed(["a"], backend="external", wait=True)
+    assert seen["backend"] == "external"
+    assert result["backend"] == "external"
+
+
+@pytest.mark.asyncio
+async def test_model_offload_builds_params_and_returns_data():
+    client = _client()
+    data = {"model": "m", "residency": "ram", "changed": True}
+    client.client.jsonrpc_call = AsyncMock(return_value=_ok(data))
+
+    assert await client.model_offload() == data
+    method, params = client.client.jsonrpc_call.await_args.args
+    assert (method, params) == ("model_offload", {})
+
+    await client.model_offload("all-MiniLM-L6-v2")
+    _method, params = client.client.jsonrpc_call.await_args.args
+    assert params == {"model": "all-MiniLM-L6-v2"}
+
+
+@pytest.mark.asyncio
+async def test_model_load_builds_params():
+    client = _client()
+    client.client.jsonrpc_call = AsyncMock(return_value=_ok({"residency": "loading"}))
+
+    await client.model_load()
+    method, params = client.client.jsonrpc_call.await_args.args
+    assert (method, params) == ("model_load", {})
+
+    await client.model_load("all-MiniLM-L6-v2", device="cuda:0", wait=True)
+    _method, params = client.client.jsonrpc_call.await_args.args
+    assert params == {"model": "all-MiniLM-L6-v2", "device": "cuda:0", "wait": True}
+
+    await client.model_load(wait=False)
+    _method, params = client.client.jsonrpc_call.await_args.args
+    assert params == {"wait": False}
+
+
+@pytest.mark.asyncio
+async def test_refusals_arrive_as_api_errors_with_the_server_error():
+    client = _client()
+    refusal = {
+        "code": -32002,
+        "message": "command is not available in vectorization mode 'external'",
+        "data": {"code": "BACKEND_MODE_MISMATCH", "field": "command"},
+    }
+    client.client.jsonrpc_call = AsyncMock(
+        return_value={"result": {"success": False, "error": refusal}}
+    )
+    with pytest.raises(EmbedAPIError) as info:
+        await client.model_offload()
+    assert info.value.error == refusal
+
+    client.client.jsonrpc_call = AsyncMock(return_value={"error": refusal})
+    with pytest.raises(EmbedAPIError) as info:
+        await client.model_load(wait=True)
+    assert info.value.error == refusal