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, default_model, 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).
Providers (server 4.0.46+): the full model id is provider + model. embed and embed_file take an optional provider ("local" = the server's own model, or a live macsc provider id such as "openai"); it is sent only when not None. There is no backend argument any more (a TypeError is raised for backend=); the backend field of results and models() entries is still returned. default_model() returns exactly {model, dimension, provider}; models() returns {use_own_model, default: {provider, model}, external: {configured, service}, models: [...]} with entries {name, provider, dimension, supported_dimensions, max_tokens, backend, residency (local)}.
Resolution order (server): provider given -> must be known, model omitted -> the default model of that provider (it must be the default provider's, else UNKNOWN_MODEL); provider and model omitted -> the default pair; provider omitted and model given -> the default provider first (if it lists the model it is used and macsc is not consulted for a local default), else the other providers are searched: exactly one offers it -> used, several -> PROVIDER_REQUIRED, none -> UNKNOWN_MODEL. Dimension omitted -> the entry's default; given -> must satisfy supported_dimensions else UNSUPPORTED_DIMENSION.
Error codes (error.data.code / error.data.kind, surfaced 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. model_offload() moves the resident local model VRAM -> RAM (pinned against the GPU watcher) and model_load(model=None, device=None, wait=None) moves it back (wait=False returns at once while the load continues, wait=True blocks until it is in VRAM); neither takes a provider. Refusals of model_offload/model_load/default_model arrive as EmbedAPIError carrying the server error object. Every embed result carries provider, model, dimension and backend; external results also carry usage.
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
embedandembed_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
Release
The client is released together with the server (embed) as one unit and always carries the same
version. Releases are run only by the server script docker/build.sh in the embed repository,
which computes the next version, writes it into both trees, and calls this repository's scripts:
build.sh <release-version>- client tests, sdist/wheel,twine check; never uploadspublish.sh <release-version>-twine uploadof the built files, run only after the Docker Hub push succeeded
Both scripts have no options and no skip switches, accept exactly one argument, and refuse a
version that differs from pyproject.toml / embed_client/__init__.py (exit code 3).
License
MIT License
Author
Vasiliy Zdanovskiy — vasilyvz@gmail.com
1 maintainer
Metadata
1 maintainer
Release files for embed-client 4.0.50
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| embed_client-4.0.50.tar.gz | 246.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| embed_client-4.0.50-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 350.8 kB
Release files / embed_client-4.0.50.tar.gz
| Download URL | embed_client-4.0.50.tar.gz |
|---|---|
| Size | 246.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c499193ac73b8f08a8c0b9b8f73b5379093f771ded664042b4753b6c4db2ad82
|
|
BLAKE2b-256 checksum How to use checksums |
aaeb03af435fe216883207b9dd1f6aa44a4f94c17c14b23c199f2a98ed32f421
|
| Upload date | |
|
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.50-py3-none-any.whl
| Download URL | embed_client-4.0.50-py3-none-any.whl |
|---|---|
| Size | 103.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6e437e06591da5d6d484ac730d1b4759d6081df995206c0a78d9e865bfc412bb
|
|
BLAKE2b-256 checksum How to use checksums |
ab3b2395d66ac7fb59c84b1f7536cfa404ef6fe3dde59f63feadc0a268bd614f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for embed-client 4.0.50
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
