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
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
License
MIT License
Author
Vasiliy Zdanovskiy — vasilyvz@gmail.com
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file embed_client-4.0.16.tar.gz.
File metadata
- Download URL: embed_client-4.0.16.tar.gz
- Upload date:
- Size: 359.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
76c4a00ce2edd7ed0a06d163d64db53ab40f045e61f5f2e01237176d88035d08
|
|
| MD5 |
23891062853f4d22a9a6cb355c8d29c9
|
|
| BLAKE2b-256 |
0034eaed4c4d408161507e5093920e4b062e005f5c0e586e85471faf1e148344
|
File details
Details for the file embed_client-4.0.16-py3-none-any.whl.
File metadata
- Download URL: embed_client-4.0.16-py3-none-any.whl
- Upload date:
- Size: 98.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8cda6b32ccc22e299941c402b2170efe6d862718427eb50ffdf0dac234070a3c
|
|
| MD5 |
10c3fc46e196dbe0e3f2504ab64c361f
|
|
| BLAKE2b-256 |
3b1e8f2b5bd93a75d01ce0cd1afc30690a00c309448704b5d55cdc8de48f16f5
|
