Skip to main content

embed-client

Python async client bundled with the Embedding Service in this repository's client/ directory. The canonical public client is EmbeddingClient (JSON-RPC via mcp-proxy-adapter). The distribution and import names are unchanged.

from embed_client import EmbeddingClient

Installation

pip install embed-client

Editable development checkout:

git clone https://github.com/maverikod/ai-embed.git
cd ai-embed
pip install -e ./client

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_PAYMENT_REQUIRED (error.data.payment_required true: the provider account needs payment or credit), 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.

Input-limit table (server input_limit_ commands):* input_limit_add(provider, model, max_input_tokens, tokenizer, max_inputs_per_request=None, max_total_tokens_per_request=None, source=None) adds a manual row (-32602 INPUT_LIMIT_EXISTS, LOCAL_LIMIT_FROM_MODEL); input_limit_delete(provider, model) removes a row (-32602 INPUT_LIMIT_NOT_FOUND); input_limit_update(provider, model, *, <named cells>) changes only the cells passed explicitly (None sends null, which only the three nullable cells accept; -32602 INPUT_LIMIT_NOT_FOUND, INPUT_LIMIT_EMPTY_UPDATE, LOCAL_LIMIT_FROM_MODEL); input_limit_list(provider=None) returns {rows: [...]} sorted by (provider, model) with each row's origin (module | manual). Mutating commands may also return -32603 INPUT_LIMIT_PERSIST_FAILED. Refusals arrive as EmbedAPIError. The client does not validate these parameters.

Documentation

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

The original client test modules are preserved under client/tests/; the shared project pipeline owns executable acceptance from the repository root.

python -m pipeline

Release

The server and client read one version from embed_client/_version.py here. The root ../build.sh builds the client wheel and sdist, checks their metadata, publishes only the client to PyPI and pushes the server image to Docker Hub on every successful run. It accepts no arguments or skip options and invokes no pipeline. Run the shared pipeline separately before releasing the candidate.

For isolated package artifacts without publishing, run python -m build client from the repository root. This is packaging only, not service acceptance.

License

MIT License

Author

Vasiliy Zdanovskiy — vasilyvz@gmail.com

Metadata

Release files for embed-client 4.0.90

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.90
File Size Uploaded Provenance Actions
embed_client-4.0.90.tar.gz 118.5 kB Without provenance Details for embed_client-4.0.90.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for embed-client 4.0.90
File Interpreter ABI Platform Actions
embed_client-4.0.90-py3-none-any.whl Python 3 none any Details for embed_client-4.0.90-py3-none-any.whl

Total release size: 242.8 kB

Release files / embed_client-4.0.90.tar.gz

Download URL embed_client-4.0.90.tar.gz
Size 118.5 kB
Tags Source
SHA-256 checksum
How to use checksums
7fdef6865b99658ae14088115c0a61c8085b822b9c1199d302fa3a11d670f953
BLAKE2b-256 checksum
How to use checksums
6e164a9372bdfde1a8aae932db620c378c1aeef28cb467918d71b09f9af65cd6
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.90-py3-none-any.whl

Download URL embed_client-4.0.90-py3-none-any.whl
Size 124.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
051e9217a3c3bb28bf6519f6598d45354b822fb97f5fbac57bd48ad8d617177d
BLAKE2b-256 checksum
How to use checksums
da6a81f8a2c1d3d841a5a8aeed2d7f5b8da37b28d96b17df8811b431ff438907
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.90

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.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

4.0.90 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page