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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

embed_client-4.0.15.tar.gz (359.1 kB view details)

Uploaded Aug 13, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

embed_client-4.0.15-py3-none-any.whl (98.9 kB view details)

Uploaded Aug 13, 2026 Python 3

File details

Details for the file embed_client-4.0.15.tar.gz.

File metadata

Download URL: embed_client-4.0.15.tar.gz
Upload date: Aug 13, 2026
Size: 359.1 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.4

File hashes

Hashes for embed_client-4.0.15.tar.gz
Algorithm	Hash digest
SHA256	`5c98e0d0f34b8b4971fa41f5f9269251f6266a2b3137091b463bf178dc160a85`
MD5	`cdb8f287601892ed22b3ed1c419c2bdd`
BLAKE2b-256	`2da7e5daf86566e92fb2b960c7922f41ae751673df2c2cc13458f63c8c7c7463`

See more details on using hashes here.

File details

Details for the file embed_client-4.0.15-py3-none-any.whl.

File metadata

Download URL: embed_client-4.0.15-py3-none-any.whl
Upload date: Aug 13, 2026
Size: 98.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.4

File hashes

Hashes for embed_client-4.0.15-py3-none-any.whl
Algorithm	Hash digest
SHA256	`d620032e7e653a2855df31578d69b2b725d2c7970d6eb412f07915d3f5ba4d45`
MD5	`198fc2a63f88b17628db03fa41e6be9c`
BLAKE2b-256	`22bbb4b3650ec9833989e5a729ca0b0c005e82378c378fc545576076e5492293`