embed-client

Python async client for the Embedding Service API. The canonical public client is EmbeddingClient, aligned with the migrated server-side contract (JSON-RPC via mcp-proxy-adapter).

from embed_client import EmbeddingClient

Installation

pip install embed-client

Editable development checkout:

git clone <repository-url>
cd embed-client
pip install -e .

Canonical real-server E2E (localhost:8001, mTLS)

The repository ships a runnable end-to-end tour of the public API against localhost:8001 with mTLS, using certificates under mtls_certificates/ (see mtls_certificates/README.md if present).

Artifact	Path
Example script	`examples/canonical_mtls_localhost_8001.py`
Live integration	Set `RUN_CANONICAL_MTLS_E2E=1` to perform real network calls (otherwise dry run / config check)
Optional `embed_file`	Set `CANONICAL_EMBED_FILE_SERVER_PATH` to a server-visible file path to include `embed_file` in the tour
Tests	`tests/test_canonical_mtls_example.py`

python examples/canonical_mtls_localhost_8001.py
RUN_CANONICAL_MTLS_E2E=1 python examples/canonical_mtls_localhost_8001.py

Minimal usage

import asyncio
from embed_client import EmbeddingClient

async def main() -> None:
    async with EmbeddingClient.from_base_url_port("http://localhost", 8001) as client:
        h = await client.health()
        print("health:", h)
        data = await client.embed(["hello"], error_policy="continue", wait=True)
        print("embed keys:", list(data.keys()) if isinstance(data, dict) else type(data))

if __name__ == "__main__":
    asyncio.run(main())

Public queue-oriented helpers include embed, wait_for_job, job_status, list_queued_commands, cmd, optional embed_file, plus introspection (list_commands, models, fetch_openapi_schema, http_get, timing_stats) and TLS helpers is_mtls_enabled, get_ssl_config. See embed_client/embedding_client.py for the full list.

embed_file vs local JSON without shared server disk: use embed_file with a server-visible input_file when the input already exists on the service host. For a json_array file that exists only on the client machine (no shared filesystem), use the CLI embed-file-json subcommand (or embed_file_from_local_json_file) so the client validates, uploads through the adapter, resolves storage_path via get_upload_session, then runs embed_file with that path and format=json_array. For Markdown sources (e.g. with YAML front matter), run prepare-embed-file-json first to emit a valid json_array (array of strings): the body is split only on blank lines (\n\n) into paragraph-sized strings, with per-paragraph UTF-8 size limits and no automatic oversize split — oversized paragraphs require editing the source or raising the byte cap; then embed-file-json. Add --show-progress to stream server WebSocket/status lines to stderr during the job wait (see CLI_README.md).

Documentation

CONFIGURATION.md — JSON config schema, protocols, validation
CLI_README.md — embed-config-generator, embed-config-validator, embed-vectorize
docs/api_format.md — JSON-RPC shapes for embed and embed_file (server path vs upload)
examples/README.md — example index (canonical mTLS first)
docs/SERVER_MODES_AND_CLIENT.md — security modes vs client behavior (short summary; not full matrix)

Security modes

The server supports multiple HTTP/HTTPS/mTLS and auth combinations. For deploy-time verification expectations, see the project deploy rule; for field-level mapping, see CONFIGURATION.md and docs/SERVER_MODES_AND_CLIENT.md.

Development and tests

Run the test suite with pytest; configuration lives in pyproject.toml ([tool.pytest.ini_options]). There is no pytest.ini at the repository root.

pytest -q

License

MIT License

Author

Vasiliy Zdanovskiy — vasilyvz@gmail.com

Metadata

Release files for embed-client 4.0.25

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for embed-client 4.0.25
File	Size	Uploaded
embed_client-4.0.25.tar.gz	238.3 kB	Oct 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for embed-client 4.0.25
File	Interpreter	ABI	Platform	Reset
embed_client-4.0.25-py3-none-any.whl 100.2 kB Oct 1, 2026	Python 3	none	any	Details

Total release size: 338.5 kB

Release files / embed_client-4.0.25.tar.gz

Download URL	embed_client-4.0.25.tar.gz
Size	238.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`29237d1b6585168c3865cc6bf69fca7c995d42e1d9e4ec69df074ebe97666758`
BLAKE2b-256 checksum How to use checksums	`5d4255484621e5b1e4ba2a615d3cd42972d0700f2110ef8439b0288a8d05ae23`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.4`

Release files / embed_client-4.0.25-py3-none-any.whl

Download URL	embed_client-4.0.25-py3-none-any.whl
Size	100.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e8efdbbaf7bdf50321b0977291e823ebe6b1bf41f83c95e0bf77c10cd4cb01be`
BLAKE2b-256 checksum How to use checksums	`6ae44a129bf205a14affcb4b319e2a668a24aed90801eadf02b3476499ac792e`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.4`