embed-client 4.0.78__tar.gz → 4.0.87__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. {embed_client-4.0.78/embed_client.egg-info → embed_client-4.0.87}/PKG-INFO +4 -13
  2. {embed_client-4.0.78 → embed_client-4.0.87}/README.md +1 -1
  3. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/_version.py +1 -1
  4. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/cli.py +14 -4
  5. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/cli_core.py +1 -1
  6. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/embedding_client.py +6 -2
  7. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/exceptions.py +1 -1
  8. {embed_client-4.0.78 → embed_client-4.0.87/embed_client.egg-info}/PKG-INFO +4 -13
  9. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client.egg-info/SOURCES.txt +1 -36
  10. embed_client-4.0.87/embed_client.egg-info/requires.txt +10 -0
  11. {embed_client-4.0.78 → embed_client-4.0.87}/examples/README.md +10 -2
  12. {embed_client-4.0.78 → embed_client-4.0.87}/examples/async_testing_client_example.py +12 -5
  13. {embed_client-4.0.78 → embed_client-4.0.87}/examples/canonical_mtls_localhost_8001.py +5 -2
  14. {embed_client-4.0.78 → embed_client-4.0.87}/examples/configs/http_simple.json +1 -5
  15. {embed_client-4.0.78 → embed_client-4.0.87}/examples/configs/https_token.json +1 -5
  16. {embed_client-4.0.78 → embed_client-4.0.87}/examples/configs/mtls_roles.json +1 -5
  17. {embed_client-4.0.78 → embed_client-4.0.87}/examples/embed_file_json_local.py +12 -0
  18. {embed_client-4.0.78 → embed_client-4.0.87}/examples/security_examples.py +65 -40
  19. {embed_client-4.0.78 → embed_client-4.0.87}/examples/security_examples_ru.py +65 -40
  20. {embed_client-4.0.78 → embed_client-4.0.87}/pyproject.toml +3 -24
  21. embed_client-4.0.78/embed_client.egg-info/requires.txt +0 -20
  22. embed_client-4.0.78/tests/test_adapter_integration.py +0 -73
  23. embed_client-4.0.78/tests/test_adapter_phase1.py +0 -166
  24. embed_client-4.0.78/tests/test_adapter_phase2.py +0 -263
  25. embed_client-4.0.78/tests/test_all_security_modes.py +0 -627
  26. embed_client-4.0.78/tests/test_async_client_adapter.py +0 -84
  27. embed_client-4.0.78/tests/test_async_client_real.py +0 -311
  28. embed_client-4.0.78/tests/test_async_client_real_fixtures.py +0 -123
  29. embed_client-4.0.78/tests/test_async_client_stress.py +0 -346
  30. embed_client-4.0.78/tests/test_async_client_stress_new.py +0 -326
  31. embed_client-4.0.78/tests/test_async_client_stress_updated.py +0 -326
  32. embed_client-4.0.78/tests/test_auth_manager.py +0 -187
  33. embed_client-4.0.78/tests/test_canonical_mtls_example.py +0 -145
  34. embed_client-4.0.78/tests/test_cli_embed_file_json.py +0 -66
  35. embed_client-4.0.78/tests/test_cli_exit_codes_insecure.py +0 -295
  36. embed_client-4.0.78/tests/test_client_factory.py +0 -461
  37. embed_client-4.0.78/tests/test_client_factory_convenience.py +0 -65
  38. embed_client-4.0.78/tests/test_client_factory_integration.py +0 -115
  39. embed_client-4.0.78/tests/test_config.py +0 -384
  40. embed_client-4.0.78/tests/test_config_explicit_host_not_overridden.py +0 -34
  41. embed_client-4.0.78/tests/test_embed_file_aggregation_method.py +0 -62
  42. embed_client-4.0.78/tests/test_embed_file_output_validate.py +0 -147
  43. embed_client-4.0.78/tests/test_embed_immediate_mode.py +0 -125
  44. embed_client-4.0.78/tests/test_example_async_usage.py +0 -100
  45. embed_client-4.0.78/tests/test_input_limit_commands_client.py +0 -232
  46. embed_client-4.0.78/tests/test_json_embed_file_preflight.py +0 -63
  47. embed_client-4.0.78/tests/test_local_json_embed_file.py +0 -100
  48. embed_client-4.0.78/tests/test_md_embed_file_prep.py +0 -78
  49. embed_client-4.0.78/tests/test_security_matrix.py +0 -421
  50. embed_client-4.0.78/tests/test_ssl_manager.py +0 -58
  51. embed_client-4.0.78/tests/test_structured_terminal_error.py +0 -477
  52. embed_client-4.0.78/tests/test_terminal_delivery_events.py +0 -130
  53. embed_client-4.0.78/tests/test_vectorization_modes_client.py +0 -245
  54. embed_client-4.0.78/tests/test_wait_for_job_poll_queue_shape.py +0 -122
  55. embed_client-4.0.78/tests/test_wait_for_job_ws_fallback.py +0 -113
  56. embed_client-4.0.78/tests/test_with_auth.py +0 -260
  57. {embed_client-4.0.78 → embed_client-4.0.87}/CONFIGURATION.md +0 -0
  58. {embed_client-4.0.78 → embed_client-4.0.87}/LICENSE +0 -0
  59. {embed_client-4.0.78 → embed_client-4.0.87}/MANIFEST.in +0 -0
  60. {embed_client-4.0.78 → embed_client-4.0.87}/docs/SERVER_MODES_AND_CLIENT.md +0 -0
  61. {embed_client-4.0.78 → embed_client-4.0.87}/docs/api_format.md +0 -0
  62. {embed_client-4.0.78 → embed_client-4.0.87}/docs/client_integration_guide.md +0 -0
  63. {embed_client-4.0.78 → embed_client-4.0.87}/docs/error_handling_complete.md +0 -0
  64. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/__init__.py +0 -0
  65. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/__main__.py +0 -0
  66. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/adapter_config_factory.py +0 -0
  67. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/adapter_config_normalizer.py +0 -0
  68. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/adapter_generator_bridge.py +0 -0
  69. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/auth.py +0 -0
  70. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/client_factory.py +0 -0
  71. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/client_factory_examples.py +0 -0
  72. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/client_factory_helpers.py +0 -0
  73. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/config.py +0 -0
  74. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/config_defaults.py +0 -0
  75. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/config_examples.py +0 -0
  76. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/config_generator.py +0 -0
  77. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/config_generator_cli.py +0 -0
  78. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/config_presets.py +0 -0
  79. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/config_validator.py +0 -0
  80. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/config_validator_cli.py +0 -0
  81. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/constants.py +0 -0
  82. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/demo_cli.py +0 -0
  83. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/demo_security_cli.py +0 -0
  84. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/embed_file_output_validate.py +0 -0
  85. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/embed_file_status_store.py +0 -0
  86. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/embedding_client_helpers.py +0 -0
  87. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/example_async_usage.py +0 -0
  88. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/example_async_usage_demo.py +0 -0
  89. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/example_async_usage_ru.py +0 -0
  90. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/example_async_usage_ru_demo.py +0 -0
  91. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/identifier_types.py +0 -0
  92. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/json_embed_file_preflight.py +0 -0
  93. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/local_json_embed_file.py +0 -0
  94. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/md_embed_file_prep.py +0 -0
  95. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/response_normalizer.py +0 -0
  96. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/response_parsers.py +0 -0
  97. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/security_cli.py +0 -0
  98. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/security_cli_core.py +0 -0
  99. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/ssl_examples.py +0 -0
  100. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client/ssl_manager.py +0 -0
  101. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client.egg-info/dependency_links.txt +0 -0
  102. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client.egg-info/entry_points.txt +0 -0
  103. {embed_client-4.0.78 → embed_client-4.0.87}/embed_client.egg-info/top_level.txt +0 -0
  104. {embed_client-4.0.78 → embed_client-4.0.87}/examples/__init__.py +0 -0
  105. {embed_client-4.0.78 → embed_client-4.0.87}/examples/data/embed_file_json_array_sample.json +0 -0
  106. {embed_client-4.0.78 → embed_client-4.0.87}/setup.cfg +0 -0
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: embed-client
3
- Version: 4.0.78
4
- Summary: Async client for the Embedding Service API. Canonical class: EmbeddingClient (JSON-RPC via mcp-proxy-adapter >=8.10).
3
+ Version: 4.0.87
4
+ Summary: Async client for the Embedding Service API. Canonical class: EmbeddingClient (JSON-RPC via mcp-proxy-adapter >=8.11.16).
5
5
  Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
6
6
  License-Expression: MIT
7
7
  Project-URL: Homepage, https://github.com/maverikod/ai-embed
@@ -26,20 +26,11 @@ Classifier: Topic :: System :: Networking
26
26
  Requires-Python: >=3.8
27
27
  Description-Content-Type: text/markdown
28
28
  License-File: LICENSE
29
- Requires-Dist: mcp-proxy-adapter>=8.11.14
29
+ Requires-Dist: mcp-proxy-adapter>=8.11.16
30
30
  Requires-Dist: mcp_security_framework>=2.3.2
31
31
  Provides-Extra: scripts
32
32
  Requires-Dist: pydantic>=2.0.0; extra == "scripts"
33
- Provides-Extra: test
34
- Requires-Dist: pytest; extra == "test"
35
- Requires-Dist: pytest-asyncio; extra == "test"
36
- Requires-Dist: pytest-xdist; extra == "test"
37
- Requires-Dist: pytest-timeout; extra == "test"
38
33
  Provides-Extra: dev
39
- Requires-Dist: pytest; extra == "dev"
40
- Requires-Dist: pytest-asyncio; extra == "dev"
41
- Requires-Dist: pytest-xdist; extra == "dev"
42
- Requires-Dist: pytest-timeout; extra == "dev"
43
34
  Requires-Dist: black; extra == "dev"
44
35
  Requires-Dist: flake8; extra == "dev"
45
36
  Requires-Dist: mypy; extra == "dev"
@@ -110,7 +101,7 @@ Public queue-oriented helpers include **`embed`**, **`wait_for_job`**, **`job_st
110
101
 
111
102
  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`.
112
103
 
113
- 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`.
104
+ 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`.
114
105
 
115
106
  **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.
116
107
 
@@ -63,7 +63,7 @@ Public queue-oriented helpers include **`embed`**, **`wait_for_job`**, **`job_st
63
63
 
64
64
  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`.
65
65
 
66
- 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`.
66
+ 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`.
67
67
 
68
68
  **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.
69
69
 
@@ -1,3 +1,3 @@
1
1
  """Authoritative release version for the bundled server and client."""
2
2
 
3
- __version__ = "4.0.78"
3
+ __version__ = "4.0.87"
@@ -16,6 +16,7 @@ email: vasilyvz@gmail.com
16
16
 
17
17
  import argparse
18
18
  import asyncio
19
+ import re
19
20
  import sys
20
21
  from typing import Any, Dict # noqa: F401
21
22
 
@@ -24,6 +25,15 @@ from embed_client.cli_core import VectorizationCLI, create_config_from_args
24
25
  from embed_client.constants import DEFAULT_POLL_INTERVAL
25
26
 
26
27
 
28
+ def _device_arg(value: str) -> str:
29
+ """argparse type of --device: auto, cpu, cuda or cuda:N (N a device index)."""
30
+ if re.fullmatch(r"auto|cpu|cuda|cuda:[0-9]+", value) is None:
31
+ raise argparse.ArgumentTypeError(
32
+ f"invalid device {value!r}: expected auto, cpu, cuda or cuda:N"
33
+ )
34
+ return value
35
+
36
+
27
37
  async def main():
28
38
  """Main CLI function."""
29
39
  parser = argparse.ArgumentParser(
@@ -161,8 +171,8 @@ Examples:
161
171
  )
162
172
  vectorize_parser.add_argument(
163
173
  "--device",
164
- choices=["auto", "cpu", "cuda", "cuda:0"],
165
- help="Device for embedding (server-side: auto, cpu, cuda, cuda:0)",
174
+ type=_device_arg,
175
+ help="Device for embedding (server-side: auto, cpu, cuda, cuda:N)",
166
176
  )
167
177
  vectorize_parser.add_argument(
168
178
  "--wait-timeout",
@@ -222,8 +232,8 @@ Examples:
222
232
  )
223
233
  embed_file_json.add_argument(
224
234
  "--device",
225
- choices=["auto", "cpu", "cuda", "cuda:0"],
226
- help="Device for embedding (server-side)",
235
+ type=_device_arg,
236
+ help="Device for embedding (server-side: auto, cpu, cuda, cuda:N)",
227
237
  )
228
238
  embed_file_json.add_argument(
229
239
  "--error-policy",
@@ -220,7 +220,7 @@ class VectorizationCLI:
220
220
  model: Optional model name (server-side).
221
221
  dimension: Optional expected vector dimension (server-side).
222
222
  error_policy: "continue" or "fail_fast" (default: "continue").
223
- device: Optional device: "auto", "cpu", "cuda", "cuda:0" (server-side).
223
+ device: Optional device: "auto", "cpu", "cuda", "cuda:N" (server-side).
224
224
 
225
225
  Returns:
226
226
  A list of embedding vectors on success (possibly empty when
@@ -686,7 +686,7 @@ class EmbeddingClient:
686
686
  dimension: Optional expected vector dimension
687
687
  job_id: Optional custom job ID (server may ignore and generate own)
688
688
  error_policy: 'fail_fast' or 'continue'; default from server
689
- device: 'auto', 'cpu', 'cuda', 'cuda:0'; default from server
689
+ device: 'auto', 'cpu', 'cuda' or 'cuda:N'; default from server
690
690
  aggregation_method: How to combine part vectors when a text is
691
691
  longer than the model can read. For the local model, when
692
692
  neither the call nor the server config sets it, the default is
@@ -722,6 +722,8 @@ class EmbeddingClient:
722
722
  and ``error.data.kind`` unchanged: -32602 UNKNOWN_PROVIDER,
723
723
  UNKNOWN_MODEL, UNSUPPORTED_DIMENSION, PROVIDER_REQUIRED;
724
724
  -32003 EXTERNAL_UNAVAILABLE, EXTERNAL_UPSTREAM_FAILURE,
725
+ EXTERNAL_PAYMENT_REQUIRED (error.data.payment_required true: the
726
+ provider account needs payment or credit; top up and repeat),
725
727
  EXTERNAL_BAD_RESPONSE, EXTERNAL_INVALID_REQUEST; -32001
726
728
  MODEL_LOADING (retry); -32004 OWN_MODEL_DISABLED; -32005
727
729
  GPU_DISABLED; -32603 MODEL_LOAD_FAILED, NO_GPU_AVAILABLE,
@@ -1464,7 +1466,9 @@ class EmbeddingClient:
1464
1466
  List available models (shape matches server models command result.data).
1465
1467
 
1466
1468
  Returns:
1467
- ``{"use_own_model": "none"|"ram"|"gpu", "default": {provider,
1469
+ ``{"use_own_model": "none"|"ram"|"gpu" (the effective mode derived
1470
+ from the server flags use_own_model false / true + device cpu /
1471
+ true + device gpu), "default": {provider,
1468
1472
  model}, "external": {configured, service}, "models": [...]}``; each
1469
1473
  entry has name, provider, dimension, supported_dimensions,
1470
1474
  max_tokens, backend and (local entries) residency. For the local
@@ -68,7 +68,7 @@ class ModelServerUnavailableError(EmbedError):
68
68
  class EmbedGpuOutOfMemoryError(EmbedError):
69
69
  """
70
70
  GPU ran out of memory while loading or running the embedding model.
71
- User message suggests using CPU (embedding.device=cpu) or freeing GPU memory.
71
+ User message suggests using CPU (vectorization.device=cpu) or freeing GPU memory.
72
72
  """
73
73
 
74
74
 
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: embed-client
3
- Version: 4.0.78
4
- Summary: Async client for the Embedding Service API. Canonical class: EmbeddingClient (JSON-RPC via mcp-proxy-adapter >=8.10).
3
+ Version: 4.0.87
4
+ Summary: Async client for the Embedding Service API. Canonical class: EmbeddingClient (JSON-RPC via mcp-proxy-adapter >=8.11.16).
5
5
  Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
6
6
  License-Expression: MIT
7
7
  Project-URL: Homepage, https://github.com/maverikod/ai-embed
@@ -26,20 +26,11 @@ Classifier: Topic :: System :: Networking
26
26
  Requires-Python: >=3.8
27
27
  Description-Content-Type: text/markdown
28
28
  License-File: LICENSE
29
- Requires-Dist: mcp-proxy-adapter>=8.11.14
29
+ Requires-Dist: mcp-proxy-adapter>=8.11.16
30
30
  Requires-Dist: mcp_security_framework>=2.3.2
31
31
  Provides-Extra: scripts
32
32
  Requires-Dist: pydantic>=2.0.0; extra == "scripts"
33
- Provides-Extra: test
34
- Requires-Dist: pytest; extra == "test"
35
- Requires-Dist: pytest-asyncio; extra == "test"
36
- Requires-Dist: pytest-xdist; extra == "test"
37
- Requires-Dist: pytest-timeout; extra == "test"
38
33
  Provides-Extra: dev
39
- Requires-Dist: pytest; extra == "dev"
40
- Requires-Dist: pytest-asyncio; extra == "dev"
41
- Requires-Dist: pytest-xdist; extra == "dev"
42
- Requires-Dist: pytest-timeout; extra == "dev"
43
34
  Requires-Dist: black; extra == "dev"
44
35
  Requires-Dist: flake8; extra == "dev"
45
36
  Requires-Dist: mypy; extra == "dev"
@@ -110,7 +101,7 @@ Public queue-oriented helpers include **`embed`**, **`wait_for_job`**, **`job_st
110
101
 
111
102
  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`.
112
103
 
113
- 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`.
104
+ 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`.
114
105
 
115
106
  **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.
116
107
 
@@ -65,39 +65,4 @@ examples/security_examples_ru.py
65
65
  examples/configs/http_simple.json
66
66
  examples/configs/https_token.json
67
67
  examples/configs/mtls_roles.json
68
- examples/data/embed_file_json_array_sample.json
69
- tests/test_adapter_integration.py
70
- tests/test_adapter_phase1.py
71
- tests/test_adapter_phase2.py
72
- tests/test_all_security_modes.py
73
- tests/test_async_client_adapter.py
74
- tests/test_async_client_real.py
75
- tests/test_async_client_real_fixtures.py
76
- tests/test_async_client_stress.py
77
- tests/test_async_client_stress_new.py
78
- tests/test_async_client_stress_updated.py
79
- tests/test_auth_manager.py
80
- tests/test_canonical_mtls_example.py
81
- tests/test_cli_embed_file_json.py
82
- tests/test_cli_exit_codes_insecure.py
83
- tests/test_client_factory.py
84
- tests/test_client_factory_convenience.py
85
- tests/test_client_factory_integration.py
86
- tests/test_config.py
87
- tests/test_config_explicit_host_not_overridden.py
88
- tests/test_embed_file_aggregation_method.py
89
- tests/test_embed_file_output_validate.py
90
- tests/test_embed_immediate_mode.py
91
- tests/test_example_async_usage.py
92
- tests/test_input_limit_commands_client.py
93
- tests/test_json_embed_file_preflight.py
94
- tests/test_local_json_embed_file.py
95
- tests/test_md_embed_file_prep.py
96
- tests/test_security_matrix.py
97
- tests/test_ssl_manager.py
98
- tests/test_structured_terminal_error.py
99
- tests/test_terminal_delivery_events.py
100
- tests/test_vectorization_modes_client.py
101
- tests/test_wait_for_job_poll_queue_shape.py
102
- tests/test_wait_for_job_ws_fallback.py
103
- tests/test_with_auth.py
68
+ examples/data/embed_file_json_array_sample.json
@@ -0,0 +1,10 @@
1
+ mcp-proxy-adapter>=8.11.16
2
+ mcp_security_framework>=2.3.2
3
+
4
+ [dev]
5
+ black
6
+ flake8
7
+ mypy
8
+
9
+ [scripts]
10
+ pydantic>=2.0.0
@@ -1,8 +1,16 @@
1
1
  # Examples index
2
2
 
3
- ## 1. Canonical mTLS tour (localhost:8001)
3
+ The runnable examples select their target through the repository's single
4
+ `pipeline/endpoints.env` loader and branch-derived `PIPELINE_ENV`. They refuse
5
+ direct production calls and conflicting explicit targets. Historical filenames
6
+ retain `localhost_8001`; live targets now come from the paired table. Transport
7
+ demonstrations fail before connecting if that transport is unavailable. Security
8
+ JSON files are auth/trust fragments filled by their runner, not standalone
9
+ connection profiles. See [pipeline configuration](../../docs/PIPELINE_ENVIRONMENT.md).
4
10
 
5
- **[`canonical_mtls_localhost_8001.py`](canonical_mtls_localhost_8001.py)** — full operational walkthrough of **`EmbeddingClient`** against **localhost:8001** with **mTLS**, using **`mtls_certificates/client/`** and **`mtls_certificates/ca/`** (see **`mtls_certificates/README.md`** if present).
11
+ ## 1. Canonical mTLS tour (historical filename)
12
+
13
+ **[`canonical_mtls_localhost_8001.py`](canonical_mtls_localhost_8001.py)** — operational walkthrough of **`EmbeddingClient`** against the paired DEV endpoint with **mTLS**, using matching DEV client and CA files (see **`mtls_certificates/README.md`** if present).
6
14
 
7
15
  | Environment | Purpose |
8
16
  |-------------|---------|
@@ -50,17 +50,24 @@ from embed_client.embedding_client import EmbeddingClient # noqa: E402
50
50
 
51
51
 
52
52
  async def run_example(
53
- host: str = "localhost",
54
- port: int = 8001,
55
- protocol: str = "http",
53
+ host: Optional[str] = None,
54
+ port: Optional[int] = None,
55
+ protocol: Optional[str] = None,
56
56
  ca_path: Optional[str] = None,
57
57
  output_dir: Optional[Path] = None,
58
58
  ) -> Dict[str, Any]:
59
59
  """Generate, validate and use a client config; return the ``health()`` result.
60
60
 
61
- ``protocol`` is ``http`` or ``https`` (``https`` takes *ca_path*). Defaults reproduce the original behaviour: localhost, 8001, http,
62
- config written under ``<repo>/configs``.
61
+ Defaults come from the branch-selected pipeline endpoint. Explicit values
62
+ must match it; HTTPS takes *ca_path*. Configuration stays in the output directory.
63
63
  """
64
+ from pipeline.environment import example_target
65
+ from urllib.parse import urlsplit
66
+ base_url, selected_port = example_target(protocol)
67
+ selected = urlsplit(base_url)
68
+ if host is not None and host != selected.hostname or port is not None and port != selected_port:
69
+ raise ValueError("example host/port conflicts with the pipeline endpoint")
70
+ host, port, protocol = selected.hostname, selected_port, protocol or selected.scheme
64
71
  gen = ClientConfigGenerator()
65
72
  out_dir = Path(output_dir) if output_dir is not None else _ROOT / "configs"
66
73
  out = out_dir / "_example_generated_http.json"
@@ -96,14 +96,17 @@ def _cert_paths(root: Path) -> Dict[str, str]:
96
96
 
97
97
 
98
98
  def build_mtls_localhost_8001_config(root: Path) -> Dict[str, Any]:
99
- """Return a config dict for mTLS to localhost:8001 using repository certs."""
99
+ """Return a config for the paired DEV endpoint using repository certs."""
100
+ from pipeline.environment import example_target
101
+ from urllib.parse import urlsplit
102
+ base_url, port = example_target("mtls")
100
103
  c = _cert_paths(root)
101
104
  for k, p in c.items():
102
105
  if not Path(p).is_file():
103
106
  raise FileNotFoundError(f"Missing {k}: {p}")
104
107
  return {
105
108
  "protocol": "mtls",
106
- "server": {"host": "localhost", "port": 8001},
109
+ "server": {"host": urlsplit(base_url).hostname, "port": port},
107
110
  "auth": {
108
111
  "method": "certificate",
109
112
  "certificate": {
@@ -1,12 +1,8 @@
1
1
  {
2
- "server": {
3
- "host": "http://localhost",
4
- "port": 8001
5
- },
6
2
  "auth": {
7
3
  "method": "none"
8
4
  },
9
5
  "ssl": {
10
6
  "enabled": false
11
7
  }
12
- }
8
+ }
@@ -1,8 +1,4 @@
1
1
  {
2
- "server": {
3
- "host": "https://localhost",
4
- "port": 8443
5
- },
6
2
  "auth": {
7
3
  "method": "api_key",
8
4
  "api_keys": {
@@ -14,4 +10,4 @@
14
10
  "verify_mode": "CERT_REQUIRED",
15
11
  "check_hostname": true
16
12
  }
17
- }
13
+ }
@@ -1,8 +1,4 @@
1
1
  {
2
- "server": {
3
- "host": "https://localhost",
4
- "port": 8443
5
- },
6
2
  "auth": {
7
3
  "method": "certificate",
8
4
  "certificate": {
@@ -26,4 +22,4 @@
26
22
  "role_attributes": {
27
23
  "department": "IT"
28
24
  }
29
- }
25
+ }
@@ -34,8 +34,20 @@ DEFAULT_MODEL = "text-embedding-3-small"
34
34
 
35
35
 
36
36
  async def _run(json_path: str, model: str = DEFAULT_MODEL) -> int:
37
+ from pathlib import Path
38
+ root = str(Path(__file__).resolve().parents[2])
39
+ if root not in sys.path:
40
+ sys.path.insert(0, root)
41
+ from pipeline.environment import example_target
42
+ from urllib.parse import urlsplit
43
+ url, port = example_target()
37
44
  blocks = iter_json_array_block_texts(json_path)
38
45
  client: EmbeddingClient = ClientFactory.from_environment()
46
+ expected = urlsplit(url)
47
+ if ((client.host, client.port) != (expected.hostname, port)
48
+ or client.protocol != expected.scheme and not (expected.scheme == "https" and client.protocol == "mtls")):
49
+ await client.close()
50
+ raise ValueError("example environment conflicts with the pipeline endpoint")
39
51
  async with client:
40
52
  t0 = time.perf_counter()
41
53
  out = await client.embed_file_from_local_json_file(