Metadata-Version: 2.4
Name: embed-client
Version: 3.1.9.2
Summary: Async client for the Embedding Service API. Canonical class: EmbeddingClient (JSON-RPC via mcp-proxy-adapter).
Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/vasilyvz/embed-client
Project-URL: Repository, https://github.com/vasilyvz/embed-client
Project-URL: Documentation, https://github.com/vasilyvz/embed-client#readme
Project-URL: Bug Tracker, https://github.com/vasilyvz/embed-client/issues
Project-URL: Configuration Reference, https://github.com/vasilyvz/embed-client/blob/main/CONFIGURATION.md
Keywords: embedding,async,client,api,authentication,ssl,tls,mtls,config,generator,validator,configuration
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp-proxy-adapter>=6.10.0
Provides-Extra: scripts
Requires-Dist: pydantic>=2.0.0; extra == "scripts"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: pytest-timeout; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# 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`**).

```python
from embed_client import EmbeddingClient
```

## Installation

```bash
pip install embed-client
```

Editable development checkout:

```bash
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`](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`](tests/test_canonical_mtls_example.py) |

```bash
python examples/canonical_mtls_localhost_8001.py
RUN_CANONICAL_MTLS_E2E=1 python examples/canonical_mtls_localhost_8001.py
```

## Minimal usage

```python
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](CONFIGURATION.md)** — JSON config schema, protocols, validation
- **[CLI_README.md](CLI_README.md)** — `embed-config-generator`, `embed-config-validator`, `embed-vectorize`
- **[docs/api_format.md](docs/api_format.md)** — JSON-RPC shapes for `embed` and `embed_file` (server path vs upload)
- **[examples/README.md](examples/README.md)** — example index (canonical mTLS first)
- **[docs/SERVER_MODES_AND_CLIENT.md](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.

```bash
pytest -q
```

## License

MIT License

## Author

**Vasiliy Zdanovskiy** — vasilyvz@gmail.com
