embed-client-dev 4.0.78__py3-none-any.whl

embed_client/embedding_client.py

@@ -0,0 +1,1929 @@
+"""
+Embedding service client for interacting with embedding service API.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+import asyncio
+import copy
+import hashlib
+import inspect
+import logging
+import os
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union
+
+if TYPE_CHECKING:
+    from embed_client.config import ClientConfig
+
+from embed_client.embed_file_status_store import EmbedFileJobStatusStore
+
+from mcp_proxy_adapter.client.jsonrpc_client import JsonRpcClient
+from mcp_proxy_adapter.transfer.models import TransferReceipt
+from embed_client.embedding_client_helpers import (
+    list_commands_via_client,
+    wait_for_job_poll,
+)
+from embed_client.constants import EMBED_COMMAND_SCHEMA_DEFAULT_ERROR_POLICY
+from embed_client.exceptions import EmbedAPIError, EmbedClientError, EmbedError
+
+logger = logging.getLogger(__name__)
+
+try:  # mcp-proxy-adapter >= 8.10 raises this when /ws closes mid-wait
+    from mcp_proxy_adapter.client.jsonrpc_client.exceptions import (
+        ClientWebSocketClosedError as _AdapterWsClosedError,
+    )
+except ImportError:  # pragma: no cover - older adapter builds
+    _AdapterWsClosedError = None  # type: ignore[assignment,misc]
+
+# Terminal queue states reported by queue_get_job_status / embed_job_status.
+_POLL_COMPLETED_STATES = ("completed", "success")
+_POLL_FAILED_STATES = ("failed", "error")
+_POLL_STOPPED_STATES = ("stopped", "cancelled", "canceled")
+# Marks an input_limit_update cell that the caller did not name (distinct from null).
+_NOT_GIVEN: Any = object()
+
+
+def _is_ws_closed_before_terminal(exc: BaseException) -> bool:
+    """Whether *exc* means the /ws stream closed before a terminal job event.
+
+    The job itself is unaffected by a dropped stream: the server keeps
+    executing it and ``queue_get_job_status`` still reports its terminal
+    state. A heartbeat miss while the server is busy closes the stream
+    without any job having failed.
+    """
+    if _AdapterWsClosedError is not None and isinstance(exc, _AdapterWsClosedError):
+        return True
+    return "websocket closed" in str(exc).lower()
+
+
+def _client_has_async_method(client: Any, name: str) -> bool:
+    fn = getattr(client, name, None)
+    return fn is not None and inspect.iscoroutinefunction(fn)
+
+
+def _uses_adapter_job_message_registry(client: Any) -> bool:
+    """True if *client* exposes async ``get_job_messages`` (adapter job registry)."""
+    return _client_has_async_method(client, "get_job_messages")
+
+
+async def _maybe_await(value: Any) -> None:
+    if inspect.isawaitable(value):
+        await value
+
+
+def _sha256_hex_file(path: str) -> str:
+    """SHA-256 hex digest of file at ``path`` (streaming read)."""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _normalize_hex_checksum(value: Any) -> str:
+    if not isinstance(value, str):
+        return ""
+    return value.strip().lower()
+
+
+def _merge_jsonrpc_result_data_layers(raw: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Merge ``data`` dicts found along nested JSON-RPC-style ``result`` wrappers.
+
+    Walks *raw* depth-first: at each dict node, if ``data`` is a dict it is
+    collected; then ``result`` is visited if it is a dict. Shallow ``data``
+    layers are merged first; deeper layers overwrite on key conflicts so full
+    command payloads (e.g. ``input_checksum_value`` under inner
+    ``result.result.data``) win over thin outer ``data`` envelopes.
+    """
+    layers: List[Dict[str, Any]] = []
+
+    def visit(node: Any) -> None:
+        if not isinstance(node, dict):
+            return
+        d = node.get("data")
+        if isinstance(d, dict):
+            layers.append(d)
+        nxt = node.get("result")
+        if isinstance(nxt, dict):
+            visit(nxt)
+
+    visit(raw)
+    if not layers:
+        return raw
+    merged: Dict[str, Any] = {}
+    for d in layers:
+        merged = {**merged, **d}
+    return merged
+
+
+def _embed_file_queue_result_error_message(data: Dict[str, Any]) -> Optional[str]:
+    """
+    If a queued ``embed_file`` job completed with ``success: false`` in the
+    normalized WebSocket payload, return a human-readable error message.
+    """
+    inner = data.get("result")
+    if not isinstance(inner, dict):
+        return None
+    if inner.get("success") is True:
+        return None
+    err = inner.get("error")
+    if inner.get("success") is not False and err is None:
+        return None
+    if isinstance(err, dict):
+        msg = err.get("message")
+        if isinstance(msg, str) and msg.strip():
+            return msg.strip()
+        return str(err) if err else "embed_file job failed"
+    if err is not None:
+        return str(err)
+    return "embed_file job failed"
+
+
+#: Adapter terminal events that carry a failure. ``delivery_failed`` is what the
+#: adapter pushes when a queued or execute_async command fails or times out
+#: (its ``error`` field holds the real reason, e.g. "Command timed out after 300.0s").
+_FAILED_TERMINAL_EVENTS = frozenset({"job_failed", "delivery_failed"})
+#: Adapter terminal events for a job that was cancelled or stopped before completion.
+_CANCELLED_TERMINAL_EVENTS = frozenset({"delivery_cancelled", "delivery_stopped"})
+
+
+def _normalize_terminal_job_payload(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Normalize adapter /ws terminal payload to embed result ``data`` shape.
+
+    Failure events (``job_failed``, ``delivery_failed``) and cancellation events
+    (``delivery_cancelled``, ``delivery_stopped``) raise :class:`EmbedClientError`
+    carrying the event's ``error`` text. Used by :meth:`wait_for_job` (adapter path)
+    and embed_file WS completion.
+    """
+    ev = payload.get("event") or payload.get("type")
+    if ev in _FAILED_TERMINAL_EVENTS:
+        err = payload.get("error", "Unknown error")
+        raise EmbedClientError(f"Job failed: {err}", error=payload.get("error"))
+    if ev in _CANCELLED_TERMINAL_EVENTS:
+        err = payload.get("error", "Unknown error")
+        raise EmbedClientError(f"Job cancelled: {err}", error=payload.get("error"))
+    if ev in ("job_completed", "job_completed_success", "delivery_completed"):
+        raw = payload.get("result") or {}
+        error = _find_failed_command_result(raw)
+        if error is not None:
+            raise EmbedClientError(
+                f"Job command failed: {error}",
+                error=_find_failed_command_error_object(raw),
+            )
+        return _merge_jsonrpc_result_data_layers(raw)
+    raise EmbedClientError(
+        f"Unexpected WebSocket event: {ev} (payload keys: {list(payload.keys())})"
+    )
+
+
+def _missing_from_worker_registry(exc: Exception) -> bool:
+    """Whether a queued command failed because the worker has no such command.
+
+    The adapter runs a queued command in a child process whose registry is
+    rebuilt from the project's own modules, so the adapter's own builtins —
+    help, health, echo — are absent there even though they answer over
+    JSON-RPC. Those commands are not broken and must not be reported as such.
+    """
+    details = getattr(exc, "details", None)
+    if not isinstance(details, dict):
+        return False
+    status = details.get("result_status")
+    if not isinstance(status, dict):
+        return False
+    return "not found" in str(status.get("description") or "").lower()
+
+
+def _find_failed_command_error_object(value: Any) -> Any:
+    """Return the raw error object of the first nested failed command envelope.
+
+    Sibling of :func:`_find_failed_command_result` (same traversal) that returns
+    the error exactly as received (dict, str or ``None``) instead of a message.
+    """
+    if not isinstance(value, dict):
+        return None
+    if value.get("success") is False:
+        return value.get("error")
+    for key in ("result", "data"):
+        if _find_failed_command_result(value.get(key)) is not None:
+            return _find_failed_command_error_object(value.get(key))
+    return None
+
+
+def _find_failed_command_result(value: Any) -> Optional[str]:
+    """Return the first nested command error from a completed queue envelope.
+
+    A queue job whose command failed still arrives as ``job_completed``: the
+    refusal sits inside the envelope with ``success: False``. Without this the
+    caller would read a failed command as a successful job.
+    """
+    if not isinstance(value, dict):
+        return None
+    if value.get("success") is False:
+        error = value.get("error")
+        if isinstance(error, dict):
+            return str(error.get("message") or error)
+        return str(error or "Unknown command error")
+    for key in ("result", "data"):
+        nested = _find_failed_command_result(value.get(key))
+        if nested is not None:
+            return nested
+    return None
+
+
+class EmbeddingClient:
+    """
+    Client for embedding service API.
+
+    Provides high-level interface for:
+    - Generating embeddings (via queue)
+    - Checking job status
+    - Listing available models
+    - Health checks
+
+    This client always uses WebSocket (/ws) for job result delivery when
+    wait=True (server exposes /ws; job_push is enabled when queue is on).
+    No HTTP polling for completion.
+
+    **embed_file status store (optional):** pass ``enable_embed_file_status_store=True``
+    to accumulate per-``job_id`` submit payload and WebSocket frames for
+    :meth:`embed_file`. Query with :meth:`get_embed_file_status_snapshot`,
+    :meth:`list_embed_file_status_messages`, :meth:`alist_embed_file_status_messages`,
+    :meth:`list_embed_file_status_job_ids`, and clear with
+    :meth:`clear_embed_file_status`. With mcp-proxy-adapter ``JobTrackingMixin``
+    (>= 6.10), WS completion uses :meth:`JsonRpcClient.wait_for_job` and
+    :meth:`clear_embed_file_status` also clears the adapter registry; from async
+    code prefer :meth:`alist_embed_file_status_messages` and
+    :meth:`aget_embed_file_status_snapshot` to read adapter history.
+    Default is off; behavior is unchanged when disabled.
+
+    With **mcp-proxy-adapter >= 8.10**, a synchronous command that hits the server
+    sync cap is **re-queued** instead of failing the HTTP/JSON-RPC call; the JSON
+    payload may include ``queued_after_timeout`` (see :meth:`embed` with
+    ``wait=False``).
+
+    Example:
+        client = EmbeddingClient(
+            host="127.0.0.1", port=8080, enable_embed_file_status_store=True
+        )
+        await client.embed_file("/srv/data.txt", wait=True)
+        snap = await client.aget_embed_file_status_snapshot("job-uuid")
+    """
+
+    def __init__(
+        self,
+        protocol: str = "http",
+        host: str = "127.0.0.1",
+        port: int = 8080,
+        cert: Optional[str] = None,
+        key: Optional[str] = None,
+        ca: Optional[str] = None,
+        check_hostname: bool = False,
+        token: Optional[str] = None,
+        token_header: Optional[str] = None,
+        timeout: float = 120.0,
+        *,
+        enable_embed_file_status_store: bool = False,
+        verify_server: bool = True,
+    ):
+        """
+        Initialize embedding client.
+
+        Args:
+            protocol: Transport protocol (http, https, mtls)
+            host: Server hostname
+            port: Server port
+            cert: Path to client certificate file (for mTLS)
+            key: Path to client private key file (for mTLS)
+            ca: Path to CA certificate file (for mTLS)
+            check_hostname: Whether to verify hostname in SSL connections
+            token: Authentication token
+            token_header: Header name for authentication token
+            timeout: Request/timeout in seconds for JSON-RPC and wait operations
+            enable_embed_file_status_store: If True, keep an in-memory record of
+                each ``embed_file`` job (submit + WS messages) keyed by ``job_id``.
+                When False (default), no extra storage and query methods return
+                empty/None.
+            verify_server: When False, the constructed client does not verify the
+                server certificate or its name. Required when dialling a host by an
+                address that the certificate does not cover.
+        """
+        self.client = JsonRpcClient(
+            protocol=protocol,
+            host=host,
+            port=port,
+            cert=cert,
+            key=key,
+            ca=ca,
+            check_hostname=check_hostname,
+            token=token,
+            token_header=token_header or ("X-API-Key" if token else None),
+            timeout=timeout,
+        )
+        if not verify_server:
+            self.client.verify = False
+        self.protocol = protocol
+        self.host = host
+        self.port = port
+        self._cert = cert
+        self._key = key
+        self._ca = ca
+        self._token = token
+        self._token_header = token_header or "X-API-Key"
+        self._timeout = float(timeout)
+        self._check_hostname = check_hostname
+        self._verify_server = verify_server
+        self._auth_method: Optional[str] = None
+        self._ssl_settings: Optional[Dict[str, Any]] = None
+        self._embed_file_status_store: Optional[EmbedFileJobStatusStore] = (
+            EmbedFileJobStatusStore() if enable_embed_file_status_store else None
+        )
+
+    @property
+    def base_url(self) -> str:
+        """Base URL without path; mTLS is shown as ``https`` for compatibility."""
+        scheme = "https" if self.protocol in ("https", "mtls") else "http"
+        return f"{scheme}://{self.host}"
+
+    @property
+    def timeout(self) -> float:
+        """Configured client timeout (seconds)."""
+        return self._timeout
+
+    def get_auth_method(self) -> Optional[str]:
+        """Auth method from config (``none``, ``api_key``, ``jwt``, …), if known."""
+        return self._auth_method
+
+    def is_authenticated(self) -> bool:
+        """Whether the client is configured for non-empty authentication."""
+        m = self._auth_method
+        if m in (None, "none"):
+            return False
+        if m == "api_key":
+            return bool(self._token)
+        if m in ("jwt", "basic", "certificate"):
+            return True
+        return bool(self._token)
+
+    def is_ssl_enabled(self) -> bool:
+        """True if TLS is enabled in config or transport uses HTTPS/mTLS."""
+        if isinstance(self._ssl_settings, dict) and "enabled" in self._ssl_settings:
+            return bool(self._ssl_settings["enabled"])
+        return self.protocol in ("https", "mtls")
+
+    def is_mtls_enabled(self) -> bool:
+        """True if mutual TLS is in use."""
+        return self.protocol == "mtls"
+
+    def get_ssl_config(self) -> Dict[str, Any]:
+        """SSL subsection from client config, or a minimal derived dict."""
+        if isinstance(self._ssl_settings, dict) and self._ssl_settings:
+            return dict(self._ssl_settings)
+        return {
+            "enabled": self.is_ssl_enabled(),
+            "verify_mode": "CERT_REQUIRED",
+            "check_hostname": self._check_hostname,
+        }
+
+    def get_auth_headers(self) -> Dict[str, str]:
+        """Return headers for API-key style auth (empty if no token)."""
+        if not self._token:
+            return {}
+        name = self._token_header or "X-API-Key"
+        return {str(name): str(self._token)}
+
+    @classmethod
+    def from_base_url_port(
+        cls,
+        base_url: str,
+        port: Optional[int] = None,
+        *,
+        timeout: float = 30.0,
+    ) -> "EmbeddingClient":
+        """Construct client from ``base_url`` and optional ``port`` (tests / scripts)."""
+        from urllib.parse import urlparse
+
+        parsed = urlparse(base_url)
+        scheme = (parsed.scheme or "http").lower()
+        if scheme not in ("http", "https"):
+            scheme = "http"
+        host = parsed.hostname or "localhost"
+        use_port = int(
+            parsed.port
+            if parsed.port is not None
+            else (port if port is not None else 8001)
+        )
+        return cls(
+            protocol="https" if scheme == "https" else "http",
+            host=host,
+            port=use_port,
+            timeout=float(timeout),
+        )
+
+    @classmethod
+    def from_config_dict(cls, config_dict: Dict[str, Any]) -> "EmbeddingClient":
+        """Same as :func:`embedding_client_from_config_dict`."""
+        return embedding_client_from_config_dict(config_dict)
+
+    @classmethod
+    def from_config_file(cls, config_path: Union[str, Path]) -> "EmbeddingClient":
+        """Load config from path and build a client."""
+        from embed_client.config import ClientConfig
+
+        cc = ClientConfig()
+        cc.load_from_file(str(config_path))
+        return cls.from_config(cc)
+
+    @classmethod
+    def with_auth(
+        cls,
+        base_url: str,
+        port: int,
+        auth_method: str,
+        **kwargs: Any,
+    ) -> "EmbeddingClient":
+        """Build a client from URL/port and auth method (legacy factory helper)."""
+        config_dict: Dict[str, Any] = {
+            "server": {"host": base_url, "port": port},
+            "client": {"timeout": kwargs.get("timeout", 30.0)},
+            "auth": {"method": auth_method},
+        }
+        if auth_method == "api_key":
+            if "api_keys" in kwargs:
+                config_dict["auth"]["api_keys"] = kwargs["api_keys"]
+            elif "api_key" in kwargs:
+                config_dict["auth"]["api_keys"] = {"user": kwargs["api_key"]}
+            else:
+                raise ValueError(
+                    "api_keys or api_key parameter required for api_key authentication"
+                )
+        elif auth_method == "jwt":
+            required_params = ["secret", "username", "password"]
+            for param in required_params:
+                if param not in kwargs:
+                    raise ValueError(
+                        f"{param} parameter required for jwt authentication"
+                    )
+            config_dict["auth"]["jwt"] = {
+                "secret": kwargs["secret"],
+                "username": kwargs["username"],
+                "password": kwargs["password"],
+                "expiry_hours": kwargs.get("expiry_hours", 24),
+            }
+        elif auth_method == "basic":
+            required_params = ["username", "password"]
+            for param in required_params:
+                if param not in kwargs:
+                    raise ValueError(
+                        f"{param} parameter required for basic authentication"
+                    )
+            config_dict["auth"]["basic"] = {
+                "username": kwargs["username"],
+                "password": kwargs["password"],
+            }
+        elif auth_method == "certificate":
+            required_params = ["cert_file", "key_file"]
+            for param in required_params:
+                if param not in kwargs:
+                    raise ValueError(
+                        f"{param} parameter required for certificate authentication"
+                    )
+            config_dict["auth"]["certificate"] = {
+                "cert_file": kwargs["cert_file"],
+                "key_file": kwargs["key_file"],
+            }
+        else:
+            raise ValueError(f"Unsupported authentication method: {auth_method}")
+
+        ssl_enabled = kwargs.get("ssl_enabled")
+        if ssl_enabled is None:
+            ssl_enabled = base_url.startswith("https://")
+
+        if ssl_enabled or any(
+            key in kwargs
+            for key in ["ca_cert_file", "cert_file", "key_file", "ssl_enabled"]
+        ):
+            ssl_config: Dict[str, Any] = {
+                "enabled": ssl_enabled,
+                "verify_mode": kwargs.get("verify_mode", "CERT_REQUIRED"),
+                "check_hostname": kwargs.get("check_hostname", True),
+                "check_expiry": kwargs.get("check_expiry", True),
+            }
+            if "ca_cert_file" in kwargs:
+                ssl_config["ca_cert_file"] = kwargs["ca_cert_file"]
+            if "cert_file" in kwargs:
+                ssl_config["cert_file"] = kwargs["cert_file"]
+            if "key_file" in kwargs:
+                ssl_config["key_file"] = kwargs["key_file"]
+            config_dict["ssl"] = ssl_config
+
+        return embedding_client_from_config_dict(config_dict)
+
+    def get_embed_file_status_snapshot(self, job_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Return a copy of accumulated state for an ``embed_file`` job, or ``None``.
+
+        Only populated when the client was constructed with
+        ``enable_embed_file_status_store=True`` and the job was recorded (submit
+        and/or WebSocket messages). Keys typically include ``job_id``, ``submit``,
+        ``messages``, and ``last_event`` after WS traffic.
+
+        Args:
+            job_id: Queue job id returned by the server for ``embed_file``.
+
+        Returns:
+            Deep copy of internal record, or ``None`` if unknown or store disabled.
+
+        When the adapter exposes ``get_job_messages`` and this method is called
+        from synchronous code (no running event loop), ``messages`` / ``last_event``
+        are refreshed from the adapter registry and merged with the local submit
+        snapshot. Under an active asyncio loop, use :meth:`aget_embed_file_status_snapshot`
+        so messages can be read from the adapter registry (local store does not
+        duplicate WS frames when the adapter tracks them).
+        """
+        if self._embed_file_status_store is None:
+            return None
+        local = self._embed_file_status_store.snapshot(job_id)
+        if local is None:
+            return None
+        if not _uses_adapter_job_message_registry(self.client):
+            return local
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            msgs = asyncio.run(self.client.get_job_messages(job_id))
+            merged: Dict[str, Any] = dict(local)
+            merged["messages"] = copy.deepcopy(msgs)
+            if msgs:
+                merged["last_event"] = copy.deepcopy(msgs[-1])
+            return merged
+        return local
+
+    async def aget_embed_file_status_snapshot(
+        self, job_id: str
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Async snapshot of embed_file job state: local ``submit`` plus adapter messages.
+
+        When ``get_job_messages`` exists on the underlying client, ``messages`` and
+        ``last_event`` come from the adapter job registry; otherwise from the local
+        store. Returns ``None`` if the status store is disabled or ``job_id`` is unknown.
+        """
+        if self._embed_file_status_store is None:
+            return None
+        local = self._embed_file_status_store.snapshot(job_id)
+        if local is None:
+            return None
+        if not _uses_adapter_job_message_registry(self.client):
+            return local
+        msgs = list(await self.client.get_job_messages(job_id))
+        merged = dict(local)
+        merged["messages"] = copy.deepcopy(msgs)
+        if msgs:
+            merged["last_event"] = copy.deepcopy(msgs[-1])
+        return merged
+
+    def list_embed_file_status_messages(self, job_id: str) -> List[Dict[str, Any]]:
+        """
+        List WebSocket JSON payloads accumulated for ``job_id`` (order preserved).
+
+        Returns an empty list if the store is disabled or ``job_id`` is unknown.
+
+        When ``JsonRpcClient.get_job_messages`` exists and there is no running
+        event loop, returns the adapter's bounded history. With an active event
+        loop and adapter-side tracking, WebSocket frames are not copied into the
+        local store — use :meth:`alist_embed_file_status_messages` (or await
+        :meth:`aget_embed_file_status_snapshot`) to read from the adapter registry.
+        Otherwise returns the in-memory store filled during ``embed_file``.
+        """
+        if self._embed_file_status_store is None:
+            return []
+        if not _uses_adapter_job_message_registry(self.client):
+            return self._embed_file_status_store.messages(job_id)
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return list(asyncio.run(self.client.get_job_messages(job_id)))
+        return self._embed_file_status_store.messages(job_id)
+
+    async def alist_embed_file_status_messages(
+        self, job_id: str
+    ) -> List[Dict[str, Any]]:
+        """
+        Async view of WS/job messages for ``job_id`` (adapter registry when available).
+
+        Empty list if the embed_file status store is disabled.
+        """
+        if self._embed_file_status_store is None:
+            return []
+        if _uses_adapter_job_message_registry(self.client):
+            return list(await self.client.get_job_messages(job_id))
+        return self._embed_file_status_store.messages(job_id)
+
+    def clear_embed_file_status(self, job_id: str) -> None:
+        """Remove stored submit/messages for ``job_id``. No-op if store disabled."""
+        if self._embed_file_status_store is None:
+            return
+        self._embed_file_status_store.clear(job_id)
+        if not _client_has_async_method(self.client, "clear_job_tracking"):
+            return
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            asyncio.run(self.client.clear_job_tracking(job_id))
+        else:
+            loop.create_task(self.client.clear_job_tracking(job_id))
+
+    def list_embed_file_status_job_ids(self) -> List[str]:
+        """
+        Return ``job_id`` values currently present in the embed_file status store.
+
+        Empty list if the store is disabled or nothing was recorded yet.
+        """
+        if self._embed_file_status_store is None:
+            return []
+        return self._embed_file_status_store.job_ids()
+
+    async def health(self) -> Dict[str, Any]:
+        """
+        Check server health.
+
+        Returns:
+            Health status information
+        """
+        return await self.client.health()
+
+    async def embed(
+        self,
+        texts: List[str],
+        model: Optional[str] = None,
+        dimension: Optional[int] = None,
+        job_id: Optional[str] = None,
+        error_policy: Optional[str] = None,
+        device: Optional[str] = None,
+        aggregation_method: Optional[str] = None,
+        parts: Optional[List[Optional[List[str]]]] = None,
+        wait: bool = False,
+        wait_timeout: int = 60,
+        poll_interval: float = 1.0,
+        use_push: bool = True,
+        provider: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Generate embeddings for texts (via queue).
+
+        Parameters match server embed command schema. When wait=True, completion
+        is always received via WebSocket (/ws) push (use_push is ignored; server
+        always uses WS for result delivery).
+
+        Args:
+            texts: List of texts to create embeddings for
+            model: Optional model name
+            dimension: Optional expected vector dimension
+            job_id: Optional custom job ID (server may ignore and generate own)
+            error_policy: 'fail_fast' or 'continue'; default from server
+            device: 'auto', 'cpu', 'cuda', 'cuda:0'; default from server
+            aggregation_method: How to combine part vectors when a text is
+                longer than the model can read. For the local model, when
+                neither the call nor the server config sets it, the default is
+                ``weighted_mean_by_tokens_normalized`` (``method_source``
+                ``constant``); a config value overrides that default (an
+                explicit null in the config disables aggregation, so a text past
+                the limit is refused rather than truncated) and a call value
+                overrides both. For a nonlocal provider a text past its input limit is
+                split and aggregated server-side, with the default
+                ``weighted_mean_by_tokens_normalized`` when this is omitted.
+            parts: One entry per text: a list of parts to combine, or ``None``
+                to let the server derive the parts from the text itself.
+            wait: If True, wait for job completion and return results (via /ws).
+            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.
+            provider: Optional provider id of the full model id (provider +
+                model). ``"local"`` is the server's own model; any other id is
+                a live macsc vectorization provider (for example ``"openai"``).
+                Sent only when not ``None`` (never injected by the client).
+                Resolution on the server (default first): provider given ->
+                must be known (else UNKNOWN_PROVIDER); model omitted -> the
+                default model, which must belong to that provider (else
+                UNKNOWN_MODEL). Provider omitted and model omitted -> the
+                default pair. Provider omitted and model given -> the default
+                provider is tried first (if it lists the model it is used,
+                macsc is not consulted for a local default); otherwise the
+                other providers are searched: exactly one offering the model
+                is used, several -> PROVIDER_REQUIRED, none -> UNKNOWN_MODEL.
+                ``dimension`` omitted -> the entry's default dimension; given
+                -> must satisfy its supported dimensions (else
+                UNSUPPORTED_DIMENSION). Errors arrive with ``error.data.code``
+                and ``error.data.kind`` unchanged: -32602 UNKNOWN_PROVIDER,
+                UNKNOWN_MODEL, UNSUPPORTED_DIMENSION, PROVIDER_REQUIRED;
+                -32003 EXTERNAL_UNAVAILABLE, EXTERNAL_UPSTREAM_FAILURE,
+                EXTERNAL_BAD_RESPONSE, EXTERNAL_INVALID_REQUEST; -32001
+                MODEL_LOADING (retry); -32004 OWN_MODEL_DISABLED; -32005
+                GPU_DISABLED; -32603 MODEL_LOAD_FAILED, NO_GPU_AVAILABLE,
+                -32603 TOKEN_MEASUREMENT_FAILED (retry; the input length could
+                not be measured, nothing was embedded).
+                ``aggregation_method`` and ``parts`` are accepted for any
+                effective provider. A text longer than a nonlocal provider's input
+                limit is split and aggregated server-side: with no
+                ``aggregation_method`` the default is
+                ``weighted_mean_by_tokens_normalized`` (reported as
+                ``method_source`` ``provider_default``); it is never refused for
+                lack of a method. ``device`` is accepted only with the effective
+                provider ``"local"``. The client does not validate these
+                parameters; it forwards them as given.
+
+        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", "provider", "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.
+
+        Raises:
+            EmbedClientError: If embedding request or job fails.
+            TimeoutError: If wait_timeout > 0 and job does not complete in time.
+
+        Example:
+            # Submit job and get job_id immediately
+            result = await client.embed(["Hello, world!"], wait=False)
+            job_id = result["job_id"]
+
+            # Wait for completion with timeout
+            result = await client.embed(
+                ["Hello, world!"],
+                wait=True,
+                wait_timeout=120  # Wait up to 2 minutes
+            )
+
+            # With error_policy and device (match server schema)
+            result = await client.embed(
+                ["Hello!"], error_policy="continue", device="cpu", wait=True
+            )
+        """
+        # Params match server embed schema (texts required; rest optional)
+        params: Dict[str, Any] = {"texts": texts}
+        if model is not None:
+            params["model"] = model
+        if dimension is not None:
+            params["dimension"] = dimension
+        if job_id is not None:
+            params["job_id"] = job_id
+        if error_policy is not None:
+            params["error_policy"] = error_policy
+        else:
+            params["error_policy"] = EMBED_COMMAND_SCHEMA_DEFAULT_ERROR_POLICY
+        if device is not None:
+            params["device"] = device
+        if aggregation_method is not None:
+            params["aggregation_method"] = aggregation_method
+        if parts is not None:
+            params["parts"] = parts
+        if provider is not None:
+            params["provider"] = provider
+
+        # When wait=True use execute_async("embed_execute") for in-process execution
+        # (no queue, no worker spawn) to avoid large per-request delay.
+        if wait:
+            return await self._embed_via_execute_async(params, wait_timeout)
+
+        response = await self.client.jsonrpc_call("embed", params)
+
+        # Extract result
+        if "error" in response:
+            raise EmbedClientError(f"Embedding failed: {response['error']}")
+
+        result = response.get("result", {})
+        if not result.get("success"):
+            error = result.get("error", {})
+            raise EmbedClientError(
+                f"Embedding failed: {error.get('message', 'Unknown error')}"
+            )
+
+        # Extract data - server may return full result (sync) or job_id (async queue)
+        data = result.get("data", {})
+        out_job_id = data.get("job_id") or result.get("job_id")
+
+        # Sync response: full result in one response (no job_id)
+        if not out_job_id and isinstance(data.get("results"), list):
+            return data
+
+        if not out_job_id:
+            raise EmbedClientError("No job_id or results returned from server")
+
+        qat = data.get("queued_after_timeout")
+        if qat is None:
+            qat = result.get("queued_after_timeout")
+        out: Dict[str, Any] = {
+            "job_id": out_job_id,
+            "status": data.get("status") or result.get("status", "pending"),
+            "message": data.get("message")
+            or result.get("message", "Job queued successfully"),
+        }
+        if qat is not None:
+            out["queued_after_timeout"] = bool(qat)
+        return out
+
+    async def wait_for_job(
+        self,
+        job_id: str,
+        timeout: Union[int, float] = 60,
+        poll_interval: float = 1.0,
+    ) -> Dict[str, Any]:
+        """
+        Wait for job completion.
+
+        When the underlying ``JsonRpcClient`` provides ``wait_for_job``
+        (mcp-proxy-adapter ``JobTrackingMixin``, >= 6.10), completion is waited
+        via WebSocket and the result is normalized to the same shape as the poll
+        path. Otherwise polls :meth:`job_status` every *poll_interval* seconds.
+
+        Args:
+            job_id: Job ID to wait for
+            timeout: Max wait (seconds); 0 = no timeout (WS path: no receive
+                deadline; poll path: unbounded loop)
+            poll_interval: Seconds between status checks (HTTP poll fallback only)
+
+        Returns:
+            {"results": [...], "model": str, "dimension": int} (and optional "device")
+
+        Raises:
+            EmbedClientError: If job not found or job failed. A job that runs
+                longer than the server's 180 s job limit is terminated by the
+                server and fails with "Worker request timed out waiting for a
+                response from the worker process" (-32603, WORKER_RESPONSE_TIMEOUT);
+                the server stays usable for the next request.
+            TimeoutError: If timeout > 0 and job does not complete in time
+        """
+        if _client_has_async_method(self.client, "wait_for_job"):
+            t_arg = float(timeout) if timeout > 0 else 0.0
+            started = asyncio.get_running_loop().time()
+            try:
+                raw = await self.client.wait_for_job(job_id, timeout=t_arg)
+            except asyncio.TimeoutError as e:
+                if t_arg > 0:
+                    msg = f"Job {job_id} did not complete within {t_arg} seconds"
+                else:
+                    msg = f"Job {job_id} WebSocket wait timed out"
+                raise TimeoutError(msg) from e
+            except Exception as e:  # noqa: BLE001 - classified below
+                if not _is_ws_closed_before_terminal(e):
+                    if isinstance(e, RuntimeError):
+                        raise EmbedClientError(f"WebSocket error: {e}") from e
+                    raise
+                return await self._poll_terminal_after_ws_close(
+                    job_id, t_arg, started, e, poll_interval=poll_interval
+                )
+            return _normalize_terminal_job_payload(raw)
+        return await wait_for_job_poll(
+            self.job_status, job_id, timeout=timeout, poll_interval=poll_interval
+        )
+
+    async def _poll_terminal_after_ws_close(
+        self,
+        job_id: str,
+        timeout: float,
+        started: float,
+        cause: BaseException,
+        poll_interval: float = 1.0,
+    ) -> Dict[str, Any]:
+        """Finish a wait whose /ws stream closed before the terminal event.
+
+        Polls :meth:`job_status` (``queue_get_job_status``) for the rest of the
+        caller's *timeout* and returns exactly what the WebSocket path would
+        have returned: the terminal status is wrapped as the equivalent
+        ``job_completed`` / ``job_failed`` event and passed through the same
+        normalizer, so a failed command inside a completed envelope is still
+        reported as a failure. ``timeout`` 0 means no deadline, as on the WS path.
+        The terminal events the normalizer accepts are ``job_completed``,
+        ``job_completed_success``, ``delivery_completed``, ``job_failed``,
+        ``delivery_failed``, ``delivery_cancelled`` and ``delivery_stopped``.
+        """
+        loop = asyncio.get_running_loop()
+        deadline = None if timeout <= 0 else started + timeout
+        logger.warning(
+            "WebSocket closed before a terminal event for job %s (%s); "
+            "polling queue_get_job_status for its terminal state",
+            job_id,
+            cause,
+        )
+        interval = poll_interval if poll_interval and poll_interval > 0 else 1.0
+        while True:
+            status = await self.job_status(job_id)
+            if isinstance(status, dict):
+                if status.get("exists") is False:
+                    raise EmbedClientError(f"Job {job_id} not found") from cause
+                state = str(status.get("status") or "").lower()
+                if state in _POLL_COMPLETED_STATES:
+                    return _normalize_terminal_job_payload(
+                        {
+                            "event": "job_completed",
+                            "job_id": job_id,
+                            "result": status.get("result") or {},
+                        }
+                    )
+                if state in _POLL_FAILED_STATES:
+                    failed_event: Dict[str, Any] = {
+                        "event": "job_failed",
+                        "job_id": job_id,
+                    }
+                    # Omit "error" when the status has none: the normalizer then
+                    # words the message "Unknown error" and exc.error stays None.
+                    failed_error = (
+                        status.get("error")
+                        or status.get("description")
+                        or status.get("message")
+                    )
+                    if failed_error:
+                        failed_event["error"] = failed_error
+                    return _normalize_terminal_job_payload(failed_event)
+                if state in _POLL_STOPPED_STATES:
+                    raise EmbedClientError(f"Job {job_id} was stopped") from cause
+            if deadline is not None and loop.time() >= deadline:
+                raise TimeoutError(
+                    f"Job {job_id} did not complete within {timeout} seconds"
+                ) from cause
+            await asyncio.sleep(interval)
+
+    async def _embed_via_execute_async(
+        self, params: Dict[str, Any], timeout: int = 60
+    ) -> Dict[str, Any]:
+        """
+        Run embed in-process via execute_async (no queue, no worker spawn).
+
+        Uses adapter execute_async RPC; server runs embed_execute in main process
+        and pushes result via WebSocket. Returns embed result shape; raises on
+        failure or timeout.
+        """
+        timeout_sec = float(timeout) if timeout > 0 else 60.0
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future[Dict[str, Any]] = loop.create_future()
+
+        def on_result(event: Dict[str, Any]) -> None:
+            if not fut.done():
+                fut.set_result(event)
+
+        await self.client.execute_async(
+            "embed_execute",
+            params,
+            on_result=on_result,
+            timeout=timeout_sec,
+        )
+        try:
+            event = await asyncio.wait_for(fut, timeout=timeout_sec + 5.0)
+        except asyncio.TimeoutError as e:
+            raise TimeoutError(
+                f"Embed (execute_async) did not complete within {timeout_sec}s"
+            ) from e
+
+        ev = event.get("event") or event.get("type")
+        if ev in _FAILED_TERMINAL_EVENTS:
+            err = event.get("error", "Unknown error")
+            raise EmbedClientError(f"Embed failed: {err}", error=event.get("error"))
+        if ev in _CANCELLED_TERMINAL_EVENTS:
+            err = event.get("error", "Unknown error")
+            raise EmbedClientError(f"Embed cancelled: {err}", error=event.get("error"))
+        # Accept job_completed, job_completed_success, and delivery_completed
+        # (delivery_completed is used in newer adapter versions)
+        if ev not in ("job_completed", "job_completed_success", "delivery_completed"):
+            raise EmbedClientError(
+                f"Unexpected WebSocket event: {ev} (keys: {list(event.keys())})"
+            )
+
+        return _normalize_terminal_job_payload(event)
+
+    async def _wait_for_job_via_adapter_ws(
+        self,
+        job_id: str,
+        timeout: int = 60,
+        *,
+        on_ws_event: Optional[Callable[[Dict[str, Any]], Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Wait for job completion via adapter WebSocket (/ws queue_job subscribe).
+
+        Prefers ``JsonRpcClient.wait_for_job`` when present so frames are recorded
+        in the adapter job registry; optional ``on_ws_event`` is chained after
+        adapter recording. Falls back to ``wait_for_job_via_websocket`` with
+        ``on_inbound_message`` when ``wait_for_job`` is not available.
+        """
+        if _client_has_async_method(self.client, "wait_for_job"):
+            t_arg = float(timeout) if timeout > 0 else 0.0
+            started = asyncio.get_running_loop().time()
+
+            async def _on_event(msg: Dict[str, Any]) -> None:
+                if on_ws_event is not None:
+                    await _maybe_await(on_ws_event(msg))
+
+            try:
+                payload = await self.client.wait_for_job(
+                    job_id,
+                    timeout=t_arg,
+                    on_event=_on_event,
+                )
+            except asyncio.TimeoutError as e:
+                if t_arg > 0:
+                    msg = f"Job {job_id} did not complete within {t_arg} seconds"
+                else:
+                    msg = f"Job {job_id} WebSocket wait timed out"
+                raise TimeoutError(msg) from e
+            except Exception as e:  # noqa: BLE001 - classified below
+                if not _is_ws_closed_before_terminal(e):
+                    if isinstance(e, RuntimeError):
+                        raise EmbedClientError(f"WebSocket error: {e}") from e
+                    raise
+                return await self._poll_terminal_after_ws_close(
+                    job_id, t_arg, started, e
+                )
+            return _normalize_terminal_job_payload(payload)
+
+        timeout_sec = float(timeout) if timeout > 0 else 60.0
+        try:
+            payload = await self.client.wait_for_job_via_websocket(
+                job_id,
+                timeout=timeout_sec,
+                on_inbound_message=on_ws_event,
+            )
+        except asyncio.TimeoutError as e:
+            raise TimeoutError(
+                f"Job {job_id} did not complete within {timeout_sec} seconds"
+            ) from e
+        except RuntimeError as e:
+            raise EmbedClientError(f"WebSocket error: {e}") from e
+        return _normalize_terminal_job_payload(payload)
+
+    def open_bidirectional_ws_channel(
+        self,
+        receive_timeout: float = 60.0,
+        heartbeat: float = 30.0,
+    ) -> Any:
+        """
+        Open adapter's bidirectional WebSocket channel to /ws (send + receive).
+
+        Returns the same context manager as the adapter's client: use
+        send_json() to send (e.g. subscribe/unsubscribe), receive_iter() to
+        consume server events (job_completed, job_failed, etc.).
+
+        Returns:
+            Adapter BidirectionalWsChannel (use with async with).
+        """
+        from mcp_proxy_adapter.client.jsonrpc_client import (
+            open_bidirectional_ws_channel,
+        )
+
+        return open_bidirectional_ws_channel(
+            self.client,
+            receive_timeout=receive_timeout,
+            heartbeat=heartbeat,
+        )
+
+    async def job_status(self, job_id: str) -> Dict[str, Any]:
+        """
+        Get job status (shape matches server embed_job_status result.data).
+
+        Tries queue_get_job_status first, then embed_job_status. Returns dict
+        with exists, status, done, and when completed: result (with success/data).
+
+        Args:
+            job_id: Job ID to check
+
+        Returns:
+            Server job status data (exists, status, done, result?).
+
+        Raises:
+            EmbedClientError: If status request fails
+        """
+        # Try built-in queue command first (for commands with use_queue=True)
+        try:
+            response = await self.client.jsonrpc_call(
+                "queue_get_job_status", {"job_id": job_id}
+            )
+            if "error" not in response:
+                result = response.get("result", {})
+                if result.get("success"):
+                    return result.get("data", {})
+        except Exception as e:
+            logger.debug(
+                "queue_get_job_status not available (%s), using embed_job_status",
+                e,
+            )
+
+        # Use embed_job_status when queue does not provide queue_get_job_status
+        try:
+            response = await self.client.jsonrpc_call(
+                "embed_job_status", {"job_id": job_id}
+            )
+
+            if "error" in response:
+                raise EmbedClientError(
+                    f"Status check failed: {response['error']}",
+                    error=response["error"],
+                )
+
+            result = response.get("result", {})
+            if not result.get("success"):
+                error = result.get("error", {})
+                raise EmbedClientError(
+                    f"Status check failed: {error.get('message', 'Unknown error')}",
+                    error=result.get("error"),
+                )
+
+            return result.get("data", {})
+        except Exception as e:
+            raise EmbedClientError(
+                f"Status check failed: {e}",
+                error=e.error if isinstance(e, EmbedClientError) else None,
+            ) from e
+
+    async def upload_file(
+        self,
+        source_path: str,
+        *,
+        filename: Optional[str] = None,
+    ) -> TransferReceipt:
+        """
+        Stage a local file via the adapter HTTP upload (same transport as JSON-RPC).
+
+        Delegates to :meth:`JsonRpcClient.upload_file` on the underlying client.
+        After upload, call :meth:`JsonRpcClient.get_upload_session` with the receipt's
+        ``transfer_id`` to obtain ``storage_path``, then pass that path as
+        ``input_file`` to :meth:`embed_file` (see :meth:`embed_file_from_local_json_file`).
+        """
+        return await self.client.upload_file(source_path, filename=filename)
+
+    async def embed_file(
+        self,
+        input_file: str,
+        *,
+        file_format: str = "lines",
+        model: Optional[str] = None,
+        dimension: Optional[int] = None,
+        device: Optional[str] = None,
+        error_policy: Optional[str] = None,
+        aggregation_method: Optional[str] = None,
+        provider: Optional[str] = None,
+        wait: bool = True,
+        wait_timeout: int = 600,
+        download_to: Optional[str] = None,
+        skip_download: bool = False,
+        local_source_path: Optional[str] = None,
+        on_ws_event: Optional[Callable[[Dict[str, Any]], Any]] = None,
+        on_job_id_known: Optional[Callable[[str], Any]] = None,
+        on_download_start: Optional[Callable[[str, str], Any]] = None,
+        on_download_done: Optional[Callable[[str], Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Run ``embed_file`` on the server: read texts from ``input_file``, write JSON.
+
+        Matches server command ``embed_file`` (queue job). When ``wait=True``, waits for
+        completion via WebSocket. If the result includes an outbound transfer id, the
+        client downloads via the adapter transfer HTTP API
+        (``JsonRpcClient.download_file``) and sends ``transfer_ack`` so the server can
+        remove the temp output file (when the session used ``delete_source_on_ack``).
+
+        ``input_file`` must be a path on the **server** host. After :meth:`upload_file`,
+        resolve the server-visible path with :meth:`JsonRpcClient.get_upload_session`
+        (``storage_path``) and pass it here — :meth:`embed_file_from_local_json_file`
+        does this for local ``json_array`` files.
+
+        Args:
+            input_file: Absolute path to UTF-8 file on the **server** filesystem.
+            file_format: ``lines`` or ``json_array`` (maps to server param ``format``).
+            model, dimension, device, error_policy: Same semantics as :meth:`embed`.
+            aggregation_method: Same semantics as :meth:`embed`: accepted for any
+                provider; for a nonlocal provider an over-limit entry is split
+                and aggregated server-side (default
+                ``weighted_mean_by_tokens_normalized``). For the local model it
+                is resolved by priority call -> config -> constant when omitted,
+                and the constant is ``weighted_mean_by_tokens_normalized``;
+                applied per-item, one line/array entry at a time.
+            provider: Same semantics as :meth:`embed` (``"local"`` or a live
+                macsc provider id; sent only when not ``None``; resolution order
+                and error codes as documented there).
+            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
+                ``None`` and ``skip_download`` is False, uses a temporary local path.
+            skip_download: If True, do not call ``download_file``; ``transfer_ack`` uses
+                ``checksum_value`` from the job completion payload (server metadata).
+            local_source_path: If set, after the job completes verify this file's
+                SHA-256 against ``input_checksum_value`` from the server (when
+                present).
+            on_ws_event: Optional callback for each WebSocket JSON payload while waiting
+                for the queue job (including non-terminal events). May be sync or async.
+            on_job_id_known: Called with ``job_id`` after the RPC returns and before the
+                WebSocket wait (only when ``wait=True``).
+            on_download_start: Called with ``(outbound_transfer_id, local_path)``
+                before ``download_file`` (only when a transfer id is present and
+                download runs).
+            on_download_done: Called with ``local_path`` after a successful download
+                and checksum, before ``transfer_ack``.
+
+        If the client was created with ``enable_embed_file_status_store=True``, the
+        same submit payload and WebSocket frames used for this call are recorded
+        under the job's ``job_id`` (see :meth:`get_embed_file_status_snapshot`).
+
+        Returns:
+            With wait=True: merged job ``data`` plus ``local_output_path`` when a file
+            was downloaded, and ``transfer_ack_result`` after a successful ACK.
+            With wait=False: dict with at least ``job_id`` and ``status``.
+        """
+        if not input_file or not str(input_file).strip():
+            raise EmbedClientError("embed_file: input_file is required")
+
+        params: Dict[str, Any] = {
+            "input_file": str(input_file).strip(),
+            "format": file_format,
+        }
+        if model is not None:
+            params["model"] = model
+        if dimension is not None:
+            params["dimension"] = dimension
+        if device is not None:
+            params["device"] = device
+        if error_policy is not None:
+            params["error_policy"] = error_policy
+        else:
+            params["error_policy"] = EMBED_COMMAND_SCHEMA_DEFAULT_ERROR_POLICY
+        if aggregation_method is not None:
+            params["aggregation_method"] = aggregation_method
+        if provider is not None:
+            params["provider"] = provider
+
+        response = await self.client.jsonrpc_call("embed_file", params)
+        if "error" in response:
+            raise EmbedClientError(f"embed_file failed: {response['error']}")
+
+        result = response.get("result", {})
+        if not result.get("success"):
+            err = result.get("error") or {}
+            msg = (
+                err.get("message", "Unknown error")
+                if isinstance(err, dict)
+                else str(err)
+            )
+            raise EmbedClientError(f"embed_file failed: {msg}")
+
+        nested = result.get("data")
+        nested_dict = nested if isinstance(nested, dict) else {}
+        job_id = nested_dict.get("job_id") or result.get("job_id")
+        job_id_str = str(job_id).strip() if job_id else ""
+
+        if self._embed_file_status_store is not None and job_id_str:
+            submit_snap: Dict[str, Any] = dict(nested_dict) if nested_dict else {}
+            submit_snap.setdefault("job_id", job_id_str)
+            self._embed_file_status_store.record_submit(job_id_str, submit_snap)
+
+        if not wait:
+            out: Dict[str, Any] = dict(nested_dict)
+            if job_id_str:
+                out.setdefault("job_id", job_id_str)
+            return out
+
+        if not job_id_str:
+            if isinstance(nested_dict.get("output_path"), str):
+                return dict(nested_dict)
+            raise EmbedClientError(
+                "embed_file: no job_id and no output_path in response"
+            )
+
+        tw = int(wait_timeout) if wait_timeout > 0 else 600
+        if on_job_id_known is not None:
+            await _maybe_await(on_job_id_known(job_id_str))
+
+        ws_callback: Optional[Callable[[Dict[str, Any]], Any]] = on_ws_event
+        if self._embed_file_status_store is not None and job_id_str:
+            store = self._embed_file_status_store
+            user_cb = on_ws_event
+
+            async def _embed_file_ws_with_store(ev: Dict[str, Any]) -> None:
+                if not _uses_adapter_job_message_registry(self.client):
+                    store.record_message(job_id_str, ev)
+                if user_cb is not None:
+                    await _maybe_await(user_cb(ev))
+
+            ws_callback = _embed_file_ws_with_store
+        data = await self._wait_for_job_via_adapter_ws(
+            job_id_str, tw, on_ws_event=ws_callback
+        )
+
+        fail_msg = _embed_file_queue_result_error_message(data)
+        if fail_msg:
+            inner_result = data.get("result")
+            raise EmbedClientError(
+                f"embed_file failed: {fail_msg}",
+                error=(
+                    inner_result.get("error")
+                    if isinstance(inner_result, dict)
+                    else None
+                ),
+            )
+
+        if local_source_path:
+            expected_in = _normalize_hex_checksum(data.get("input_checksum_value"))
+            if not expected_in:
+                raise EmbedClientError(
+                    "embed_file: local_source_path set but job result has no "
+                    "input_checksum_value for verification"
+                )
+            src_digest = _sha256_hex_file(local_source_path).lower()
+            if src_digest != expected_in:
+                raise EmbedClientError(
+                    "embed_file: local source file SHA256 does not match "
+                    f"server input_checksum_value (local={src_digest}, "
+                    f"server={expected_in})"
+                )
+
+        tid = str(
+            data.get("outbound_transfer_id") or data.get("transfer_id") or ""
+        ).strip()
+        if not tid:
+            return data
+
+        algo = str(data.get("checksum_algorithm") or "sha256").strip().lower()
+        local_path: Optional[str] = None
+        temp_path: Optional[str] = None
+        checksum_value: str
+
+        if skip_download:
+            cv = data.get("checksum_value")
+            if not isinstance(cv, str) or not cv.strip():
+                raise EmbedClientError(
+                    "embed_file: skip_download requires checksum_value in job result"
+                )
+            checksum_value = cv.strip().lower()
+        else:
+            if download_to:
+                local_path = download_to
+            else:
+                fd, local_path = tempfile.mkstemp(prefix="embed_file_", suffix=".json")
+                os.close(fd)
+                temp_path = local_path
+            try:
+                if on_download_start is not None:
+                    await _maybe_await(on_download_start(tid, local_path))
+                await self.client.download_file(tid, local_path)
+                expected_out = _normalize_hex_checksum(data.get("checksum_value"))
+                if not expected_out:
+                    raise EmbedClientError(
+                        "embed_file: job result missing checksum_value; "
+                        "cannot verify downloaded file integrity"
+                    )
+                local_digest = _sha256_hex_file(local_path).lower()
+                if local_digest != expected_out:
+                    raise EmbedClientError(
+                        "embed_file: downloaded file SHA256 does not match "
+                        f"server checksum_value (local={local_digest}, "
+                        f"expected={expected_out})"
+                    )
+                checksum_value = local_digest
+                if on_download_done is not None:
+                    await _maybe_await(on_download_done(local_path))
+            except Exception:
+                if temp_path:
+                    try:
+                        os.unlink(temp_path)
+                    except OSError:
+                        pass
+                raise
+
+        ack_params: Dict[str, Any] = {
+            "outbound_transfer_id": tid,
+            "checksum_algorithm": algo,
+            "checksum_value": checksum_value,
+        }
+        if job_id_str:
+            ack_params["job_id"] = job_id_str
+
+        ack_resp = await self.client.jsonrpc_call("transfer_ack", ack_params)
+        if "error" in ack_resp:
+            err = ack_resp["error"]
+            if temp_path:
+                try:
+                    os.unlink(temp_path)
+                except OSError:
+                    pass
+            raise EmbedClientError(f"transfer_ack failed: {err}")
+
+        out = dict(data)
+        if local_path is not None:
+            out["local_output_path"] = local_path
+        out["transfer_ack_result"] = ack_resp.get("result", ack_resp)
+        return out
+
+    async def embed_file_from_local_json_file(
+        self,
+        local_path: str,
+        *,
+        max_block_bytes: Optional[int] = None,
+        upload_filename: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """
+        Validate a local UTF-8 JSON ``json_array`` file (array of strings), upload
+        via the adapter, resolve ``storage_path`` via ``get_upload_session``, then run
+        :meth:`embed_file` with that path and ``format=json_array``.
+
+        See :mod:`embed_client.json_embed_file_preflight` for validation rules and
+        ``EMBED_CLIENT_MAX_JSON_BLOCK_BYTES``.
+
+        See also :mod:`embed_client.md_embed_file_prep` when strings came from
+        ``prepare-embed-file-json`` (paragraphs split on ``\\n\\n`` only).
+        """
+        from embed_client.local_json_embed_file import (
+            embed_file_from_local_json_file as _embed_local_json,
+        )
+
+        return await _embed_local_json(
+            self,
+            local_path,
+            max_block_bytes=max_block_bytes,
+            upload_filename=upload_filename,
+            **kwargs,
+        )
+
+    async def jsonrpc(
+        self, method: str, params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Low-level JSON-RPC (same transport and auth as other methods).
+
+        Prefer :meth:`embed`, :meth:`models`, :meth:`health`, etc. when applicable.
+        """
+        return await self.client.jsonrpc_call(method, params or {})
+
+    async def models(self) -> Dict[str, Any]:
+        """
+        List available models (shape matches server models command result.data).
+
+        Returns:
+            ``{"use_own_model": "none"|"ram"|"gpu", "default": {provider,
+            model}, "external": {configured, service}, "models": [...]}``; each
+            entry has name, provider, dimension, supported_dimensions,
+            max_tokens, backend and (local entries) residency. For the local
+            entry ``max_tokens`` is the real window of the loaded (own) model,
+            read from the model itself (its on-disk metadata before the load),
+            and ``null`` when unknown; it is not a fixed table. Entries are
+            unique by (provider, name). The local entry is listed only when
+            ``use_own_model`` is not ``"none"``; macsc entries are the live
+            list of providers with vectorization. macsc configured but down
+            raises -32003 EXTERNAL_UNAVAILABLE (no static fallback). The method
+            takes no parameters.
+
+        Raises:
+            EmbedClientError: If models request fails
+        """
+        response = await self.client.jsonrpc_call("models", {})
+
+        if "error" in response:
+            raise EmbedClientError(f"Models list failed: {response['error']}")
+
+        result = response.get("result", {})
+        if not result.get("success"):
+            error = result.get("error", {})
+            raise EmbedClientError(
+                f"Models list failed: {error.get('message', 'Unknown error')}"
+            )
+
+        return result.get("data", {})
+
+    async def default_model(self) -> Dict[str, Any]:
+        """Default pair of the server (provider + model) and its dimension.
+
+        The server takes no parameters. The default pair is the configured
+        default provider and model; the dimension is the configured default
+        dimension, else the entry's default dimension (local: the loaded
+        dimension). Calls that name no provider use this pair.
+
+        Returns:
+            Exactly ``{model, dimension, provider}``.
+
+        Raises:
+            EmbedAPIError: -32001 MODEL_LOADING (local default not loaded yet),
+                -32003 EXTERNAL_* when macsc fails or does not list the
+                configured default model.
+        """
+        return await self._service_command("default_model", {})
+
+    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 hold lasts until ``model_load`` (or a model selection): neither the
+        GPU watcher nor a local request moves it back; local requests are
+        served on the CPU from the RAM image meanwhile. Idempotent.
+        use_own_model ``gpu``: VRAM -> RAM, the GPU is released. ``ram``: an
+        idempotent success (residency ``ram``, device ``cpu``, ``changed``
+        false). ``none``: refused with -32004 OWN_MODEL_DISABLED. The command
+        takes no ``provider``.
+
+        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, -32004 OWN_MODEL_DISABLED.
+        """
+        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).
+
+        use_own_model ``gpu``: the model goes onto the GPU. ``ram``: refused
+        with -32005 GPU_DISABLED (any arguments). ``none``: refused with -32004
+        OWN_MODEL_DISABLED. The command takes no ``provider``.
+
+        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, -32004 OWN_MODEL_DISABLED, -32005 GPU_DISABLED.
+        """
+        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 input_limit_add(
+        self,
+        provider: str,
+        model: str,
+        max_input_tokens: int,
+        tokenizer: str,
+        max_inputs_per_request: Optional[int] = None,
+        max_total_tokens_per_request: Optional[int] = None,
+        source: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Add a manual input-limit row for (provider, model).
+
+        Cells not given are omitted from the request (server default: null for
+        the three nullable cells). The client does not validate the values.
+
+        Args:
+            provider: Provider id (``"local"`` or a macsc provider id).
+            model: Model id under that provider.
+            max_input_tokens: Positive integer limit; ``"model"`` is the only
+                value the local row accepts, so a number on ``local`` is refused.
+            tokenizer: Tokenizer name (enum ``cl100k_base``).
+            max_inputs_per_request: Positive integer or ``None``.
+            max_total_tokens_per_request: Positive integer or ``None``.
+            source: Free-text provenance of the limit, or ``None``.
+
+        Returns:
+            ``{provider, model, row: {max_input_tokens, tokenizer,
+            max_inputs_per_request, max_total_tokens_per_request, source,
+            origin: "manual"}}``.
+
+        Raises:
+            EmbedAPIError: -32602 INPUT_LIMIT_EXISTS (row already present),
+                -32602 LOCAL_LIMIT_FROM_MODEL (numeric limit on ``local``),
+                -32602 validation (unknown, missing, type or value; expected/got),
+                -32603 INPUT_LIMIT_PERSIST_FAILED (table and file unchanged).
+        """
+        params: Dict[str, Any] = {
+            "provider": provider,
+            "model": model,
+            "max_input_tokens": max_input_tokens,
+            "tokenizer": tokenizer,
+        }
+        if max_inputs_per_request is not None:
+            params["max_inputs_per_request"] = max_inputs_per_request
+        if max_total_tokens_per_request is not None:
+            params["max_total_tokens_per_request"] = max_total_tokens_per_request
+        if source is not None:
+            params["source"] = source
+        return await self._service_command("input_limit_add", params)
+
+    async def input_limit_delete(self, provider: str, model: str) -> Dict[str, Any]:
+        """Delete the input-limit row for (provider, model).
+
+        A row registered by a module is remembered as deleted (not re-added at
+        startup); a manual row with no module row is removed.
+
+        Args:
+            provider: Provider id.
+            model: Model id under that provider.
+
+        Returns:
+            ``{provider, model, deleted: true, origin_was}``.
+
+        Raises:
+            EmbedAPIError: -32602 INPUT_LIMIT_NOT_FOUND (no such row), -32602
+                validation, -32603 INPUT_LIMIT_PERSIST_FAILED (unchanged).
+        """
+        return await self._service_command(
+            "input_limit_delete", {"provider": provider, "model": model}
+        )
+
+    async def input_limit_update(
+        self,
+        provider: str,
+        model: str,
+        *,
+        max_input_tokens: Any = _NOT_GIVEN,
+        tokenizer: Any = _NOT_GIVEN,
+        max_inputs_per_request: Any = _NOT_GIVEN,
+        max_total_tokens_per_request: Any = _NOT_GIVEN,
+        source: Any = _NOT_GIVEN,
+    ) -> Dict[str, Any]:
+        """Change only the named cells of the input-limit row for (provider, model).
+
+        Only the cells passed explicitly are sent; every other cell of the row
+        stays unchanged. Passing ``None`` sends null, which the server accepts
+        only for ``max_inputs_per_request``, ``max_total_tokens_per_request`` and
+        ``source``. Updating a module row makes it a manual row (manual override).
+        Calling with no cells sends none, and the server refuses it with
+        INPUT_LIMIT_EMPTY_UPDATE.
+
+        Args:
+            provider: Provider id.
+            model: Model id under that provider.
+            max_input_tokens: Positive integer; refused on ``local``
+                (LOCAL_LIMIT_FROM_MODEL).
+            tokenizer: Tokenizer name (enum ``cl100k_base``).
+            max_inputs_per_request: Positive integer or ``None``.
+            max_total_tokens_per_request: Positive integer or ``None``.
+            source: Free-text provenance or ``None``.
+
+        Returns:
+            ``{provider, model, row: {all cells}, changed: [names of the cells
+            whose value changed], origin: "manual"}``.
+
+        Raises:
+            EmbedAPIError: -32602 INPUT_LIMIT_NOT_FOUND (no such row),
+                -32602 INPUT_LIMIT_EMPTY_UPDATE (no cell named),
+                -32602 LOCAL_LIMIT_FROM_MODEL, -32602 validation (unknown cell,
+                type or value; expected/got), -32603 INPUT_LIMIT_PERSIST_FAILED
+                (unchanged).
+        """
+        named = {
+            "max_input_tokens": max_input_tokens,
+            "tokenizer": tokenizer,
+            "max_inputs_per_request": max_inputs_per_request,
+            "max_total_tokens_per_request": max_total_tokens_per_request,
+            "source": source,
+        }
+        params: Dict[str, Any] = {"provider": provider, "model": model}
+        for name, value in named.items():
+            if value is not _NOT_GIVEN:
+                params[name] = value
+        return await self._service_command("input_limit_update", params)
+
+    async def input_limit_list(self, provider: Optional[str] = None) -> Dict[str, Any]:
+        """List input-limit rows, sorted by (provider, model), unique by key.
+
+        Reads no model and makes no provider call. Deletion marks are not shown.
+
+        Args:
+            provider: Optional provider filter; sent only when not ``None``.
+
+        Returns:
+            ``{rows: [{provider, model, max_input_tokens, tokenizer,
+            max_inputs_per_request, max_total_tokens_per_request, source,
+            origin: "module" | "manual"}]}``; a provider with no rows gives
+            ``rows: []``.
+
+        Raises:
+            EmbedAPIError: -32602 validation (unknown parameter, value).
+        """
+        params: Dict[str, Any] = {}
+        if provider is not None:
+            params["provider"] = provider
+        return await self._service_command("input_limit_list", params)
+
+    async def list_commands(self) -> Dict[str, Any]:
+        """
+        List available commands.
+
+        Returns:
+            Available commands information
+        """
+        return await list_commands_via_client(self.client.jsonrpc_call)
+
+    async def cmd(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        auto_poll: bool = True,
+    ) -> Dict[str, Any]:
+        """Execute a command via the adapter unified path (CLI and legacy callers).
+
+        Callers of this package depend on its own error type, not on whichever
+        exception the transport happens to raise, so an adapter failure and a
+        command that answered with a refusal both arrive as
+        :class:`EmbedAPIError` carrying the server's own error.
+        """
+        try:
+            result = await self.client.execute_command_unified(
+                command=command,
+                params=params or {},
+                auto_poll=auto_poll,
+            )
+        except EmbedError:
+            raise
+        except Exception as exc:
+            if _missing_from_worker_registry(exc):
+                try:
+                    return await self._cmd_over_jsonrpc(command, params or {})
+                except EmbedError:
+                    raise
+                except Exception as direct_exc:
+                    raise EmbedAPIError(str(direct_exc)) from direct_exc
+            raise EmbedAPIError(str(exc)) from exc
+        failure = _find_failed_command_result(result)
+        if failure is not None:
+            raise EmbedAPIError(failure)
+        return result
+
+    async def _cmd_over_jsonrpc(
+        self, command: str, params: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Run *command* over plain JSON-RPC and return its payload."""
+        response = await self.client.jsonrpc_call(command, params)
+        if isinstance(response, dict) and response.get("error") is not None:
+            raise EmbedAPIError(response["error"])
+        payload = response.get("result") if isinstance(response, dict) else None
+        if not isinstance(payload, dict):
+            raise EmbedAPIError(f"Command {command!r} returned {response!r}")
+        failure = _find_failed_command_result(payload)
+        if failure is not None:
+            raise EmbedAPIError(failure)
+        return payload
+
+    async def list_queued_commands(
+        self,
+        status: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """List queued jobs (adapter ``queue_list_jobs``).
+
+        The command takes ``status_filter`` and ``limit``; the transport helper
+        of the same name sends ``status``/``job_type`` instead and the server
+        rejects the call, so the request is made directly.
+        """
+        params: Dict[str, Any] = {}
+        if status:
+            params["status_filter"] = status
+        if limit:
+            params["limit"] = int(limit)
+        response = await self.client.jsonrpc_call("queue_list_jobs", 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"queue_list_jobs returned {response!r}")
+        failure = _find_failed_command_result(result)
+        if failure is not None:
+            raise EmbedAPIError(failure)
+        return result
+
+    async def cancel_command(self, job_id: str) -> Dict[str, Any]:
+        """Stop and delete a queued job."""
+        await self.client.queue_stop_job(job_id)
+        return await self.client.queue_delete_job(job_id)
+
+    async def get_job_logs(self, job_id: str) -> Dict[str, Any]:
+        """Fetch logs for a queued job (adapter ``queue_get_job_logs``)."""
+        return await self.client.queue_get_job_logs(job_id)
+
+    async def timing_stats(self, file_path: Optional[str] = None) -> Dict[str, Any]:
+        """Fetch timing statistics RPC (when enabled on server)."""
+        params: Dict[str, Any] = {}
+        if file_path is not None and str(file_path).strip():
+            params["file_path"] = str(file_path).strip()
+        response = await self.client.jsonrpc_call("timing_stats", params)
+        if "error" in response:
+            raise EmbedClientError(f"timing_stats failed: {response['error']}")
+        result = response.get("result", {})
+        if isinstance(result, dict) and result.get("success") is False:
+            err = result.get("error", {})
+            msg = (
+                err.get("message", "Unknown error")
+                if isinstance(err, dict)
+                else str(err)
+            )
+            raise EmbedClientError(f"timing_stats failed: {msg}")
+        return result.get("data", result)
+
+    async def __aenter__(self) -> "EmbeddingClient":
+        """Async context manager entry (standalone package convenience)."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Release the adapter HTTP client (httpx) and related resources."""
+        await self.client.close()
+
+    async def fetch_openapi_schema(self) -> Dict[str, Any]:
+        """
+        Load ``GET /openapi.json`` using the same TLS and auth headers as JSON-RPC.
+
+        Delegates to ``JsonRpcClient.get_openapi_schema`` on the underlying client.
+        """
+        return await self.client.get_openapi_schema()
+
+    async def http_get(self, path: str) -> tuple[int, str]:
+        """
+        ``GET`` a path under the service base URL (e.g. ``/``, ``/docs``).
+
+        Uses the shared async httpx client from ``JsonRpcClient.get_async_http_client``
+        (same ``base_url`` and ``headers`` as JSON-RPC, including API key or
+        ``Authorization``).
+
+        Returns:
+            ``(status_code, response_text)``.
+        """
+        client = await self.client.get_async_http_client()
+        p = path if path.startswith("/") else f"/{path}"
+        response = await client.get(
+            f"{self.client.base_url}{p}",
+            headers=self.client.headers,
+        )
+        return response.status_code, response.text
+
+    def __repr__(self) -> str:
+        """String representation of client."""
+        return f"EmbeddingClient({self.protocol}://{self.host}:{self.port})"
+
+    @classmethod
+    def from_config(cls, config: "ClientConfig") -> "EmbeddingClient":
+        """Build client from a loaded :class:`~embed_client.config.ClientConfig`."""
+        return embedding_client_from_config_dict(config.get_all())
+
+
+def embedding_client_from_config_dict(config_dict: Dict[str, Any]) -> "EmbeddingClient":
+    """Build :class:`EmbeddingClient` from embed-client ``config_dict`` (adapter-shaped)."""
+    from embed_client.adapter_config_factory import AdapterConfigFactory
+
+    p = AdapterConfigFactory.from_config_dict(config_dict)
+    auth = config_dict.get("auth") or {}
+    ssl = config_dict.get("ssl")
+    client = EmbeddingClient(
+        protocol=p["protocol"],
+        host=p["host"],
+        port=int(p["port"]),
+        cert=p.get("cert"),
+        key=p.get("key"),
+        ca=p.get("ca"),
+        check_hostname=bool(p.get("check_hostname", False)),
+        token=p.get("token"),
+        token_header=p.get("token_header"),
+        timeout=float(p.get("timeout", 120.0)),
+    )
+    client._auth_method = auth.get("method")
+    client._ssl_settings = dict(ssl) if isinstance(ssl, dict) else None
+    return client