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

embed_client/example_async_usage_ru_demo.py

@@ -0,0 +1,313 @@
+"""
+Вспомогательные демонстрационные функции для ``embed_client/example_async_usage_ru.py``.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+
+**run_client_examples** — короткий тур: health, OpenAPI, команды, ``cmd('embed')``.
+
+**demonstrate_security_modes** и связанные функции — печать сценариев
+``ClientFactory`` без обязательного живого сервера.
+
+Используется :class:`~embed_client.embedding_client.EmbeddingClient` и фабрика.
+"""
+
+from __future__ import annotations
+
+import ssl
+from typing import Any, Dict, List
+
+from embed_client.embedding_client import EmbeddingClient
+from embed_client.exceptions import EmbedError
+from embed_client.client_factory import ClientFactory, detect_security_mode
+from embed_client.response_parsers import extract_embeddings
+
+
+async def run_client_examples(client: EmbeddingClient) -> None:
+    """
+    Короткий интерактивный тур (health, OpenAPI, список команд, embed).
+
+    При ошибке health выводит сообщение и завершает функцию; остальные шаги ловят свои исключения.
+    """
+    # Проверка здоровья сервиса
+    try:
+        health = await client.health()
+        print("Состояние сервиса:", health)
+    except EmbedError as exc:
+        print(f"Ошибка при проверке состояния сервиса: {exc}")
+        return
+
+    # Получение OpenAPI схемы
+    try:
+        schema = await client.fetch_openapi_schema()
+        version = schema.get("info", {}).get("version", "unknown")
+        print("Версия OpenAPI схемы:", version)
+    except EmbedError as exc:
+        print(f"Ошибка при получении OpenAPI схемы: {exc}")
+
+    # Получение списка доступных команд
+    try:
+        commands = await client.list_commands()
+        print(f"Доступные команды: {commands}")
+    except EmbedError as exc:
+        print(f"Ошибка при получении списка команд: {exc}")
+
+    # Генерация эмбеддингов
+    try:
+        texts = [
+            "Привет, мир!",
+            "Это тестовое предложение.",
+            "Сервис эмбеддингов работает!",
+        ]
+        result = await client.cmd("embed", {"texts": texts})
+
+        embeddings = extract_embeddings(result)
+        count = len(embeddings) if embeddings is not None else 0
+        print(f"Сгенерировано эмбеддингов: {count}")
+        first_dim = (
+            len(embeddings[0])
+            if embeddings and len(embeddings) > 0 and embeddings[0] is not None
+            else 0
+        )
+        print("Размерность первого эмбеддинга:", first_dim)
+    except EmbedError as exc:
+        print(f"Ошибка при генерации эмбеддингов: {exc}")
+
+
+async def demonstrate_security_modes() -> None:
+    """
+    Печать шести шаблонов создания клиентов через ``ClientFactory`` (HTTP … mTLS+roles).
+
+    Не подключается к серверу сама по себе.
+    """
+    print("=== Демонстрация режимов безопасности ===")
+    print("Этот пример показывает, как создавать клиентов для всех 6 режимов.")
+    print(
+        "Важно: примеры создают конфигурации клиентов, но не подключаются "
+        "к реальным серверам."
+    )
+
+    # 1. HTTP
+    print("\n1. HTTP режим (без аутентификации, без SSL):")
+    print("   Использование: разработка, внутренние сети, доверенная среда")
+    try:
+        client = ClientFactory.create_http_client("http://localhost", 8001)
+        print(f"   ✓ HTTP клиент: {client.base_url}:{client.port}")
+        print(f"   ✓ SSL включён: {client.is_ssl_enabled()}")
+        print(f"   ✓ Аутентифицирован: {client.is_authenticated()}")
+        print(f"   ✓ Метод аутентификации: {client.get_auth_method()}")
+        await client.close()
+    except Exception as exc:  # noqa: BLE001
+        print(f"   ✗ Ошибка: {exc}")
+
+    # 2. HTTP + Token
+    print("\n2. HTTP + Token (HTTP с API ключом):")
+    print("   Использование: управление доступом к API, простая аутентификация")
+    try:
+        client = ClientFactory.create_http_token_client(
+            "http://localhost", 8001, "api_key", api_key="demo_key"
+        )
+        print(f"   ✓ HTTP + Token клиент: {client.base_url}:{client.port}")
+        print(f"   ✓ SSL включён: {client.is_ssl_enabled()}")
+        print(f"   ✓ Аутентифицирован: {client.is_authenticated()}")
+        print(f"   ✓ Метод аутентификации: {client.get_auth_method()}")
+        if client.is_authenticated():
+            headers = client.get_auth_headers()
+            print(f"   ✓ Заголовки аутентификации: {headers}")
+        await client.close()
+    except Exception as exc:  # noqa: BLE001
+        print(f"   ✗ Ошибка: {exc}")
+
+    # 3. HTTPS
+    print("\n3. HTTPS режим (шифрование с сертификатами сервера):")
+    print("   Использование: защищённое соединение, публичные сети")
+    try:
+        client = ClientFactory.create_https_client("https://localhost", 9443)
+        print(f"   ✓ HTTPS клиент: {client.base_url}:{client.port}")
+        print(f"   ✓ SSL включён: {client.is_ssl_enabled()}")
+        print(f"   ✓ Аутентифицирован: {client.is_authenticated()}")
+        if client.is_ssl_enabled():
+            ssl_config = client.get_ssl_config()
+            print(f"   ✓ SSL конфигурация: {ssl_config}")
+            print(f"   ✓ OpenSSL / TLS: {ssl.OPENSSL_VERSION}")
+        await client.close()
+    except Exception as exc:  # noqa: BLE001
+        print(f"   ✗ Ошибка: {exc}")
+
+    # 4. HTTPS + Token
+    print("\n4. HTTPS + Token (HTTPS + аутентификация):")
+    print("   Использование: защищённый доступ к API, production")
+    try:
+        client = ClientFactory.create_https_token_client(
+            "https://localhost",
+            9443,
+            "basic",
+            username="admin",
+            password="secret",
+        )
+        print(f"   ✓ HTTPS + Token клиент: {client.base_url}:{client.port}")
+        print(f"   ✓ SSL включён: {client.is_ssl_enabled()}")
+        print(f"   ✓ Аутентифицирован: {client.is_authenticated()}")
+        print(f"   ✓ Метод аутентификации: {client.get_auth_method()}")
+        if client.is_authenticated():
+            headers = client.get_auth_headers()
+            print(f"   ✓ Заголовки аутентификации: {headers}")
+        await client.close()
+    except Exception as exc:  # noqa: BLE001
+        print(f"   ✗ Ошибка: {exc}")
+
+    # 5. mTLS
+    print("\n5. mTLS (взаимная TLS, сертификаты клиента и сервера):")
+    print("   Использование: максимальная безопасность, аутентификация клиента")
+    try:
+        client = ClientFactory.create_mtls_client(
+            "https://localhost",
+            "mtls_certificates/client/embedding-service.crt",
+            "mtls_certificates/client/embedding-service.key",
+            8443,
+        )
+        print(f"   ✓ mTLS клиент: {client.base_url}:{client.port}")
+        print(f"   ✓ SSL включён: {client.is_ssl_enabled()}")
+        print(f"   ✓ mTLS включён: {client.is_mtls_enabled()}")
+        print(f"   ✓ Аутентифицирован: {client.is_authenticated()}")
+        if client.is_ssl_enabled():
+            ssl_config = client.get_ssl_config()
+            print(f"   ✓ SSL конфигурация: {ssl_config}")
+        await client.close()
+    except Exception as exc:  # noqa: BLE001
+        print(f"   ✗ Ошибка: {exc}")
+
+    # 6. mTLS + Roles
+    print("\n6. mTLS + Roles (mTLS + роли):")
+    print("   Использование: корпоративная безопасность, права доступа по ролям")
+    try:
+        client = ClientFactory.create_mtls_roles_client(
+            "https://localhost",
+            "mtls_certificates/client/embedding-service.crt",
+            "mtls_certificates/client/embedding-service.key",
+            8443,
+            roles=["admin", "user"],
+            role_attributes={"department": "IT"},
+        )
+        print(f"   ✓ mTLS + Roles клиент: {client.base_url}:{client.port}")
+        print(f"   ✓ SSL включён: {client.is_ssl_enabled()}")
+        print(f"   ✓ mTLS включён: {client.is_mtls_enabled()}")
+        print(f"   ✓ Аутентифицирован: {client.is_authenticated()}")
+        if client.is_authenticated():
+            headers = client.get_auth_headers()
+            print(f"   ✓ Заголовки аутентификации: {headers}")
+        await client.close()
+    except Exception as exc:  # noqa: BLE001
+        print(f"   ✗ Ошибка: {exc}")
+
+    print("\n=== Краткое резюме режимов безопасности ===")
+    print("1. HTTP: базовая связность, без безопасности")
+    print("2. HTTP + Token: API ключ поверх HTTP")
+    print("3. HTTPS: шифрование с сертификатами сервера")
+    print("4. HTTPS + Token: шифрование + аутентификация")
+    print("5. mTLS: взаимная аутентификация сертификатами")
+    print("6. mTLS + Roles: сертификаты + контроль доступа по ролям")
+
+
+async def demonstrate_automatic_detection() -> None:
+    """Демонстрация автоматического определения режима безопасности."""
+    print("\n=== Автоматическое определение режима безопасности ===")
+    print(
+        "Этот пример показывает, как клиент автоматически определяет "
+        "подходящий режим безопасности."
+    )
+
+    test_cases: List[Any] = [
+        ("http://localhost", None, None, None, None, "HTTP"),
+        ("http://localhost", "api_key", None, None, None, "HTTP + Token"),
+        ("https://localhost", None, None, None, None, "HTTPS"),
+        ("https://localhost", "api_key", None, None, None, "HTTPS + Token"),
+        ("https://localhost", None, None, "cert.pem", "key.pem", "mTLS"),
+        (
+            "https://localhost",
+            None,
+            None,
+            "cert.pem",
+            "key.pem",
+            "mTLS + Roles",
+            {"roles": ["admin"]},
+        ),
+    ]
+
+    for case in test_cases:
+        if len(case) == 6:
+            base_url, auth_method, ssl_enabled, cert_file, key_file, expected = case
+            kwargs: Dict[str, Any] = {}
+        else:
+            (
+                base_url,
+                auth_method,
+                ssl_enabled,
+                cert_file,
+                key_file,
+                expected,
+                kwargs,
+            ) = case
+
+        try:
+            mode = detect_security_mode(
+                base_url, auth_method, ssl_enabled, cert_file, key_file, **kwargs
+            )
+            print(
+                f"  ✓ {base_url} + {auth_method or 'none'} + "
+                f"{cert_file or 'no cert'} -> {mode} ({expected})"
+            )
+        except Exception as exc:  # noqa: BLE001
+            print(f"  ✗ Ошибка при определении режима для {base_url}: {exc}")
+
+
+async def demonstrate_with_auth_method() -> None:
+    """Демонстрация метода with_auth для динамической аутентификации."""
+    print("\n=== Динамическая аутентификация с помощью with_auth() ===")
+    print(
+        "Пример показывает, как создавать клиентов с разными методами "
+        "аутентификации, используя метод класса with_auth."
+    )
+
+    auth_examples = [
+        ("api_key", {"api_key": "dynamic_api_key"}, "API Key аутентификация"),
+        (
+            "jwt",
+            {"secret": "secret", "username": "user", "password": "pass"},
+            "JWT аутентификация",
+        ),
+        ("basic", {"username": "admin", "password": "secret"}, "Basic аутентификация"),
+        (
+            "certificate",
+            {"cert_file": "client.crt", "key_file": "client.key"},
+            "Certificate аутентификация",
+        ),
+    ]
+
+    for auth_method, kwargs, description in auth_examples:
+        try:
+            print(f"\n{description}:")
+            auth_client = EmbeddingClient.with_auth(
+                "http://localhost",
+                8001,
+                auth_method,
+                **kwargs,
+            )
+            print(f"  ✓ Метод аутентификации: {auth_client.get_auth_method()}")
+            print(f"  ✓ Аутентифицирован: {auth_client.is_authenticated()}")
+            if auth_client.is_authenticated():
+                headers = auth_client.get_auth_headers()
+                print(f"  ✓ Заголовки аутентификации: {headers}")
+            await auth_client.close()
+        except Exception as exc:  # noqa: BLE001
+            print(f"  ✗ Ошибка для {auth_method}: {exc}")
+
+    print("\n✓ Демонстрация динамической аутентификации завершена.")
+
+
+__all__ = [
+    "run_client_examples",
+    "demonstrate_security_modes",
+    "demonstrate_automatic_detection",
+    "demonstrate_with_auth_method",
+]

embed_client/exceptions.py

@@ -0,0 +1,122 @@
+"""
+Project-wide custom exceptions for embed-client (aligned with embedding service server).
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+import copy
+from typing import Any, Optional
+
+
+class EmbedError(Exception):
+    """Base exception for all embed package errors."""
+
+    def __init__(self, message: str, *args: object, **kwargs: object) -> None:
+        super().__init__(message, *args, **kwargs)
+        self.message = message
+
+
+class EmbedConfigError(EmbedError):
+    """Config load, parse or validation failure."""
+
+
+class EmbedQueueError(EmbedError):
+    """Queue not initialized, submit failed, or job not found in queue."""
+
+
+class EmbedClientError(EmbedError):
+    """
+    Client-facing failure: embed failed, job not found, status check failed,
+    or models list failed.
+
+    Attributes:
+        error: Deep copy of the original terminal error object as received (a
+            dict, or a str when the producer sent a string); ``None`` when the
+            failure carries none.
+        code: ``error["code"]`` when ``error`` is a dict with a ``code`` key,
+            else ``None``.
+        data: Deep copy of ``error["data"]`` when ``error`` is a dict with a
+            ``data`` key, else ``None``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *args: object,
+        error: Optional[Any] = None,
+        **kwargs: object,
+    ) -> None:
+        super().__init__(message, *args, **kwargs)
+        self.error: Any = copy.deepcopy(error)
+        self.code: Any = None
+        self.data: Any = None
+        if isinstance(self.error, dict):
+            self.code = self.error.get("code")
+            if "data" in self.error:
+                self.data = copy.deepcopy(self.error["data"])
+
+
+class EmbedServiceError(EmbedError):
+    """Generic service or runtime failure (e.g. model load, encode, I/O)."""
+
+
+class ModelServerUnavailableError(EmbedError):
+    """Model server health check failed or connection error; use direct service."""
+
+
+class EmbedGpuOutOfMemoryError(EmbedError):
+    """
+    GPU ran out of memory while loading or running the embedding model.
+    User message suggests using CPU (embedding.device=cpu) or freeing GPU memory.
+    """
+
+
+class EmbedHTTPError(EmbedClientError):
+    """
+    HTTP layer error (4xx, 5xx) from transport or adapter.
+
+    Attributes:
+        status: HTTP status code returned by the server.
+        message: Short human-readable message (same as historical client).
+    """
+
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.message = message
+
+
+class EmbedAPIError(EmbedClientError):
+    """
+    Error returned by the Embedding Service API in the response body.
+
+    The raw error payload from the API is stored in the ``error`` attribute.
+    """
+
+    def __init__(self, error: Any) -> None:
+        super().__init__(f"API error: {error}")
+        self.error = error
+
+
+class EmbedTimeoutError(EmbedClientError):
+    """Request to the Embedding Service timed out."""
+
+
+class EmbedJSONError(EmbedClientError):
+    """JSON parsing of a response body failed."""
+
+
+__all__ = [
+    "EmbedError",
+    "EmbedConfigError",
+    "EmbedQueueError",
+    "EmbedClientError",
+    "EmbedServiceError",
+    "ModelServerUnavailableError",
+    "EmbedGpuOutOfMemoryError",
+    "EmbedHTTPError",
+    "EmbedAPIError",
+    "EmbedTimeoutError",
+    "EmbedJSONError",
+]

embed_client/identifier_types.py

@@ -0,0 +1,56 @@
+"""
+Type definitions and validation functions for identifier types.
+
+This module provides type-safe identifiers to distinguish between:
+- JobId: Queue job identifiers from server queue operations
+- DeliverId: Adapter-managed WebSocket delivery/correlation identifiers
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import NewType
+
+JobId = NewType("JobId", str)
+DeliverId = NewType("DeliverId", str)
+
+
+def is_valid_job_id(identifier: str) -> bool:
+    """
+    Validate that a string is a valid job_id.
+
+    A valid job_id is a non-empty string after stripping whitespace.
+
+    Args:
+        identifier: String to validate.
+
+    Returns:
+        True if identifier is a non-empty string after stripping, False otherwise.
+    """
+    if not isinstance(identifier, str):
+        return False
+    stripped = identifier.strip()
+    return len(stripped) > 0
+
+
+def is_valid_deliver_id(identifier: str) -> bool:
+    """
+    Validate that a string is a valid deliver_id.
+
+    A valid deliver_id is a non-empty string after stripping whitespace.
+
+    Args:
+        identifier: String to validate.
+
+    Returns:
+        True if identifier is a non-empty string after stripping, False otherwise.
+    """
+    if not isinstance(identifier, str):
+        return False
+    stripped = identifier.strip()
+    return len(stripped) > 0
+
+
+__all__ = ["JobId", "DeliverId", "is_valid_job_id", "is_valid_deliver_id"]

embed_client/json_embed_file_preflight.py

@@ -0,0 +1,128 @@
+"""
+Client-side validation for local JSON files used with ``embed_file`` (``json_array``).
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, List, Optional
+
+from embed_client.constants import DEFAULT_MAX_JSON_EMBED_BLOCK_BYTES
+from embed_client.exceptions import EmbedClientError
+
+
+def resolve_max_json_block_bytes(explicit: Optional[int] = None) -> int:
+    """
+    Return max UTF-8 byte length per ``json_array`` item (one string per array element).
+
+    Order: *explicit* if set, else ``EMBED_CLIENT_MAX_JSON_BLOCK_BYTES``, else
+    :data:`DEFAULT_MAX_JSON_EMBED_BLOCK_BYTES`.
+    """
+    if explicit is not None:
+        if explicit < 1:
+            raise EmbedClientError("max_block_bytes must be >= 1")
+        return explicit
+    raw = os.environ.get("EMBED_CLIENT_MAX_JSON_BLOCK_BYTES", "").strip()
+    if raw:
+        try:
+            v = int(raw, 10)
+        except ValueError as e:
+            raise EmbedClientError(
+                "EMBED_CLIENT_MAX_JSON_BLOCK_BYTES must be a positive integer"
+            ) from e
+        if v < 1:
+            raise EmbedClientError("EMBED_CLIENT_MAX_JSON_BLOCK_BYTES must be >= 1")
+        return v
+    return DEFAULT_MAX_JSON_EMBED_BLOCK_BYTES
+
+
+def validate_local_json_embed_file(
+    path: str, *, max_block_bytes: Optional[int] = None
+) -> None:
+    """
+    Ensure *path* is a readable file, content is JSON, root is a non-empty array
+    of strings (UTF-8 text per item, as the server ``embed_file`` ``json_array``
+    format expects); each item's UTF-8 size is within the configured maximum.
+
+    Raises:
+        EmbedClientError: On missing file, non-JSON content, or schema/size violations.
+    """
+    if not path or not path.strip():
+        raise EmbedClientError("local JSON embed file path is empty")
+    ap = os.path.abspath(path)
+    if not os.path.isfile(ap):
+        raise EmbedClientError(f"not a file or not found: {ap}")
+    if not os.access(ap, os.R_OK):
+        raise EmbedClientError(f"file not readable: {ap}")
+
+    try:
+        with open(ap, "rb") as f:
+            raw = f.read()
+    except OSError as e:
+        raise EmbedClientError(f"cannot read file: {ap}: {e}") from e
+
+    try:
+        text = raw.decode("utf-8-sig")
+    except UnicodeDecodeError as e:
+        raise EmbedClientError(f"file must be UTF-8 (with optional BOM): {ap}") from e
+
+    stripped = text.lstrip()
+    if not stripped:
+        raise EmbedClientError(f"file is empty: {ap}")
+    if stripped[0] != "[":
+        raise EmbedClientError(
+            f"json_array embed file must be a JSON array at root (starts with '['): {ap}"
+        )
+
+    try:
+        data: Any = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise EmbedClientError(f"invalid JSON in {ap}: {e}") from e
+
+    if not isinstance(data, list):
+        raise EmbedClientError(
+            f"JSON root must be an array for json_array format: {ap}"
+        )
+    if len(data) == 0:
+        raise EmbedClientError(f"JSON array must not be empty: {ap}")
+
+    max_b = resolve_max_json_block_bytes(max_block_bytes)
+    for i, item in enumerate(data):
+        if not isinstance(item, str):
+            raise EmbedClientError(
+                f"item {i} must be a string (UTF-8 text to embed), "
+                f"got {type(item).__name__}: {ap}"
+            )
+        nbytes = len(item.encode("utf-8"))
+        if nbytes > max_b:
+            raise EmbedClientError(
+                f"item {i} exceeds max block size ({nbytes} > {max_b} bytes): {ap}"
+            )
+
+
+def iter_json_array_block_texts(path: str) -> List[str]:
+    """
+    After :func:`validate_local_json_embed_file`, load and return array strings
+    in order (for tests / introspection).
+    """
+    with open(path, "rb") as f:
+        raw = f.read()
+    text = raw.decode("utf-8-sig")
+    data = json.loads(text)
+    assert isinstance(data, list)
+    out: List[str] = []
+    for item in data:
+        assert isinstance(item, str)
+        out.append(item)
+    return out
+
+
+__all__ = [
+    "iter_json_array_block_texts",
+    "resolve_max_json_block_bytes",
+    "validate_local_json_embed_file",
+]

embed_client/local_json_embed_file.py

@@ -0,0 +1,73 @@
+"""
+Upload a validated local JSON file, resolve the server-side storage path, and run
+:meth:`EmbeddingClient.embed_file` with ``input_file`` set to that path (same pattern
+as the reference ``upload_file`` → ``get_upload_session`` → ``embed_file`` flow).
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+from embed_client.exceptions import EmbedClientError
+from embed_client.json_embed_file_preflight import validate_local_json_embed_file
+
+if TYPE_CHECKING:
+    from embed_client.embedding_client import EmbeddingClient
+
+
+async def embed_file_from_local_json_file(
+    client: "EmbeddingClient",
+    local_path: str,
+    *,
+    max_block_bytes: Optional[int] = None,
+    upload_filename: Optional[str] = None,
+    **embed_file_kwargs: Any,
+) -> Dict[str, Any]:
+    """
+    Validate a local ``json_array`` file, upload via the adapter, resolve
+    ``storage_path`` via ``JsonRpcClient.get_upload_session``, then
+    :meth:`~embed_client.embedding_client.EmbeddingClient.embed_file` with
+    ``input_file`` set to that server-visible path and ``format=json_array``.
+
+    ``local_source_path`` is set to *local_path* so optional server-side input
+    checksum verification can match the uploaded bytes.
+    """
+    validate_local_json_embed_file(local_path, max_block_bytes=max_block_bytes)
+    ap = os.path.abspath(local_path)
+    receipt = await client.upload_file(ap, filename=upload_filename)
+    if receipt.completed is not True:
+        raise EmbedClientError(
+            "adapter upload did not complete before embed_file "
+            f"(transfer_id={receipt.transfer_id!r})"
+        )
+    session = await client.client.get_upload_session(receipt.transfer_id)
+    if not isinstance(session, dict):
+        raise EmbedClientError(
+            "get_upload_session did not return a mapping; cannot run embed_file "
+            f"(transfer_id={receipt.transfer_id!r})"
+        )
+    storage_path = session.get("storage_path")
+    if not isinstance(storage_path, str) or not storage_path.strip():
+        raise EmbedClientError(
+            "upload session did not return storage_path; cannot run embed_file "
+            f"(transfer_id={receipt.transfer_id!r})"
+        )
+    server_input = storage_path.strip()
+    # Drop kwargs that would collide with our contract
+    embed_file_kwargs.pop("file_format", None)
+    embed_file_kwargs.pop("input_file", None)
+    embed_file_kwargs.pop("inbound_transfer", None)
+    embed_file_kwargs.pop("local_source_path", None)
+    return await client.embed_file(
+        server_input,
+        local_source_path=ap,
+        file_format="json_array",
+        **embed_file_kwargs,
+    )
+
+
+__all__ = ["embed_file_from_local_json_file"]