embed-client-dev 4.0.78__tar.gz

embed_client_dev-4.0.78/CONFIGURATION.md

@@ -0,0 +1,358 @@
+# Embed-Client Configuration Reference
+
+Complete reference for embed-client configuration structure. **`ClientConfig`** loads and merges JSON; **`ConfigValidator`** enforces field rules; **`ClientConfigGenerator`** (CLI **`embed-config-generator`**) emits JSON for all deploy modes. See **[CLI_README.md](CLI_README.md)** for generator and validator commands.
+
+Author: Vasiliy Zdanovskiy  
+email: vasilyvz@gmail.com
+
+## Recommended local integration (mTLS, port 8001)
+
+For a **localhost:8001** embedding service with **mutual TLS**, use the same certificate layout as the repository test bundle:
+
+- **Client certificate / key:** `mtls_certificates/client/embedding-service.crt`, `mtls_certificates/client/embedding-service.key`
+- **CA certificate:** `mtls_certificates/ca/ca.crt`
+
+A validated configuration dict matching this layout is built by **`build_mtls_localhost_8001_config()`** in [`examples/canonical_mtls_localhost_8001.py`](examples/canonical_mtls_localhost_8001.py). Typical fields:
+
+- **`protocol`:** `"mtls"`
+- **`server`:** `host` **`localhost`**, **`port`** **`8001`**
+- **`auth.method`:** **`certificate`** with **`auth.certificate`** paths mirroring **`ssl`** certificate paths
+- **`ssl.enabled`:** **`true`**, **`verify_mode`:** **`CERT_REQUIRED`** (or as required by your environment), **`cert_file`**, **`key_file`**, **`ca_cert_file`** under **`mtls_certificates/client/`** and **`mtls_certificates/ca/`**
+
+Pass the dict to **`EmbeddingClient.from_config_dict(...)`** or write it to a JSON file and use **`EmbeddingClient.from_config_file(...)`**.
+
+## Configuration Structure
+
+All embed-client configurations follow a unified structure with all fields present. Fields that are not applicable for a specific security mode are set to `null`.
+
+### Complete Configuration Schema
+
+```json
+{
+  "server": {
+    "host": "string (required, default: 'localhost')",
+    "port": "integer (required, default: 8001)",
+    "base_url": "string (optional, auto-generated)"
+  },
+  "client": {
+    "timeout": "float (optional, default: 30.0)"
+  },
+  "protocol": "string (required, one of: 'http', 'https', 'mtls')",
+  "auth": {
+    "method": "string (required, one of: 'none', 'api_key', 'jwt', 'certificate', 'basic')",
+    "api_key": {
+      "key": "string (optional, can be null)",
+      "header": "string (optional, default: 'X-API-Key')"
+    },
+    "jwt": {
+      "username": "string (optional, required for jwt method)",
+      "password": "string (optional, required for jwt method)",
+      "secret": "string (optional, required for jwt method)",
+      "expiry_hours": "integer (optional, default: 24)"
+    },
+    "certificate": {
+      "enabled": "boolean (required, true for mtls, false otherwise)",
+      "cert_file": "string (optional, required for mtls, null for http)",
+      "key_file": "string (optional, required for mtls, null for http)",
+      "ca_cert_file": "string (optional, required for mtls, null for http)"
+    },
+    "basic": {
+      "username": "string (optional, required for basic method)",
+      "password": "string (optional, required for basic method)"
+    }
+  },
+  "ssl": {
+    "enabled": "boolean (required, true for https/mtls, false for http)",
+    "verify": "boolean (optional, default: true for https/mtls, false for http)",
+    "verify_mode": "string (optional, 'CERT_REQUIRED' for mtls, 'CERT_NONE' for https)",
+    "check_hostname": "boolean (optional, default: false)",
+    "check_expiry": "boolean (optional, default: false)",
+    "cert_file": "string (optional, required for mtls, optional for https, null for http)",
+    "key_file": "string (optional, required for mtls, optional for https, null for http)",
+    "ca_cert_file": "string (optional, required for mtls, optional for https, null for http)",
+    "crl_file": "string (optional, can be null for all protocols)",
+    "client_cert_required": "boolean (optional, true for mtls, false otherwise)"
+  },
+  "security": {
+    "enabled": "boolean (optional, default: false)",
+    "roles_enabled": "boolean (optional, default: false)",
+    "roles_file": "string (optional, can be null)",
+    "tokens": "object (optional, dictionary of tokens for token-based auth)",
+    "roles": "object (optional, dictionary of roles and permissions)"
+  },
+  "logging": {
+    "enabled": "boolean (optional, default: false)",
+    "level": "string (optional, default: 'INFO')",
+    "format": "string (optional, default log format)"
+  },
+  "timeout": "integer (optional, default: 30)",
+  "retry_attempts": "integer (optional, default: 3)",
+  "retry_delay": "integer (optional, default: 1)"
+}
+```
+
+## Field Requirements by Protocol
+
+### HTTP Protocol
+
+- **protocol**: `"http"` (required)
+- **server.host**: Required (default: `"localhost"`)
+- **server.port**: Required (default: `8001`)
+- **auth.method**: `"none"` or `"api_key"` or `"jwt"` or `"basic"`
+- **auth.api_key.key**: Optional (can be `null`)
+- **auth.certificate.cert_file**: Must be `null` (not used)
+- **auth.certificate.key_file**: Must be `null` (not used)
+- **auth.certificate.ca_cert_file**: Must be `null` (not used)
+- **ssl.enabled**: `false` (required)
+- **ssl.cert_file**: Must be `null` (not used)
+- **ssl.key_file**: Must be `null` (not used)
+- **ssl.ca_cert_file**: Must be `null` (not used)
+- **ssl.crl_file**: Optional (can be `null`)
+
+### HTTPS Protocol
+
+- **protocol**: `"https"` (required)
+- **server.host**: Required (default: `"localhost"`)
+- **server.port**: Required (default: `8001`)
+- **auth.method**: `"none"` or `"api_key"` or `"jwt"` or `"basic"`
+- **auth.api_key.key**: Optional (can be `null`)
+- **auth.certificate.cert_file**: Optional (can be `null`)
+- **auth.certificate.key_file**: Optional (can be `null`)
+- **auth.certificate.ca_cert_file**: Optional (can be `null`)
+- **ssl.enabled**: `true` (required)
+- **ssl.cert_file**: Optional (can be `null`)
+- **ssl.key_file**: Optional (can be `null`)
+- **ssl.ca_cert_file**: Optional (can be `null`)
+- **ssl.crl_file**: Optional (can be `null`)
+
+### mTLS Protocol
+
+- **protocol**: `"mtls"` (required)
+- **server.host**: Required (default: `"localhost"`)
+- **server.port**: Required (default: `8001`)
+- **auth.method**: `"certificate"` (required)
+- **auth.api_key.key**: Optional (can be `null`, not used for mTLS auth)
+- **auth.certificate.cert_file**: **Required** (must be provided)
+- **auth.certificate.key_file**: **Required** (must be provided)
+- **auth.certificate.ca_cert_file**: **Required** (must be provided)
+- **ssl.enabled**: `true` (required)
+- **ssl.cert_file**: **Required** (must be provided)
+- **ssl.key_file**: **Required** (must be provided)
+- **ssl.ca_cert_file**: **Required** (must be provided)
+- **ssl.crl_file**: Optional (can be `null`)
+- **ssl.client_cert_required**: `true` (required)
+
+## Configuration Examples
+
+### HTTP Configuration
+
+```json
+{
+  "server": {
+    "host": "localhost",
+    "port": 8001
+  },
+  "protocol": "http",
+  "auth": {
+    "method": "none",
+    "api_key": {
+      "key": null
+    },
+    "certificate": {
+      "enabled": false,
+      "cert_file": null,
+      "key_file": null,
+      "ca_cert_file": null
+    }
+  },
+  "ssl": {
+    "enabled": false,
+    "cert_file": null,
+    "key_file": null,
+    "ca_cert_file": null,
+    "crl_file": null
+  }
+}
+```
+
+### HTTPS with Token Configuration
+
+```json
+{
+  "server": {
+    "host": "localhost",
+    "port": 8443
+  },
+  "protocol": "https",
+  "auth": {
+    "method": "api_key",
+    "api_key": {
+      "key": "your-api-key-here"
+    },
+    "certificate": {
+      "enabled": false,
+      "cert_file": null,
+      "key_file": null,
+      "ca_cert_file": null
+    }
+  },
+  "ssl": {
+    "enabled": true,
+    "verify_mode": "CERT_NONE",
+    "cert_file": "/path/to/cert.crt",
+    "key_file": null,
+    "ca_cert_file": "/path/to/ca.crt",
+    "crl_file": null
+  }
+}
+```
+
+### mTLS Configuration
+
+```json
+{
+  "server": {
+    "host": "localhost",
+    "port": 8443
+  },
+  "protocol": "mtls",
+  "auth": {
+    "method": "certificate",
+    "api_key": {
+      "key": null
+    },
+    "certificate": {
+      "enabled": true,
+      "cert_file": "/path/to/client.crt",
+      "key_file": "/path/to/client.key",
+      "ca_cert_file": "/path/to/ca.crt"
+    }
+  },
+  "ssl": {
+    "enabled": true,
+    "verify_mode": "CERT_REQUIRED",
+    "cert_file": "/path/to/client.crt",
+    "key_file": "/path/to/client.key",
+    "ca_cert_file": "/path/to/ca.crt",
+    "crl_file": "/path/to/crl.pem",
+    "client_cert_required": true
+  }
+}
+```
+
+## Environment variables
+
+- **`EMBED_CLIENT_MAX_JSON_BLOCK_BYTES`** — Optional positive integer: maximum UTF-8 byte length of each string item when validating a local JSON file before **`embed_file`** (`json_array`). If unset, the default is 1 MiB (see **`embed_client.constants.DEFAULT_MAX_JSON_EMBED_BLOCK_BYTES`**). For Markdown/plain text produced by **`prepare-embed-file-json`**, each string is one **paragraph block** after splitting the body **only** on **`\n\n`** (no automatic re-split of oversized paragraphs). Validation runs locally on the client; uploading the validated file uses the same adapter HTTP transport and authentication as JSON-RPC requests to the service. For the CLI entry points, see **`CLI_README.md`** (**`embed-file-json`**, **`prepare-embed-file-json`**) and **`docs/SERVER_MODES_AND_CLIENT.md`** (local upload vs server path).
+
+## Default Values
+
+When creating a configuration, the following default values are used if not specified:
+
+- **server.host**: `"localhost"`
+- **server.port**: `8001`
+- **client.timeout**: `30.0`
+- **protocol**: Determined by SSL settings (`"http"`, `"https"`, or `"mtls"`)
+- **auth.method**: `"none"`
+- **auth.api_key.key**: `null`
+- **auth.certificate.enabled**: `false` (except for mTLS where it's `true`)
+- **ssl.enabled**: `false` (except for HTTPS/mTLS where it's `true`)
+- **ssl.crl_file**: `null` (optional for all protocols)
+
+## Field Semantics
+
+### Protocol Field
+
+The `protocol` field is **always present** in all configurations and indicates the transport protocol:
+- `"http"`: Plain HTTP without encryption
+- `"https"`: HTTPS with server certificate verification
+- `"mtls"`: Mutual TLS with client and server certificates
+
+### Token Field
+
+The `auth.api_key.key` field is **always present** but can be `null`:
+- For HTTP/HTTPS with token authentication: contains the API key
+- For HTTP/HTTPS without authentication: `null`
+- For mTLS: `null` (certificate-based authentication is used)
+
+### Certificate Fields
+
+Certificate fields behavior:
+- **For HTTP**: All certificate fields (`cert_file`, `key_file`, `ca_cert_file`) must be `null`
+- **For HTTPS**: Certificate fields are optional (can be `null` or provided)
+- **For mTLS**: Certificate fields are **required** and must be provided
+
+### CRL Field
+
+The `ssl.crl_file` field is **always present** but optional:
+- Can be `null` for all protocols
+- If provided, must point to a valid Certificate Revocation List file
+- Used for checking if certificates have been revoked
+
+## Configuration Generator
+
+Use `embed-config-generator` CLI tool to generate configurations:
+
+```bash
+# Generate HTTP config
+embed-config-generator --mode http --host localhost --port 8001 --output config.json
+
+# Generate HTTPS config with certificates
+embed-config-generator --mode https --host localhost --port 8443 \
+  --cert-file /path/to/cert.crt --ca-cert-file /path/to/ca.crt --output config.json
+
+# Generate mTLS config with all certificates and CRL
+embed-config-generator --mode mtls --host localhost --port 8443 \
+  --cert-file /path/to/client.crt --key-file /path/to/client.key \
+  --ca-cert-file /path/to/ca.crt --crl-file /path/to/crl.pem --output config.json
+```
+
+## Configuration Validator
+
+Use `embed-config-validator` CLI tool to validate configurations:
+
+```bash
+# Validate single config
+embed-config-validator --file config.json
+
+# Validate all configs in directory
+embed-config-validator --dir ./configs --verbose
+```
+
+## Integration with Server
+
+When embedding the client into a server, create a separate configuration section:
+
+```json
+{
+  "server": {
+    "host": "localhost",
+    "port": 8001
+  },
+  "embed_client": {
+    "protocol": "mtls",
+    "server": {
+      "host": "embedding-service.example.com",
+      "port": 8443
+    },
+    "auth": {
+      "method": "certificate",
+      "certificate": {
+        "enabled": true,
+        "cert_file": "/path/to/client.crt",
+        "key_file": "/path/to/client.key",
+        "ca_cert_file": "/path/to/ca.crt"
+      }
+    },
+    "ssl": {
+      "enabled": true,
+      "cert_file": "/path/to/client.crt",
+      "key_file": "/path/to/client.key",
+      "ca_cert_file": "/path/to/ca.crt",
+      "crl_file": "/path/to/crl.pem"
+    }
+  }
+}
+```
+
+This allows the server to have its own configuration while the client has a separate, validated configuration section.
+

embed_client_dev-4.0.78/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Vasiliy Zdanovskiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

embed_client_dev-4.0.78/MANIFEST.in

@@ -0,0 +1,16 @@
+include README.md
+include LICENSE
+include CONFIGURATION.md
+include pyproject.toml
+recursive-include examples *.py *.md *.json
+recursive-include docs *.md
+recursive-include configs *.json
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .pytest_cache
+recursive-exclude * .git*
+recursive-exclude * .venv
+recursive-exclude * tests
+recursive-exclude * mtls_certificates
+recursive-exclude * logs
+recursive-exclude * test_environment

embed_client_dev-4.0.78/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: embed-client-dev
+Version: 4.0.78
+Summary: Async client for the Embedding Service API. Canonical class: EmbeddingClient (JSON-RPC via mcp-proxy-adapter >=8.10).
+Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/maverikod/ai-embed
+Project-URL: Repository, https://github.com/maverikod/ai-embed
+Project-URL: Documentation, https://github.com/maverikod/ai-embed/tree/main/client#readme
+Project-URL: Bug Tracker, https://github.com/maverikod/ai-embed/issues
+Project-URL: Configuration Reference, https://github.com/maverikod/ai-embed/blob/main/client/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>=8.11.14
+Requires-Dist: mcp_security_framework>=2.3.2
+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 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.
+
+```python
+from embed_client import EmbeddingClient
+```
+
+## Installation
+
+```bash
+pip install embed-client
+```
+
+Editable development checkout:
+
+```bash
+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`](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`**, **`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`.
+
+**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](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
+
+The original client test modules are preserved under `client/tests/`; the shared
+project pipeline owns executable acceptance from the repository root.
+
+```bash
+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

embed_client_dev-4.0.78/README.md

@@ -0,0 +1,108 @@
+# 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.
+
+```python
+from embed_client import EmbeddingClient
+```
+
+## Installation
+
+```bash
+pip install embed-client
+```
+
+Editable development checkout:
+
+```bash
+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`](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`**, **`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`.
+
+**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](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
+
+The original client test modules are preserved under `client/tests/`; the shared
+project pipeline owns executable acceptance from the repository root.
+
+```bash
+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