unique-search-proxy 2026.28.0.dev0__tar.gz → 2026.28.0.dev2__tar.gz

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-search-proxy
-Version: 2026.28.0.dev0
+Version: 2026.28.0.dev2
 Summary: Web Search Proxy implementation
 Author: ThePhilAz
 Author-email: ThePhilAz <rami.azouz@philico.com>
@@ -18,8 +18,9 @@ Requires-Dist: azure-core>=1.36.0,<2
 Requires-Dist: certifi>=2025.11.12,<2027
 Requires-Dist: google-genai>=1.73.0,<2
 Requires-Dist: google-auth>=2.43.0,<3
-Requires-Dist: unique-toolkit[monitoring]>=2026.28.0.dev0,<2026.28.0rc0
-Requires-Dist: unique-search-proxy-core>=2026.28.0.dev0,<2026.28.0rc0
+Requires-Dist: jinja2>=3.1.6,<4
+Requires-Dist: unique-toolkit[monitoring]>=2026.28.0.dev3,<2026.28.0rc0
+Requires-Dist: unique-search-proxy-core>=2026.28.0.dev1,<2026.28.0rc0
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique-search-proxy"
-version = "2026.28.0.dev0"
+version = "2026.28.0.dev2"
 description = "Web Search Proxy implementation"
 authors = [{ name = "ThePhilAz", email = "rami.azouz@philico.com" }]
 readme = "README.md"
@@ -20,8 +20,9 @@ dependencies = [
     "certifi>=2025.11.12,<2027",
     "google-genai>=1.73.0,<2",
     "google-auth>=2.43.0,<3",
-    "unique-toolkit[monitoring]>=2026.28.0.dev0,<2026.28.0rc0",
-    "unique-search-proxy-core>=2026.28.0.dev0,<2026.28.0rc0",
+    "jinja2>=3.1.6,<4",
+    "unique-toolkit[monitoring]>=2026.28.0.dev3,<2026.28.0rc0",
+    "unique-search-proxy-core>=2026.28.0.dev1,<2026.28.0rc0",
 ]
 
 [dependency-groups]
@@ -77,6 +78,8 @@ DEP003 = ["unique_toolkit", "unique_search_proxy_core"]
 
 [tool.poe.tasks]
 generate-sdk = "python scripts/generate_sdk.py"
+generate-helm-config = "python scripts/generate_helm_config.py"
+render-helm-fixtures = "bash scripts/render_helm_fixtures.sh"
 lint = "ruff check ."
 lint-fix = "ruff check . --fix"
 format = "ruff format ."

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/unique_search_proxy_client/web/app.py

@@ -18,7 +18,7 @@ from unique_search_proxy_client.web.logging_config import (
     configure_logging,
 )
 from unique_search_proxy_client.web.monitoring import setup_prometheus
-from unique_search_proxy_client.web.settings.startup_report import (
+from unique_search_proxy_client.web.startup_report import (
     log_startup_settings_report,
 )
 

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/unique_search_proxy_client/web/core/agent_engines/bing/client.py

@@ -8,10 +8,10 @@ from azure.core.credentials_async import AsyncTokenCredential
 from azure.core.pipeline.transport import AsyncioRequestsTransport
 from azure.identity.aio import DefaultAzureCredential, WorkloadIdentityCredential
 
-from unique_search_proxy_client.web.settings.providers.base import NOT_PROVIDED
 from unique_search_proxy_client.web.settings.providers.bing_agent import (
     bing_agent_credentials,
 )
+from unique_search_proxy_client.web.settings.secret_str import NOT_PROVIDED
 
 _LOGGER = logging.getLogger(__name__)
 

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/unique_search_proxy_client/web/core/agent_engines/vertexai/client.py

@@ -8,16 +8,24 @@ from google.auth import load_credentials_from_dict
 from google.genai._api_client import BaseApiClient
 from google.genai.client import AsyncClient
 
-from unique_search_proxy_client.web.settings.providers.base import read_secret
 from unique_search_proxy_client.web.settings.providers.vertexai_agent import (
     vertexai_agent_credentials,
 )
+from unique_search_proxy_client.web.settings.secret_str import (
+    is_secret_configured,
+    read_secret,
+)
 
 _LOGGER = logging.getLogger(__name__)
 
 
 def _get_base_api_client_from_service_account() -> BaseApiClient:
-    assert vertexai_agent_credentials.service_account_credentials is not None
+    if not is_secret_configured(vertexai_agent_credentials.service_account_credentials):
+        msg = (
+            "VERTEXAI_AGENT_CREDENTIAL_TYPE is 'service_account' but "
+            "VERTEXAI_AGENT_SERVICE_ACCOUNT_CREDENTIALS is not set."
+        )
+        raise ValueError(msg)
 
     scopes = vertexai_agent_credentials.service_account_scopes or [
         "https://www.googleapis.com/auth/cloud-platform",
@@ -43,11 +51,11 @@ def _get_base_api_client_from_adc() -> BaseApiClient:
 
 
 def get_vertex_client() -> AsyncClient:
-    if vertexai_agent_credentials.service_account_credentials is not None:
+    if vertexai_agent_credentials.credential_type == "service_account":
         _LOGGER.info("Using explicit service account credentials for VertexAI agent")
         base_api_client = _get_base_api_client_from_service_account()
     else:
-        _LOGGER.info("Using ADC for VertexAI agent")
+        _LOGGER.info("Using workload identity (ADC) for VertexAI agent")
         base_api_client = _get_base_api_client_from_adc()
     return AsyncClient(api_client=base_api_client)
 

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/unique_search_proxy_client/web/core/client/service.py

@@ -14,8 +14,10 @@ from unique_search_proxy_client.web.settings.client import (
     ProxyConfig,
     http_client_settings,
 )
-from unique_search_proxy_client.web.settings.providers.base import read_secret
-from unique_search_proxy_client.web.settings.secret_str import read_secret_headers
+from unique_search_proxy_client.web.settings.secret_str import (
+    read_secret,
+    read_secret_headers,
+)
 
 if TYPE_CHECKING:
     from fastapi import FastAPI

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/unique_search_proxy_client/web/core/crawlers/firecrawl/service.py

@@ -25,10 +25,10 @@ from unique_search_proxy_client.web.core.provider_response import (
     upstream_error_message,
     upstream_response_raw,
 )
-from unique_search_proxy_client.web.settings.providers.base import read_secret
 from unique_search_proxy_client.web.settings.providers.firecrawl import (
     firecrawl_crawl_credentials as credentials,
 )
+from unique_search_proxy_client.web.settings.secret_str import read_secret
 from unique_search_proxy_client.web.utils.url import join_url_path
 
 _LOGGER = logging.getLogger(__name__)

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/unique_search_proxy_client/web/core/crawlers/jina/service.py

@@ -18,10 +18,10 @@ from unique_search_proxy_client.web.core.provider_response import (
     transport_error_raw,
     upstream_response_raw,
 )
-from unique_search_proxy_client.web.settings.providers.base import read_secret
 from unique_search_proxy_client.web.settings.providers.jina import (
     jina_crawl_credentials as credentials,
 )
+from unique_search_proxy_client.web.settings.secret_str import read_secret
 
 _LOGGER = logging.getLogger(__name__)
 

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/unique_search_proxy_client/web/core/crawlers/tavily/service.py

@@ -19,10 +19,10 @@ from unique_search_proxy_client.web.core.provider_response import (
     upstream_error_message,
     upstream_response_raw,
 )
-from unique_search_proxy_client.web.settings.providers.base import read_secret
 from unique_search_proxy_client.web.settings.providers.tavily import (
     tavily_crawl_credentials as credentials,
 )
+from unique_search_proxy_client.web.settings.secret_str import read_secret
 
 _LOGGER = logging.getLogger(__name__)
 

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/unique_search_proxy_client/web/core/search_engines/brave/service.py

@@ -37,10 +37,10 @@ from unique_search_proxy_client.web.core.search_engines.pagination import PageRe
 from unique_search_proxy_client.web.core.search_engines.service_base import (
     SearchEngineService,
 )
-from unique_search_proxy_client.web.settings.providers.base import read_secret
 from unique_search_proxy_client.web.settings.providers.brave import (
     brave_search_credentials as credentials,
 )
+from unique_search_proxy_client.web.settings.secret_str import read_secret
 
 _LOGGER = logging.getLogger(__name__)
 _BRAVE_PROVIDER_LABEL = "Brave Web Search API"

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/unique_search_proxy_client/web/core/search_engines/google/service.py

@@ -37,10 +37,10 @@ from unique_search_proxy_client.web.core.search_engines.pagination import PageRe
 from unique_search_proxy_client.web.core.search_engines.service_base import (
     SearchEngineService,
 )
-from unique_search_proxy_client.web.settings.providers.base import read_secret
 from unique_search_proxy_client.web.settings.providers.google import (
     google_search_credentials as credentials,
 )
+from unique_search_proxy_client.web.settings.secret_str import read_secret
 
 _GOOGLE_PROVIDER_LABEL = "Google Custom Search API"
 

{unique_search_proxy-2026.28.0.dev0 → unique_search_proxy-2026.28.0.dev2}/unique_search_proxy_client/web/core/search_engines/perplexity/service.py

@@ -36,7 +36,7 @@ from unique_search_proxy_client.web.core.search_engines.service_base import (
 from unique_search_proxy_client.web.settings.providers import (
     perplexity_search_credentials as credentials,
 )
-from unique_search_proxy_client.web.settings.providers.base import read_secret
+from unique_search_proxy_client.web.settings.secret_str import read_secret
 
 _LOGGER = logging.getLogger(__name__)
 _PERPLEXITY_PROVIDER_LABEL = "Perplexity Search API"

unique_search_proxy-2026.28.0.dev2/unique_search_proxy_client/web/helm/__init__.py

@@ -0,0 +1 @@
+"""Helm chart metadata, registry, and artifact generation for the search proxy."""

unique_search_proxy-2026.28.0.dev2/unique_search_proxy_client/web/helm/generator/__init__.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from unique_search_proxy_client.web.helm.generator.schema import (
+    render_additional_schema,
+)
+from unique_search_proxy_client.web.helm.generator.template import (
+    render_generated_template,
+)
+from unique_search_proxy_client.web.helm.generator.values_yaml import (
+    patch_values_yaml,
+)
+from unique_search_proxy_client.web.helm.registry import (
+    HelmSettingsGroup,
+    helm_generated_groups,
+)
+
+
+def chart_paths(chart_dir: Path) -> dict[str, Path]:
+    return {
+        "additional_schema": chart_dir / "values.additional.schema.json",
+        "generated_tpl": chart_dir / "templates" / "_generated.tpl",
+        "values_yaml": chart_dir / "values.yaml",
+    }
+
+
+def generated_groups_tuple() -> tuple[HelmSettingsGroup, ...]:
+    return tuple(helm_generated_groups())
+
+
+def generate_artifacts(chart_dir: Path) -> dict[str, str]:
+    groups = generated_groups_tuple()
+    paths = chart_paths(chart_dir)
+    values_text = paths["values_yaml"].read_text(encoding="utf-8")
+
+    outputs = {
+        str(paths["additional_schema"]): render_additional_schema(groups),
+        str(paths["generated_tpl"]): render_generated_template(groups),
+        str(paths["values_yaml"]): patch_values_yaml(values_text, groups),
+    }
+    return outputs
+
+
+def write_artifacts(chart_dir: Path) -> dict[str, Path]:
+    outputs = generate_artifacts(chart_dir)
+    written: dict[str, Path] = {}
+    for path_str, content in outputs.items():
+        path = Path(path_str)
+        path.write_text(content, encoding="utf-8")
+        written[path.name] = path
+    return written
+
+
+def check_artifacts(chart_dir: Path) -> list[str]:
+    drift: list[str] = []
+    outputs = generate_artifacts(chart_dir)
+    for path_str, expected in outputs.items():
+        path = Path(path_str)
+        if not path.exists():
+            drift.append(f"missing -> {path}")
+            continue
+        actual = path.read_text(encoding="utf-8")
+        if actual != expected:
+            drift.append(f"drift -> {path}")
+    # Files emitted by earlier generator versions; flag them so they are removed
+    # rather than silently shadowing the current output. (_google.tpl predates the
+    # consolidated template; _providers.tpl was renamed to _generated.tpl.)
+    for stale_name in ("_google.tpl", "_providers.tpl"):
+        stale = chart_dir / "templates" / stale_name
+        if stale.exists():
+            drift.append(f"stale file should be removed -> {stale}")
+    return drift

unique_search_proxy-2026.28.0.dev2/unique_search_proxy_client/web/helm/generator/introspect.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Literal, cast, get_args, get_origin
+
+from pydantic import SecretStr
+from pydantic.fields import FieldInfo
+
+from unique_search_proxy_client.web.settings.secret_str import (
+    NOT_PROVIDED,
+    LogSecretStr,
+    field_has_not_provided_default,
+)
+
+_URI_DEFAULT_RE = re.compile(r"^https?://", re.IGNORECASE)
+
+DEFAULT_HELM_SECTION = "connection"
+
+
+def snake_to_camel(name: str) -> str:
+    parts = name.split("_")
+    return parts[0] + "".join(part.capitalize() for part in parts[1:])
+
+
+def env_var_name(field_name: str, env_prefix: str) -> str:
+    return f"{env_prefix}{field_name.upper()}"
+
+
+def _helm_extra(field_info: FieldInfo) -> dict[str, Any]:
+    extra = field_info.json_schema_extra
+    if isinstance(extra, dict):
+        helm = extra.get("helm")
+        if isinstance(helm, dict):
+            return helm
+    return {}
+
+
+def _unwrap_annotation(annotation: Any) -> Any:
+    origin = get_origin(annotation)
+    if origin is None:
+        return annotation
+    args = get_args(annotation)
+    non_none = [arg for arg in args if arg is not type(None)]
+    if len(non_none) == 1:
+        return non_none[0]
+    return annotation
+
+
+def _is_secret_type(annotation: Any) -> bool:
+    inner = _unwrap_annotation(annotation)
+    return inner in {SecretStr, LogSecretStr}
+
+
+def _is_scalar_type(annotation: Any) -> bool:
+    origin = get_origin(annotation)
+    if origin is Literal:
+        return True
+    inner = _unwrap_annotation(annotation)
+    if inner in {str, int, float, bool}:
+        return True
+    if isinstance(inner, type) and issubclass(inner, str):
+        return True
+    return False
+
+
+def _is_list_str_type(annotation: Any) -> bool:
+    origin = get_origin(annotation)
+    if origin is not list:
+        return False
+    args = get_args(annotation)
+    if not args:
+        return False
+    inner = args[0]
+    return inner is str or (isinstance(inner, type) and issubclass(inner, str))
+
+
+def _factory_takes_validated_data(factory: Callable[..., Any]) -> bool:
+    try:
+        params = inspect.signature(factory).parameters
+    except (TypeError, ValueError):
+        return False
+    return any(
+        p.kind
+        in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.VAR_POSITIONAL,
+        )
+        for p in params.values()
+    )
+
+
+def _default_value(field_info: FieldInfo) -> Any:
+    factory = field_info.default_factory
+    if factory is not None:
+        factory = cast(Callable[..., Any], factory)
+        try:
+            if _factory_takes_validated_data(factory):
+                return factory({})
+            return factory()
+        except TypeError:
+            return None
+    return field_info.default
+
+
+def _default_is_uri(default: Any) -> bool:
+    return isinstance(default, str) and bool(_URI_DEFAULT_RE.match(default))
+
+
+@dataclass(frozen=True)
+class HelmFieldSpec:
+    """One Helm-mapped field derived from a Pydantic model field."""
+
+    python_name: str
+    helm_name: str
+    env_var: str
+    sensitive: bool
+    required_when_enabled: bool
+    schema_ref: str | None
+    plain_type: str | None
+    format_uri: bool
+    default: Any
+    section: str
+    block_level: bool
+    container: bool
+    overridable: bool
+    emit_in_template: bool
+    emit_in_values: bool
+
+
+def _schema_ref_for_field(
+    *,
+    field_info: FieldInfo,
+    sensitive: bool,
+    default: Any,
+    helm_extra: dict[str, Any],
+) -> tuple[str | None, str | None]:
+    override = helm_extra.get("value_source")
+    if isinstance(override, str):
+        return f"#/$defs/valueSource{override}", None
+
+    if sensitive:
+        return "#/$defs/valueSourceSensitive", None
+
+    inner = _unwrap_annotation(field_info.annotation)
+    if inner is bool:
+        return "#/$defs/valueSourceBoolean", None
+    if inner is int:
+        return "#/$defs/valueSourceInteger", None
+    if inner is float:
+        return None, "number"
+    if _default_is_uri(default):
+        return None, "string"
+    if inner is str or (isinstance(inner, type) and issubclass(inner, str)):
+        return "#/$defs/valueSourceString", None
+    return "#/$defs/valueSourceString", None
+
+
+def iter_helm_fields(
+    model: type[Any],
+    *,
+    env_prefix: str,
+) -> tuple[HelmFieldSpec, ...]:
+    specs: list[HelmFieldSpec] = []
+    for field_name, field_info in model.model_fields.items():
+        helm_extra = _helm_extra(field_info)
+        if helm_extra.get("skip"):
+            continue
+
+        annotation = field_info.annotation
+        origin = get_origin(annotation)
+        container = False
+        if origin is dict:
+            continue
+        if origin is list:
+            if not _is_list_str_type(annotation):
+                continue
+            container = True
+        elif not _is_scalar_type(annotation) and not _is_secret_type(annotation):
+            continue
+
+        default = _default_value(field_info)
+        sensitive = bool(helm_extra.get("sensitive")) or _is_secret_type(annotation)
+        required_when_enabled = bool(
+            helm_extra.get("required_when_enabled")
+        ) or field_has_not_provided_default(field_info)
+        schema_ref, plain_type = _connection_property_types(
+            field_info=field_info,
+            sensitive=sensitive,
+            default=default,
+            helm_extra=helm_extra,
+            container=container,
+        )
+        helm_name = str(helm_extra.get("helm_name", snake_to_camel(field_name)))
+        section = str(helm_extra.get("section", DEFAULT_HELM_SECTION))
+        block_level = bool(helm_extra.get("block_level"))
+        overridable = bool(helm_extra.get("overridable"))
+        spec = HelmFieldSpec(
+            python_name=field_name,
+            helm_name=helm_name,
+            env_var=env_var_name(field_name, env_prefix),
+            sensitive=sensitive,
+            required_when_enabled=required_when_enabled,
+            schema_ref=schema_ref,
+            plain_type=plain_type,
+            format_uri=_default_is_uri(default),
+            default=default,
+            section=section,
+            block_level=block_level,
+            container=container,
+            overridable=overridable,
+            emit_in_template=False,
+            emit_in_values=True,
+        )
+        specs.append(
+            HelmFieldSpec(
+                python_name=spec.python_name,
+                helm_name=spec.helm_name,
+                env_var=spec.env_var,
+                sensitive=spec.sensitive,
+                required_when_enabled=spec.required_when_enabled,
+                schema_ref=spec.schema_ref,
+                plain_type=spec.plain_type,
+                format_uri=spec.format_uri,
+                default=spec.default,
+                section=spec.section,
+                block_level=spec.block_level,
+                container=spec.container,
+                overridable=spec.overridable,
+                emit_in_template=_should_emit_in_template(spec),
+                emit_in_values=spec.emit_in_values,
+            )
+        )
+    return tuple(specs)
+
+
+def _connection_property_types(
+    *,
+    field_info: FieldInfo,
+    sensitive: bool,
+    default: Any,
+    helm_extra: dict[str, Any],
+    container: bool,
+) -> tuple[str | None, str | None]:
+    if container:
+        return None, None
+    return _schema_ref_for_field(
+        field_info=field_info,
+        sensitive=sensitive,
+        default=default,
+        helm_extra=helm_extra,
+    )
+
+
+def _should_emit_in_template(field: HelmFieldSpec) -> bool:
+    if field.container:
+        # Lists are documentation-only unless explicitly marked overridable, in
+        # which case they are injected (JSON-encoded) so overlays can set them.
+        return field.overridable
+    if field.required_when_enabled or field.sensitive:
+        return True
+    # Optional fields default to ``None`` (no literal in values.yaml) but are
+    # still settable via overlays, so they must be emitted — guarded so the env
+    # var only renders when the overlay actually provides a value.
+    return field.default is not NOT_PROVIDED
+
+
+def literal_default_for_values(field: HelmFieldSpec) -> str | int | float | bool | None:
+    if field.container:
+        return None
+    if field.sensitive or field.required_when_enabled:
+        return None
+    default = field.default
+    if isinstance(default, SecretStr):
+        default = default.get_secret_value()
+    if default is NOT_PROVIDED:
+        return None
+    if default is None:
+        return None
+    if isinstance(default, (str, int, float, bool)):
+        return default
+    return str(default)
+
+
+def container_default_items(field: HelmFieldSpec) -> tuple[str, ...] | None:
+    if not field.container:
+        return None
+    default = field.default
+    if not isinstance(default, list):
+        return None
+    return tuple(str(item) for item in default)
+
+
+def group_fields_by_section(
+    fields: tuple[HelmFieldSpec, ...],
+) -> tuple[tuple[str, tuple[HelmFieldSpec, ...]], ...]:
+    """Group fields by section; ``connection`` first, then declaration order."""
+    by_section: dict[str, list[HelmFieldSpec]] = {}
+    section_order: list[str] = []
+    for field in fields:
+        if field.block_level:
+            continue
+        if field.section not in by_section:
+            by_section[field.section] = []
+            section_order.append(field.section)
+        by_section[field.section].append(field)
+
+    ordered_names: list[str] = []
+    if DEFAULT_HELM_SECTION in by_section:
+        ordered_names.append(DEFAULT_HELM_SECTION)
+    for name in section_order:
+        if name != DEFAULT_HELM_SECTION:
+            ordered_names.append(name)
+
+    return tuple((name, tuple(by_section[name])) for name in ordered_names)
+
+
+def block_level_fields(
+    fields: tuple[HelmFieldSpec, ...],
+) -> tuple[HelmFieldSpec, ...]:
+    return tuple(field for field in fields if field.block_level)