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
- 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
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.95
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 | Actions |
|---|---|---|---|---|
| embed_client-4.0.95.tar.gz | 118.6 kB | Without provenance | Details for embed_client-4.0.95.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| embed_client-4.0.95-py3-none-any.whl | Python 3 | none | any | Details for embed_client-4.0.95-py3-none-any.whl |
Total release size: 242.9 kB
Release files / embed_client-4.0.95.tar.gz
| Download URL | embed_client-4.0.95.tar.gz |
|---|---|
| Size | 118.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cfa7c7e0a706bd00ea329fd10643dc987470120059aef11914b46acf3a965f9c
|
|
BLAKE2b-256 checksum How to use checksums |
659d423cd8c475675b2aa6c7d441e8633c6bf05dfd43d47e42dccf7d3178e0ee
|
| 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.95-py3-none-any.whl
| Download URL | embed_client-4.0.95-py3-none-any.whl |
|---|---|
| Size | 124.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d46c92629fa0cac04d88c0a012683627c6a73a2b228ac0705e0b7e91a2ac6363
|
|
BLAKE2b-256 checksum How to use checksums |
756b4c795327451a0771eb87e63621ee0148e72136e358d25dfb518841a9c896
|
| 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.95
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.