keble-data-infra-api 0.1.0__tar.gz

keble_data_infra_api-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+cert/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+*__ignored__*
+
+*.env
+**/.env.docker
+*.DS_Store
+**/.DS_Store
+
+.vscode
+.idea
+
+*.crt
+
+uploads/
+!strapi-v5/public/uploads/
+!strapi-v5/public/uploads/.gitkeep
+test/
+resources/
+Brewfile
+qdrant/
+*.pyc
+**.pyc.*
+*/traefik/certs
+*/traefik/certs/*
+gcp.json
+.history
+
+prod.env.*

keble_data_infra_api-0.1.0/Dockerfile

@@ -0,0 +1,45 @@
+FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim AS builder
+
+RUN apt-get update
+RUN apt-get install --yes --no-install-recommends git build-essential
+RUN rm -rf /var/lib/apt/lists/*
+
+ARG KEBLE_AMZ_REF=b6ce544995cd14c6930bdfdfa809cd5ba10e7833
+ARG KEBLE_TIKTOK_REF=f14a9c670d270a201f2359e608f6b1e2b0493825
+ARG KEBLE_PY_REF=9db27c8c4cac25fcf4993620168c9f77dd95a0f5
+ARG KEBLE_KEEPA_REF=5907fe43d3368fec6e64da4c30e33eddb7b1d885
+
+WORKDIR /workspace
+RUN --mount=type=secret,id=gh_token \
+    sh -eu -c 'TOKEN="$(cat /run/secrets/gh_token)"; BASIC="$(printf "x-access-token:%s" "${TOKEN}" | base64 -w0)"; git -c http.extraHeader="Authorization: Basic ${BASIC}" clone https://github.com/keble-ai/keble-amz.git data-infra/keble-amz'
+RUN git -C data-infra/keble-amz checkout ${KEBLE_AMZ_REF}
+RUN --mount=type=secret,id=gh_token \
+    sh -eu -c 'TOKEN="$(cat /run/secrets/gh_token)"; BASIC="$(printf "x-access-token:%s" "${TOKEN}" | base64 -w0)"; git -c http.extraHeader="Authorization: Basic ${BASIC}" clone https://github.com/keble-ai/keble-tiktok.git data-infra/keble-tiktok'
+RUN git -C data-infra/keble-tiktok checkout ${KEBLE_TIKTOK_REF}
+RUN --mount=type=secret,id=gh_token \
+    sh -eu -c 'TOKEN="$(cat /run/secrets/gh_token)"; BASIC="$(printf "x-access-token:%s" "${TOKEN}" | base64 -w0)"; git -c http.extraHeader="Authorization: Basic ${BASIC}" clone https://github.com/keble-ai/keble-py.git deps/keble-py'
+RUN git -C deps/keble-py checkout ${KEBLE_PY_REF}
+RUN --mount=type=secret,id=gh_token \
+    sh -eu -c 'TOKEN="$(cat /run/secrets/gh_token)"; BASIC="$(printf "x-access-token:%s" "${TOKEN}" | base64 -w0)"; git -c http.extraHeader="Authorization: Basic ${BASIC}" clone https://github.com/keble-ai/keble-keepa.git deps/keble-keepa'
+RUN git -C deps/keble-keepa checkout ${KEBLE_KEEPA_REF}
+
+COPY . /workspace/data-infra/keble-data-infra
+WORKDIR /workspace/data-infra/keble-data-infra
+RUN uv sync --no-editable --no-default-groups --package keble-data-infra-api
+
+FROM python:3.13-slim-bookworm AS runtime
+
+ENV PATH="/workspace/data-infra/keble-data-infra/.venv/bin:${PATH}" \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+RUN useradd --create-home --uid 10001 keble
+WORKDIR /workspace/data-infra/keble-data-infra
+COPY --from=builder --chown=keble:keble /workspace/data-infra/keble-data-infra/.venv /workspace/data-infra/keble-data-infra/.venv
+
+USER keble
+EXPOSE 8000
+HEALTHCHECK --interval=15s --timeout=5s --start-period=15s --retries=4 \
+    CMD ["python", "-c", "from urllib.request import urlopen; urlopen('http://127.0.0.1:8000/ready', timeout=3).read()"]
+
+CMD ["uvicorn", "keble_data_infra_api.main:app", "--host", "0.0.0.0", "--port", "8000"]

keble_data_infra_api-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: keble-data-infra-api
+Version: 0.1.0
+Summary: Sole FastAPI composition root for Keble raw provider data.
+Author-email: zhenhao-ma <bob0103779@gmail.com>
+Requires-Python: <3.14,>=3.13
+Requires-Dist: aiohttp<4,>=3
+Requires-Dist: fastapi<1,>=0.110
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: keble-amz<3,>=2.0.0
+Requires-Dist: keble-data-infra-contract<1,>=0.1.0
+Requires-Dist: keble-db<2,>=1.9.0
+Requires-Dist: keble-helpers<2,>=1.12.2
+Requires-Dist: keble-keepa<2,>=1.3.0
+Requires-Dist: keble-tiktok<1,>=0.5.0
+Requires-Dist: motor<4,>=3
+Requires-Dist: pymongo<5,>=4.10
+Requires-Dist: redis<7,>=5
+Requires-Dist: sentry-sdk<3,>=2
+Requires-Dist: uvicorn<1,>=0.29
+Description-Content-Type: text/markdown
+
+# keble-data-infra-api
+
+Install the composed raw-data API with
+`pip install "keble-data-infra-api>=0.1.0,<1"`. The published distribution
+resolves the released Amazon and TikTok providers; editable local sources in
+the uv workspace are development-only.
+
+The sole FastAPI composition root for raw Amazon and TikTok provider data.
+Provider packages export framework-free services and manifests; this package
+owns route generation, exception mapping, runtime resources, and ingestion.
+
+The Stand Out platform consumes this service over HTTP and does not import its
+contracts or provider packages.
+
+## Local provider environment
+
+Build an ignored API-local `.env` from the existing Keble developer env files.
+The helper copies only the required named settings and prints key names, never
+credential values:
+
+```bash
+python scripts/build_local_env.py
+uv run --env-file .env pytest -q tests/live -m live
+```
+
+The live suite uses independent `RUN_KEEPA_LIVE`, `RUN_FASTMOSS_LIVE`, and
+`RUN_LIVE_ECHOTIK` gates. A gate is written only when its complete credential
+set exists. Each configured provider runs as a separate canary, so one missing
+credential cannot hide another provider's result. Provider failures are test
+failures; missing opt-in credentials are the only valid reason to skip. Live
+providers honor `PROVIDER_HTTP_TRUST_ENV` through `ApiSettings` instead of
+hard-coding direct network access, matching the production runtime boundary.
+The pinned TikTok provider includes HTTPX's SOCKS transport, so production
+SOCKS4/5 proxy settings remain executable rather than failing during client
+construction. The image also pins the timezone-aware/warning-free keble-db
+checkpoint used by the local-full persistence proof.
+
+## Runtime ownership
+
+`keble_data_infra_api.main:create_app` constructs the only raw FastAPI app.
+`api.router:create_router` builds discovery and provider routes from the
+registry, and `api.error_handlers` performs typed exception conversion. The
+Stand Out adapter resolves the single product-search capability through
+`GET /v1/{channel}/providers` and then calls its generated operation. The old
+`/v1/commerce/search` route and compatibility DTO snapshot are deleted.
+
+API settings and immutable application values reuse
+`keble-helpers.PydanticModelConfig` or the contract-owned `ContractModel`.
+Durable aggregates use `SchemaBase`/`MongoObjectBase`; do not introduce a local
+`ConfigDict` or direct persistence `BaseModel` policy.
+
+Mongo/Redis settings enable the API-owned provider infrastructure. The local
+env builder copies only `MONGO_DB_URI`, `REDIS_URI`, and named provider
+credentials; API-owned database/collection/namespace defaults stay isolated.
+Startup creates cache indexes before provider handlers run and shutdown closes
+all sync/async Mongo and Redis clients.
+
+Video Enrichment projection is also API-owned and requires Mongo whenever its
+Result origin is configured. One document stores the source event, owner-token
+claim, attempts, failure state, and optional projection. Unique event/result
+indexes plus expiring claims make concurrent consumers safe; Redis entries are
+acknowledged only after the document atomically reaches `completed`. The old
+replica-local JSON state file is not supported.
+
+The same typed gateway centralizes submission and job/result correlation:
+
+```text
+POST /internal/video-enrichments:submit
+GET  /internal/video-enrichment-jobs/{job_id}
+GET  /internal/video-enrichment-jobs/{job_id}/projection
+```
+
+The projection lookup uses the API-owned job/status/completion-time compound
+index. Consumers never call the independent media service or infer `result_id`
+from provider storage. A projection 404 means durable completion ingestion is
+still pending and is safe for a bounded worker retry.
+
+The submission gateway forwards the expected media SHA-256 as a dedicated
+integrity field. When an authorized provider transcript exists, the contract binds
+its normalized content checksum, source reference, and source media checksum before
+the independent service may skip ASR. The API never treats a provider title or video
+description as spoken captions.
+
+The producer's Job/Result payload contains additional stage, artifact, usage,
+frame, warning, and error fields. Data Infra validates the typed stable subset
+through the contract's source-projection inheritance and ignores only those
+additive producer fields. All submission and public normalized models retain
+`extra="forbid"`; compatibility does not weaken command validation.
+
+Configured provider routes include:
+
+```text
+POST /v1/amazon/providers/keepa/products/lookup
+POST /v1/amazon/providers/keepa/products/search
+POST /v1/amazon/providers/keepa/products/rank
+POST /v1/tiktok/providers/fastmoss/products/search
+POST /v1/tiktok/providers/echotik/products/rank
+```
+
+Run the isolated all-provider generated-route canary with:
+
+```bash
+python scripts/build_local_env.py
+uv run --env-file .env pytest -q tests/live/test_provider_routes_live.py -m live
+```
+
+## Container and observability
+
+The multi-stage image installs exact pushed provider commits and receives the
+GitHub token only as a BuildKit secret. It runs as UID 10001, exposes `/health`
+for liveness and `/ready` for configured Mongo/Redis readiness, and closes all
+runtime clients through FastAPI lifespan.
+
+Build the credential-preserving Docker env and start the profile on the existing
+`keble_default` network:
+
+```bash
+uv run --directory keble-data-infra-api python scripts/build_local_env.py
+uv run --directory keble-data-infra-api python -m scripts.build_local_docker_env
+GH_TOKEN="$(gh auth token)" docker compose \
+  --env-file keble-data-infra-api/.env.docker \
+  -f deploy/compose.raw-api.yaml --profile raw-api up --build
+```
+
+`.env`, `.env.docker`, and the BuildKit secret stay outside Git and image
+layers. Set `SENTRY_DSN`, `SENTRY_ENVIRONMENT`, and
+`SENTRY_TRACES_SAMPLE_RATE` in the source env to enable error/performance
+telemetry. Registry discovery, generated operations, cache outcomes, lease
+contention, upstream work, batches, and video ingestion emit structural spans;
+request/response content and credentials are not attached.

keble_data_infra_api-0.1.0/README.md

@@ -0,0 +1,130 @@
+# keble-data-infra-api
+
+Install the composed raw-data API with
+`pip install "keble-data-infra-api>=0.1.0,<1"`. The published distribution
+resolves the released Amazon and TikTok providers; editable local sources in
+the uv workspace are development-only.
+
+The sole FastAPI composition root for raw Amazon and TikTok provider data.
+Provider packages export framework-free services and manifests; this package
+owns route generation, exception mapping, runtime resources, and ingestion.
+
+The Stand Out platform consumes this service over HTTP and does not import its
+contracts or provider packages.
+
+## Local provider environment
+
+Build an ignored API-local `.env` from the existing Keble developer env files.
+The helper copies only the required named settings and prints key names, never
+credential values:
+
+```bash
+python scripts/build_local_env.py
+uv run --env-file .env pytest -q tests/live -m live
+```
+
+The live suite uses independent `RUN_KEEPA_LIVE`, `RUN_FASTMOSS_LIVE`, and
+`RUN_LIVE_ECHOTIK` gates. A gate is written only when its complete credential
+set exists. Each configured provider runs as a separate canary, so one missing
+credential cannot hide another provider's result. Provider failures are test
+failures; missing opt-in credentials are the only valid reason to skip. Live
+providers honor `PROVIDER_HTTP_TRUST_ENV` through `ApiSettings` instead of
+hard-coding direct network access, matching the production runtime boundary.
+The pinned TikTok provider includes HTTPX's SOCKS transport, so production
+SOCKS4/5 proxy settings remain executable rather than failing during client
+construction. The image also pins the timezone-aware/warning-free keble-db
+checkpoint used by the local-full persistence proof.
+
+## Runtime ownership
+
+`keble_data_infra_api.main:create_app` constructs the only raw FastAPI app.
+`api.router:create_router` builds discovery and provider routes from the
+registry, and `api.error_handlers` performs typed exception conversion. The
+Stand Out adapter resolves the single product-search capability through
+`GET /v1/{channel}/providers` and then calls its generated operation. The old
+`/v1/commerce/search` route and compatibility DTO snapshot are deleted.
+
+API settings and immutable application values reuse
+`keble-helpers.PydanticModelConfig` or the contract-owned `ContractModel`.
+Durable aggregates use `SchemaBase`/`MongoObjectBase`; do not introduce a local
+`ConfigDict` or direct persistence `BaseModel` policy.
+
+Mongo/Redis settings enable the API-owned provider infrastructure. The local
+env builder copies only `MONGO_DB_URI`, `REDIS_URI`, and named provider
+credentials; API-owned database/collection/namespace defaults stay isolated.
+Startup creates cache indexes before provider handlers run and shutdown closes
+all sync/async Mongo and Redis clients.
+
+Video Enrichment projection is also API-owned and requires Mongo whenever its
+Result origin is configured. One document stores the source event, owner-token
+claim, attempts, failure state, and optional projection. Unique event/result
+indexes plus expiring claims make concurrent consumers safe; Redis entries are
+acknowledged only after the document atomically reaches `completed`. The old
+replica-local JSON state file is not supported.
+
+The same typed gateway centralizes submission and job/result correlation:
+
+```text
+POST /internal/video-enrichments:submit
+GET  /internal/video-enrichment-jobs/{job_id}
+GET  /internal/video-enrichment-jobs/{job_id}/projection
+```
+
+The projection lookup uses the API-owned job/status/completion-time compound
+index. Consumers never call the independent media service or infer `result_id`
+from provider storage. A projection 404 means durable completion ingestion is
+still pending and is safe for a bounded worker retry.
+
+The submission gateway forwards the expected media SHA-256 as a dedicated
+integrity field. When an authorized provider transcript exists, the contract binds
+its normalized content checksum, source reference, and source media checksum before
+the independent service may skip ASR. The API never treats a provider title or video
+description as spoken captions.
+
+The producer's Job/Result payload contains additional stage, artifact, usage,
+frame, warning, and error fields. Data Infra validates the typed stable subset
+through the contract's source-projection inheritance and ignores only those
+additive producer fields. All submission and public normalized models retain
+`extra="forbid"`; compatibility does not weaken command validation.
+
+Configured provider routes include:
+
+```text
+POST /v1/amazon/providers/keepa/products/lookup
+POST /v1/amazon/providers/keepa/products/search
+POST /v1/amazon/providers/keepa/products/rank
+POST /v1/tiktok/providers/fastmoss/products/search
+POST /v1/tiktok/providers/echotik/products/rank
+```
+
+Run the isolated all-provider generated-route canary with:
+
+```bash
+python scripts/build_local_env.py
+uv run --env-file .env pytest -q tests/live/test_provider_routes_live.py -m live
+```
+
+## Container and observability
+
+The multi-stage image installs exact pushed provider commits and receives the
+GitHub token only as a BuildKit secret. It runs as UID 10001, exposes `/health`
+for liveness and `/ready` for configured Mongo/Redis readiness, and closes all
+runtime clients through FastAPI lifespan.
+
+Build the credential-preserving Docker env and start the profile on the existing
+`keble_default` network:
+
+```bash
+uv run --directory keble-data-infra-api python scripts/build_local_env.py
+uv run --directory keble-data-infra-api python -m scripts.build_local_docker_env
+GH_TOKEN="$(gh auth token)" docker compose \
+  --env-file keble-data-infra-api/.env.docker \
+  -f deploy/compose.raw-api.yaml --profile raw-api up --build
+```
+
+`.env`, `.env.docker`, and the BuildKit secret stay outside Git and image
+layers. Set `SENTRY_DSN`, `SENTRY_ENVIRONMENT`, and
+`SENTRY_TRACES_SAMPLE_RATE` in the source env to enable error/performance
+telemetry. Registry discovery, generated operations, cache outcomes, lease
+contention, upstream work, batches, and video ingestion emit structural spans;
+request/response content and credentials are not attached.

keble_data_infra_api-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "keble-data-infra-api"
+version = "0.1.0"
+description = "Sole FastAPI composition root for Keble raw provider data."
+readme = "README.md"
+requires-python = ">=3.13,<3.14"
+dependencies = [
+    "aiohttp>=3,<4",
+    "fastapi>=0.110,<1",
+    "httpx>=0.28,<1",
+    "keble-amz>=2.0.0,<3",
+    "keble-data-infra-contract>=0.1.0,<1",
+    "keble-db>=1.9.0,<2",
+    "keble-helpers>=1.12.2,<2",
+    "keble-keepa>=1.3.0,<2",
+    "keble-tiktok>=0.5.0,<1",
+    "motor>=3,<4",
+    "pymongo>=4.10,<5",
+    "redis>=5,<7",
+    "sentry-sdk>=2,<3",
+    "uvicorn>=0.29,<1",
+]
+
+[[project.authors]]
+name = "zhenhao-ma"
+email = "bob0103779@gmail.com"
+
+[dependency-groups]
+test = [
+    "pytest>=8.2,<9",
+    "pytest-asyncio>=1.4,<2",
+    "httpx>=0.28,<1",
+    "packaging>=24,<27",
+]
+
+[tool.uv]
+default-groups = ["test"]
+
+[tool.uv.sources]
+keble-data-infra-contract = {workspace = true}
+keble-amz = {path = "../../keble-amz"}
+keble-db = {path = "../../../deps/keble-py/keble-db"}
+keble-helpers = {path = "../../../deps/keble-py/keble-helpers"}
+keble-keepa = {path = "../../../deps/keble-keepa"}
+keble-tiktok = {path = "../../keble-tiktok"}
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "unit: fast deterministic tests with no network",
+    "contract: recorded or fixture-based external contract tests",
+    "integration: real local dependency or adapter tests",
+    "live: real external service calls",
+    "slow: slow tests",
+    "db: any real database test",
+    "mongo: MongoDB tests",
+    "redis: Redis tests",
+    "db_stack: multi-database integration tests",
+    "container: tests requiring throwaway containers",
+    "local_stack: tests requiring existing local Keble docker compose stack",
+]

keble_data_infra_api-0.1.0/scripts/__init__.py

@@ -0,0 +1 @@
+"""Developer and release utilities for the raw API distribution."""

keble_data_infra_api-0.1.0/scripts/build_local_docker_env.py

@@ -0,0 +1,78 @@
+"""Create an ignored container-network env from the API's ignored local env."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+from .build_local_env import _read_env
+
+
+def _replace_endpoint(*, value: str, hostname: str, port: int) -> str:
+    """Replace only URI host/port while retaining credentials, path and options."""
+
+    normalized = value.strip().strip("'\"")
+    parsed = urlsplit(normalized)
+    if parsed.hostname is None:
+        raise ValueError("database URI must include a hostname")
+    old_endpoint = (
+        parsed.hostname
+        if parsed.port is None
+        else f"{parsed.hostname}:{parsed.port}"
+    )
+    netloc = parsed.netloc.replace(old_endpoint, f"{hostname}:{port}")
+    return urlunsplit((parsed.scheme, netloc, parsed.path, parsed.query, parsed.fragment))
+
+
+def build_local_docker_env(*, source: Path, output: Path) -> tuple[str, ...]:
+    """Retain provider settings and map DB endpoints to existing Docker aliases.
+
+    Side effects if changes:
+    - `deploy/compose.raw-api.yaml` connects to `keble_default` Mongo/Redis;
+    - URI credentials and query options survive without being printed;
+    - the ignored output must never enter the Docker build context or Git.
+    """
+
+    assignments = _read_env(source)
+    mongo_uri = assignments.get("MONGO_DB_URI")
+    redis_uri = assignments.get("REDIS_URI")
+    if not mongo_uri or not redis_uri:
+        raise ValueError("local API env requires MONGO_DB_URI and REDIS_URI")
+    assignments["DATA_INFRA_MONGO_URI"] = _replace_endpoint(
+        value=mongo_uri,
+        hostname="mongodb",
+        port=27017,
+    )
+    assignments["DATA_INFRA_REDIS_URI"] = _replace_endpoint(
+        value=redis_uri,
+        hostname="redis",
+        port=6379,
+    )
+    output.parent.mkdir(parents=True, exist_ok=True)
+    temporary = output.with_suffix(f"{output.suffix}.tmp")
+    temporary.write_text(
+        "".join(f"{name}={value}\n" for name, value in sorted(assignments.items())),
+        encoding="utf-8",
+    )
+    temporary.replace(output)
+    return tuple(sorted(assignments))
+
+
+def main() -> None:
+    """Build `.env.docker` beside the existing ignored API environment."""
+
+    api_root = Path(__file__).resolve().parents[1]
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--source", type=Path, default=api_root / ".env")
+    parser.add_argument("--output", type=Path, default=api_root / ".env.docker")
+    arguments = parser.parse_args()
+    written = build_local_docker_env(
+        source=arguments.source,
+        output=arguments.output,
+    )
+    print("Wrote Docker settings: " + ", ".join(written))
+
+
+if __name__ == "__main__":
+    main()

keble_data_infra_api-0.1.0/scripts/build_local_env.py

@@ -0,0 +1,134 @@
+"""Build an ignored local API environment from existing Keble provider env files."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+REQUIRED_PROVIDER_KEYS = (
+    "KEEPA_API_TOKEN",
+    "FASTMOSS_BASE_URL",
+    "FASTMOSS_CLIENT_SECRET",
+    "ECHOTIK_BASE_URL",
+    "ECHOTIK_USERNAME",
+    "ECHOTIK_PASSWORD",
+    "MONGO_DB_URI",
+    "REDIS_URI",
+    "SENTRY_DSN",
+    "SENTRY_ENVIRONMENT",
+    "SENTRY_TRACES_SAMPLE_RATE",
+)
+
+
+def _parser(*, umbrella_root: Path) -> argparse.ArgumentParser:
+    """Build explicit source and destination arguments for secret-safe env assembly.
+
+    Side effects if changes:
+    - local Keepa, FastMoss and EchoTik live-test setup;
+    - developer commands documented by ``keble-data-infra-api/README.md``.
+    """
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--backend-env",
+        type=Path,
+        default=umbrella_root / "keble.backend" / ".env",
+    )
+    parser.add_argument(
+        "--tiktok-env",
+        type=Path,
+        default=umbrella_root / "data-infra" / "keble-tiktok" / ".env",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path(__file__).resolve().parents[1] / ".env",
+    )
+    return parser
+
+
+def _read_env(path: Path) -> dict[str, str]:
+    """Read dotenv assignments without evaluating shell syntax or exposing values.
+
+    Side effects if changes:
+    - which existing local settings can enter the generated raw-API environment;
+    - whether quoted provider credentials retain their original dotenv encoding.
+    """
+
+    assignments: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        candidate = line.strip()
+        if not candidate or candidate.startswith("#") or "=" not in candidate:
+            continue
+        name, separator, value = candidate.partition("=")
+        if separator and name.strip() in REQUIRED_PROVIDER_KEYS:
+            assignments[name.strip()] = value.strip()
+    return assignments
+
+
+def _has_value(assignments: dict[str, str], name: str) -> bool:
+    """Report whether one copied dotenv assignment contains a non-empty value."""
+
+    value = assignments.get(name, "").strip()
+    return bool(value.strip("'\""))
+
+
+def build_local_env(*, backend_env: Path, tiktok_env: Path, output: Path) -> tuple[str, ...]:
+    """Copy only named provider settings and enable gates with complete credentials.
+
+    Steps:
+    1. parse the two existing local env files as inert dotenv text;
+    2. select the six provider variables owned by this API;
+    3. enable a live gate only when its complete credential set exists;
+    4. atomically replace the ignored destination and return key names only.
+
+    Side effects if changes:
+    - API-local provider credentials and live-test opt-in gates;
+    - no source env file is modified and no secret value is printed.
+    """
+
+    assignments = {**_read_env(backend_env), **_read_env(tiktok_env)}
+    gates = {
+        "RUN_KEEPA_LIVE": _has_value(assignments, "KEEPA_API_TOKEN"),
+        "RUN_FASTMOSS_LIVE": all(
+            _has_value(assignments, name)
+            for name in ("FASTMOSS_BASE_URL", "FASTMOSS_CLIENT_SECRET")
+        ),
+        "RUN_LIVE_ECHOTIK": all(
+            _has_value(assignments, name)
+            for name in ("ECHOTIK_BASE_URL", "ECHOTIK_USERNAME", "ECHOTIK_PASSWORD")
+        ),
+    }
+    selected = {
+        name: assignments[name]
+        for name in REQUIRED_PROVIDER_KEYS
+        if _has_value(assignments, name)
+    }
+    selected.update({name: "1" for name, enabled in gates.items() if enabled})
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    temporary_output = output.with_suffix(f"{output.suffix}.tmp")
+    temporary_output.write_text(
+        "".join(f"{name}={value}\n" for name, value in sorted(selected.items())),
+        encoding="utf-8",
+    )
+    temporary_output.replace(output)
+    return tuple(sorted(selected))
+
+
+def main() -> None:
+    """Resolve workspace defaults, build the env, and print key names only."""
+
+    umbrella_root = Path(__file__).resolve().parents[4]
+    arguments = _parser(umbrella_root=umbrella_root).parse_args()
+    written_keys = build_local_env(
+        backend_env=arguments.backend_env,
+        tiktok_env=arguments.tiktok_env,
+        output=arguments.output,
+    )
+    print("Wrote provider settings: " + ", ".join(written_keys))
+
+
+if __name__ == "__main__":
+    main()