inh-contracts 2.3.1__tar.gz

inh_contracts-2.3.1/.gitignore

@@ -0,0 +1,52 @@
+.env
+.env.*
+!.env.example
+
+node_modules/
+.claude/
+.grok/
+.remember/
+.venv/
+venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Anchored to the repo root deliberately -- an earlier un-anchored `data/`
+# here matched (and gitignored) infra/azure/modules/data/ too, silently
+# masking that whole Terraform module from git (#47). The anchor also means
+# the CLI's packaged release compose file (#280) needs no un-ignore rules,
+# but they stay as a guard should the anchor ever be loosened again.
+/data/
+!services/inh-cli/src/inh_cli/data/
+!services/inh-cli/src/inh_cli/data/docker-compose.release.yml
+uploads/
+playwright-report/
+test-results/
+eval-report.json
+ingestion-benchmark-report.json
+search-benchmark-report.json
+.DS_Store
+
+graphify-out/
+
+# MkDocs build output
+site/
+.memory/
+
+# Local agent tooling: skills vendored by the skills installer plus its
+# lockfile. Machine-local and third-party, same category as .claude/ and
+# .remember/ above (#347).
+.agents/
+skills-lock.json
+
+# Terraform working dirs (any root/module) — state and providers never belong in git.
+**/.terraform/
+*.tfstate
+*.tfstate.*

inh_contracts-2.3.1/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: inh-contracts
+Version: 2.3.1
+Summary: Shared contracts (Weaviate naming, versioned event schemas, embedding provider abstraction) consumed by the ingestion and public-api services
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: bandit[toml]==1.9.3; extra == 'dev'
+Requires-Dist: black==24.10.0; extra == 'dev'
+Requires-Dist: mypy==1.19.1; extra == 'dev'
+Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
+Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov==7.0.0; extra == 'dev'
+Requires-Dist: pytest==9.0.2; extra == 'dev'
+Requires-Dist: ruff==0.14.10; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# inh-contracts
+
+Shared contracts package consumed by **both** the ingestion service
+(`inh-ingestion-svc`) and the public API service (`inh-public-api-svc`).
+
+This is the single source of truth for:
+
+- **Weaviate naming** (`inh_contracts.naming`) — `get_workspace_collection_name`
+  and `get_user_tenant_name`. Both services derive collection/tenant names from
+  raw workspace/user ids and MUST agree byte-for-byte (#12).
+- **Versioned event schemas** (`inh_contracts.events`) —
+  `DocumentUploadMessage` and `DocumentCompletionMessage`, the canonical
+  cross-service event contracts carrying `contract_version` (#17).
+- **Embedding provider abstraction** (`inh_contracts.embedding`, #311) — the
+  `EmbeddingProvider` interface, the `TEIProvider` (default) and
+  `OpenAICompatibleProvider` wire adapters, `create_embedding_provider()`,
+  the shared retry/batching helpers, and the Weaviate collection
+  model-identity guard (`inh_contracts.embedding.identity`). Both services'
+  `embedder.py` are thin wrappers over this — see
+  `docs/reference/configuration.md`'s "Embedding provider &
+  model-identity guard" section for the operator-facing picture.
+
+`CONTRACT_VERSION` pins the semantic version of these contracts.
+
+## Usage
+
+Each service declares a uv path dependency in its `pyproject.toml`:
+
+```toml
+[project]
+dependencies = ["inh-contracts", ...]
+
+[tool.uv.sources]
+inh-contracts = { path = "../inh-contracts" }
+```
+
+and imports from it:
+
+```python
+from inh_contracts.naming import get_workspace_collection_name, get_user_tenant_name
+from inh_contracts.events import DocumentUploadMessage, DocumentCompletionMessage
+```

inh_contracts-2.3.1/Readme.md

@@ -0,0 +1,42 @@
+# inh-contracts
+
+Shared contracts package consumed by **both** the ingestion service
+(`inh-ingestion-svc`) and the public API service (`inh-public-api-svc`).
+
+This is the single source of truth for:
+
+- **Weaviate naming** (`inh_contracts.naming`) — `get_workspace_collection_name`
+  and `get_user_tenant_name`. Both services derive collection/tenant names from
+  raw workspace/user ids and MUST agree byte-for-byte (#12).
+- **Versioned event schemas** (`inh_contracts.events`) —
+  `DocumentUploadMessage` and `DocumentCompletionMessage`, the canonical
+  cross-service event contracts carrying `contract_version` (#17).
+- **Embedding provider abstraction** (`inh_contracts.embedding`, #311) — the
+  `EmbeddingProvider` interface, the `TEIProvider` (default) and
+  `OpenAICompatibleProvider` wire adapters, `create_embedding_provider()`,
+  the shared retry/batching helpers, and the Weaviate collection
+  model-identity guard (`inh_contracts.embedding.identity`). Both services'
+  `embedder.py` are thin wrappers over this — see
+  `docs/reference/configuration.md`'s "Embedding provider &
+  model-identity guard" section for the operator-facing picture.
+
+`CONTRACT_VERSION` pins the semantic version of these contracts.
+
+## Usage
+
+Each service declares a uv path dependency in its `pyproject.toml`:
+
+```toml
+[project]
+dependencies = ["inh-contracts", ...]
+
+[tool.uv.sources]
+inh-contracts = { path = "../inh-contracts" }
+```
+
+and imports from it:
+
+```python
+from inh_contracts.naming import get_workspace_collection_name, get_user_tenant_name
+from inh_contracts.events import DocumentUploadMessage, DocumentCompletionMessage
+```

inh_contracts-2.3.1/pyproject.toml

@@ -0,0 +1,96 @@
+[project]
+name = "inh-contracts"
+version = "2.3.1"
+description = "Shared contracts (Weaviate naming, versioned event schemas, embedding provider abstraction) consumed by the ingestion and public-api services"
+readme = "Readme.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2",
+    # Embedding provider HTTP adapters (#311) -- matches the floor already
+    # required by inh-ingestion-svc so the resolved version can't drift.
+    "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+# Dev tooling versions are normalized across all three services (M7 #21).
+# See docs/developer/dependencies.md for the shared pin policy.
+dev = [
+    "pytest==9.0.2",
+    "pytest-asyncio==1.3.0",
+    "pytest-cov==7.0.0",
+    "black==24.10.0",
+    "ruff==0.14.10",
+    "mypy==1.19.1",
+    "bandit[toml]==1.9.3",
+    "pre-commit>=3.6.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/inh_contracts"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true
+
+# Mirrors inh-public-api-svc's [tool.bandit] verbatim so all three services
+# gate on the SAME severity threshold -- CI invokes `bandit -c pyproject.toml
+# -r src` everywhere. This package is clean at LOW and above with no
+# suppressions; the config exists so it STAYS gated at that threshold rather
+# than silently drifting to a laxer one.
+[tool.bandit]
+exclude_dirs = ["tests", "build", "dist"]
+skips = ["B101"]  # Skip assert_used check (used in tests)
+
+[tool.bandit.assert_used]
+skips = ["*_test.py", "test_*.py"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_functions = ["test_*"]
+# Mirrors the two services' pytest addopts (--cov=src) so `ci.yml`'s shared
+# `--cov-fail-under=${{ matrix.cov_fail_under }}` Test step works the same
+# way for this package (#132 item 4 -- this package previously ran in no
+# automation at all, so a change to a shared constant like DEFAULT_S3_REGION
+# was caught by nothing).
+addopts = "--cov=src --cov-report=term-missing"
+markers = [
+    "contract: contract/schema regression tests for shared event + naming surfaces",
+    "unit: fast isolated unit tests",
+]
+
+[tool.coverage.report]
+precision = 1
+
+# Mirrors [project.optional-dependencies].dev so `uv sync --extra dev --group dev`
+# resolves to the same normalized pins regardless of which flag is used (M7 #21).
+[dependency-groups]
+dev = [
+    "pytest==9.0.2",
+    "pytest-asyncio==1.3.0",
+    "pytest-cov==7.0.0",
+    "black==24.10.0",
+    "ruff==0.14.10",
+    "mypy==1.19.1",
+    "bandit[toml]==1.9.3",
+    "pre-commit>=3.6.0",
+]

inh_contracts-2.3.1/src/inh_contracts/__init__.py

@@ -0,0 +1,100 @@
+"""inh-contracts: shared contracts consumed by both Inherent services.
+
+Single source of truth for Weaviate naming (#12), the versioned cross-service
+event schemas (#17), shared configuration defaults (#132), the file-type
+support registry (#117), and the embedding provider abstraction (#311). See
+``inh_contracts.naming``, ``inh_contracts.events``, ``inh_contracts.defaults``,
+``inh_contracts.file_types`` and ``inh_contracts.embedding``.
+"""
+
+from inh_contracts.defaults import DEFAULT_MONGODB_URI, DEFAULT_S3_BUCKET, DEFAULT_S3_REGION
+from inh_contracts.embedding import (
+    DEFAULT_EMBEDDING_PROVIDER,
+    EmbeddingIdentity,
+    EmbeddingIdentityAdoptionRequiredError,
+    EmbeddingIdentityMismatchError,
+    EmbeddingProvider,
+    OpenAICompatibleProvider,
+    TEIProvider,
+    create_embedding_provider,
+    decode_identity,
+    embed_batch_with_retry,
+    embed_single,
+    embed_texts_batched,
+    encode_identity,
+    is_transient_embed_error,
+    redact_url,
+    resolve_identity,
+)
+from inh_contracts.events import (
+    CONTRACT_VERSION,
+    ConversationTurnMessage,
+    DocumentCompletionMessage,
+    DocumentUploadMessage,
+    StorageBackend,
+)
+from inh_contracts.file_types import (
+    FILE_TYPE_REGISTRY,
+    ContentTypeMismatchError,
+    ExtensionMismatchError,
+    FileTypeSpec,
+    UnknownContentTypeError,
+    all_mime_types,
+    check_extension_consistency,
+    get_spec_by_key,
+    get_spec_for_extension,
+    get_spec_for_mime,
+    mcp_mime_types,
+    render_markdown_table,
+    sniff_content_type,
+)
+from inh_contracts.naming import (
+    USER_TENANT_PREFIX,
+    WORKSPACE_COLLECTION_PREFIX,
+    get_user_tenant_name,
+    get_workspace_collection_name,
+)
+
+__all__ = [
+    "CONTRACT_VERSION",
+    "DocumentUploadMessage",
+    "DocumentCompletionMessage",
+    "ConversationTurnMessage",
+    "StorageBackend",
+    "get_workspace_collection_name",
+    "get_user_tenant_name",
+    "WORKSPACE_COLLECTION_PREFIX",
+    "USER_TENANT_PREFIX",
+    "DEFAULT_S3_REGION",
+    "DEFAULT_S3_BUCKET",
+    "DEFAULT_MONGODB_URI",
+    "FILE_TYPE_REGISTRY",
+    "FileTypeSpec",
+    "UnknownContentTypeError",
+    "ContentTypeMismatchError",
+    "ExtensionMismatchError",
+    "all_mime_types",
+    "mcp_mime_types",
+    "get_spec_for_mime",
+    "get_spec_for_extension",
+    "get_spec_by_key",
+    "sniff_content_type",
+    "check_extension_consistency",
+    "render_markdown_table",
+    "EmbeddingProvider",
+    "EmbeddingIdentity",
+    "EmbeddingIdentityMismatchError",
+    "EmbeddingIdentityAdoptionRequiredError",
+    "TEIProvider",
+    "OpenAICompatibleProvider",
+    "create_embedding_provider",
+    "redact_url",
+    "encode_identity",
+    "decode_identity",
+    "resolve_identity",
+    "embed_single",
+    "embed_texts_batched",
+    "embed_batch_with_retry",
+    "is_transient_embed_error",
+    "DEFAULT_EMBEDDING_PROVIDER",
+]

inh_contracts-2.3.1/src/inh_contracts/conversation.py

@@ -0,0 +1,53 @@
+"""Conversation-document contract: the synthetic identifiers a conversation's
+``processed_documents`` row and Weaviate chunks carry (#306).
+
+A conversation is not a file. It has no uploaded bytes, so
+``ConversationMemoryWorkflow`` stamps synthetic-but-real values that satisfy
+``processed_documents``' file-shaped NOT NULL/CHECK constraints (migration
+001) while still being unambiguously identifiable as "not a file":
+
+- ``content_type = CONVERSATION_CONTENT_TYPE`` -- written to
+  ``processed_documents.content_type`` AND to every Weaviate chunk object's
+  ``content_type`` property, so BOTH read paths (Postgres document row,
+  Weaviate search result) can tell a conversation chunk from a file chunk
+  without a second lookup.
+- ``document_type = CONVERSATION_DOCUMENT_TYPE`` -- the Postgres-only column
+  migration 020 adds, used for row-scoped queries (external-id lookup,
+  conversation stats).
+
+These live here rather than in either service because both sides need them:
+``inh-ingestion-svc`` WRITES them (``conversation_memory.py``) and
+``inh-public-api-svc`` READS them (freshness/staleness, conversation
+queries). Same drift lesson as ``file_types.py`` -- a string literal
+duplicated across two services is a bug waiting for one of them to be
+edited alone.
+"""
+
+from typing import Final
+
+# The synthetic MIME type a conversation document/chunk carries. Deliberately
+# in the `application/x-` vendor-extension space: it is NOT a real file format
+# and must never match a FILE_TYPE_REGISTRY entry (see file_types.py).
+CONVERSATION_CONTENT_TYPE: Final[str] = "application/x-inherent-conversation"
+
+# `processed_documents.document_type` values (migration 020's CHECK
+# constraint allows exactly these two). 'file' is the default every
+# pre-existing row backfilled to.
+CONVERSATION_DOCUMENT_TYPE: Final[str] = "conversation"
+FILE_DOCUMENT_TYPE: Final[str] = "file"
+
+
+def is_conversation(
+    *,
+    content_type: str | None = None,
+    document_type: str | None = None,
+) -> bool:
+    """Return True when either signal identifies a conversation document.
+
+    Both arguments are optional and independently sufficient, because the two
+    read paths carry different ones: a Weaviate search result has the chunk's
+    ``content_type`` but no ``document_type`` (that column is Postgres-only),
+    while a ``processed_documents`` row has both. Unknown/absent values
+    (``None``) simply do not match -- this never guesses.
+    """
+    return content_type == CONVERSATION_CONTENT_TYPE or document_type == CONVERSATION_DOCUMENT_TYPE

inh_contracts-2.3.1/src/inh_contracts/defaults.py

@@ -0,0 +1,70 @@
+"""Shared configuration defaults -- single source of truth (#132).
+
+Both services accept an S3/object-store region override via an env var, but
+each used to hardcode its OWN fallback default in its pydantic ``Settings``
+class:
+
+- ``inh-public-api-svc`` defaulted ``aws_s3_region`` to ``"eu-central-1"``.
+- ``inh-ingestion-svc`` defaulted ``s3_region`` to ``"nbg1"`` (a Hetzner
+  Object Storage location code -- not even the same naming scheme as an
+  AWS-style region string).
+
+A deployment that sets the region env var for only one service (or relies on
+defaults during local dev / a bare ``uv run`` without docker-compose) silently
+leaves the other service on its own, different default. Uploads then land in
+one region/bucket while reads target another -- #132.
+
+``DEFAULT_S3_REGION`` is now the ONE default both services' Settings classes
+import, so the code-level fallback (used whenever the region env var is
+unset) can never disagree between the two services again. This mirrors the
+existing anti-drift pattern for Weaviate naming (see ``inh_contracts.naming``,
+#12): put the single value here, have both services import it, and pin a
+contract test on each side (``test_settings_region_contract.py``) so a future
+hardcoded literal on either side fails CI instead of drifting silently.
+
+The value matches the default already baked into the deployed stack
+(``docker-compose.yml``, ``docker-compose.release.yml``, ``infra/server.tf``
+and ``.env.example`` all default ``AWS_REGION`` to ``us-east-1``), so a
+service now agrees with the documented, deployed default even when started
+directly (e.g. tests, local ``uv run``) without compose's env injection.
+"""
+
+DEFAULT_S3_REGION = "us-east-1"
+
+# ---------------------------------------------------------------------------
+# #176 -- two more cross-service config defaults drifting the same way the
+# S3 region did before #132. Both found while re-reading each service's
+# Settings class during the #132 pattern sweep; scripts/validate_env.py
+# already runtime-checks the resolved values for both, but that only warns
+# once an operator has actually set the two env vars to *different* values --
+# it does not catch the two services silently defaulting to different values
+# when an operator sets neither.
+# ---------------------------------------------------------------------------
+
+# ``inh-ingestion-svc`` defaulted ``storage_bucket`` (env ``STORAGE_BUCKET``)
+# to ``""`` while ``inh-public-api-svc`` defaulted ``aws_s3_bucket`` (env
+# ``AWS_S3_BUCKET``) to ``"inherent-documents"``. An operator who sets
+# neither env var got ingestion writing to an empty bucket name while
+# public-api read from ``"inherent-documents"`` -- the exact #132 shape.
+# Ingestion's primary upload path mostly uses the per-message
+# ``storage_bucket`` from the event payload rather than this Settings
+# default (see ``services/storage.py``'s ``default_bucket`` fallback), so the
+# empty-string default was rarely the effective value -- but the same
+# single-source-of-truth fix applies for defense in depth and consistency
+# with the #132 precedent. Both services now default to this shared bucket
+# name; the real deployed bucket is still fully operator-configurable via
+# ``STORAGE_BUCKET`` / ``AWS_S3_BUCKET``.
+DEFAULT_S3_BUCKET = "inherent-documents"
+
+# Both services also defaulted ``mongodb_db_name`` to ``"main"`` and both
+# select the database explicitly via that field when opening the Mongo
+# client (``client[settings.mongodb_db_name]``, see
+# ``inh-public-api-svc/src/services/mongo_client.py`` and
+# ``inh-ingestion-svc/src/temporal/activities/audit_activities.py``) -- so
+# the URI's own path segment is inert either way. Still, ``mongodb_uri``
+# defaulted to two different literals (``.../27017`` vs ``.../27017/main``),
+# the same "hardcoded twice, drifted slightly" shape #132 exists to prevent.
+# Single-sourced here with no path segment -- the path is not the source of
+# truth for database selection, ``mongodb_db_name`` is, so the shared
+# default should not imply otherwise.
+DEFAULT_MONGODB_URI = "mongodb://localhost:27017"

inh_contracts-2.3.1/src/inh_contracts/embedding/__init__.py

@@ -0,0 +1,67 @@
+"""Shared embedding-provider abstraction (#311).
+
+Single source of truth for both services' embedder modules: the
+``EmbeddingProvider`` interface, the TEI (default) and OpenAI-compatible wire
+adapters, the factory that selects one from ``EMBEDDING_PROVIDER``, the
+retry/batching helpers that give both the ingestion write path and the
+public-api query path identical behavior, and the Weaviate collection
+model-identity guard. See ``inh_contracts.embedding.identity`` for the
+identity-guard policy write-up.
+"""
+
+from inh_contracts.embedding.batching import embed_single, embed_texts_batched
+from inh_contracts.embedding.defaults import (
+    BATCH_RETRY_SLEEP_BUDGET_S,
+    DEFAULT_BATCH_MAX_RETRIES,
+    DEFAULT_BATCH_SIZE,
+    DEFAULT_EMBEDDING_PROVIDER,
+    DEFAULT_MAX_CONCURRENCY,
+    DEFAULT_QUERY_MAX_RETRIES,
+    DEFAULT_QUERY_TIMEOUT_S,
+    DEFAULT_TIMEOUT_S,
+    QUERY_RETRY_SLEEP_BUDGET_S,
+)
+from inh_contracts.embedding.factory import create_embedding_provider
+from inh_contracts.embedding.identity import (
+    EmbeddingIdentityAdoptionRequiredError,
+    EmbeddingIdentityMismatchError,
+    decode_identity,
+    encode_identity,
+    resolve_identity,
+)
+from inh_contracts.embedding.openai_provider import OpenAICompatibleProvider
+from inh_contracts.embedding.provider import EmbeddingIdentity, EmbeddingProvider, redact_url
+from inh_contracts.embedding.retry import (
+    embed_batch_with_retry,
+    is_transient_embed_error,
+    max_wall_clock_s,
+)
+from inh_contracts.embedding.tei_provider import TEIProvider
+
+__all__ = [
+    "EmbeddingProvider",
+    "EmbeddingIdentity",
+    "EmbeddingIdentityMismatchError",
+    "EmbeddingIdentityAdoptionRequiredError",
+    "TEIProvider",
+    "OpenAICompatibleProvider",
+    "create_embedding_provider",
+    "redact_url",
+    "encode_identity",
+    "decode_identity",
+    "resolve_identity",
+    "embed_single",
+    "embed_texts_batched",
+    "embed_batch_with_retry",
+    "is_transient_embed_error",
+    "max_wall_clock_s",
+    "DEFAULT_EMBEDDING_PROVIDER",
+    "DEFAULT_BATCH_SIZE",
+    "DEFAULT_MAX_CONCURRENCY",
+    "DEFAULT_TIMEOUT_S",
+    "DEFAULT_BATCH_MAX_RETRIES",
+    "BATCH_RETRY_SLEEP_BUDGET_S",
+    "DEFAULT_QUERY_TIMEOUT_S",
+    "DEFAULT_QUERY_MAX_RETRIES",
+    "QUERY_RETRY_SLEEP_BUDGET_S",
+]

inh_contracts-2.3.1/src/inh_contracts/embedding/batching.py

@@ -0,0 +1,102 @@
+"""Zero-vector shortcuts, TEI-sized batching, and bounded concurrency (#311).
+
+Ported verbatim (behaviorally) from ``inh-ingestion-svc``'s ``embedder.py``,
+which is the side that originally had this logic; ``embed_query`` on the
+public-api side gets it for the first time via this shared module.
+"""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from inh_contracts.embedding.defaults import (
+    BATCH_RETRY_SLEEP_BUDGET_S,
+    DEFAULT_BATCH_MAX_RETRIES,
+    DEFAULT_BATCH_SIZE,
+    DEFAULT_MAX_CONCURRENCY,
+)
+from inh_contracts.embedding.provider import EmbeddingProvider
+from inh_contracts.embedding.retry import embed_batch_with_retry
+
+
+def embed_single(
+    provider: EmbeddingProvider,
+    text: str,
+    *,
+    max_retries: int = DEFAULT_BATCH_MAX_RETRIES,
+    retry_budget_s: float = BATCH_RETRY_SLEEP_BUDGET_S,
+) -> list[float]:
+    """Return a normalized embedding for one text.
+
+    Empty / whitespace-only input returns a zero vector -- those chunks/
+    queries shouldn't surface in semantic search results anyway, and we
+    avoid a network round-trip.
+    """
+    if not text or not text.strip():
+        return [0.0] * provider.dimension
+    vecs = embed_batch_with_retry(
+        provider, [text], max_retries=max_retries, retry_budget_s=retry_budget_s
+    )
+    return vecs[0]
+
+
+def embed_texts_batched(
+    provider: EmbeddingProvider,
+    texts: list[str],
+    *,
+    batch_size: int = DEFAULT_BATCH_SIZE,
+    max_concurrency: int = DEFAULT_MAX_CONCURRENCY,
+    max_retries: int = DEFAULT_BATCH_MAX_RETRIES,
+    retry_budget_s: float = BATCH_RETRY_SLEEP_BUDGET_S,
+) -> list[list[float]]:
+    """Batched embedding with bounded parallel dispatch (#231 phase 1).
+
+    Empty strings still get zero vectors (preserved per-position), and only
+    the non-empty positions go over the wire. Batches run concurrently up to
+    ``max_concurrency`` so a large document is
+    ``ceil(n_batches / concurrency)`` round-trips instead of ``n_batches``
+    serial ones.
+    """
+    dim = provider.dimension
+    if not texts:
+        return []
+    keep_idx = [i for i, t in enumerate(texts) if t and t.strip()]
+    if not keep_idx:
+        return [[0.0] * dim for _ in texts]
+
+    # Chunk into batches under the provider's max batch size to avoid a
+    # payload-too-large response. A 535-chunk PDF was failing with one giant
+    # POST against TEI; batching keeps every request comfortably sized.
+    batch = max(1, batch_size)
+    keep_texts = [texts[i] for i in keep_idx]
+    batches: list[tuple[int, list[str]]] = []
+    for offset in range(0, len(keep_texts), batch):
+        batches.append((offset, keep_texts[offset : offset + batch]))
+
+    # index-in-keep_texts -> vector
+    results: dict[int, list[float]] = {}
+    concurrency = min(max(1, max_concurrency), len(batches))
+
+    def _run_batch(item: tuple[int, list[str]]) -> tuple[int, list[list[float]]]:
+        offset, inputs = item
+        return offset, embed_batch_with_retry(
+            provider, inputs, max_retries=max_retries, retry_budget_s=retry_budget_s
+        )
+
+    if concurrency == 1:
+        for item in batches:
+            offset, vecs = _run_batch(item)
+            for j, vec in enumerate(vecs):
+                results[offset + j] = vec
+    else:
+        with ThreadPoolExecutor(max_workers=concurrency) as pool:
+            futures = [pool.submit(_run_batch, item) for item in batches]
+            for fut in as_completed(futures):
+                offset, vecs = fut.result()
+                for j, vec in enumerate(vecs):
+                    results[offset + j] = vec
+
+    out: list[list[float]] = [[0.0] * dim for _ in texts]
+    for j, i in enumerate(keep_idx):
+        out[i] = results[j]
+    return out