@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/provider_option_panel.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .architecture import ProviderOptionPresentationPolicy
+
+
+@dataclass(frozen=True)
+class OptionPanelPolicy:
+    presentation: ProviderOptionPresentationPolicy
+    context_strategy: str
+    shows_workflows: bool
+    timeout_default: str
+
+
+@dataclass(frozen=True)
+class OptionPanelText:
+    compact_text: Callable[[Any, int], str]
+    ui_text: Callable[[str, str], str]
+    context_status: Callable[[str, dict[str, Any]], str]
+    applied_preset: Callable[[str, dict[str, Any]], str]
+    preset_text: Callable[[str, str], tuple[str, str]]
+    timeout_status: Callable[[dict[str, Any], str], str]
+
+
+@dataclass(frozen=True)
+class OptionPanelRuntime:
+    router_debug_external: Callable[[], bool]
+    message_preview_chars: Callable[[], int]
+    direct_native: Callable[[str, dict[str, Any]], bool]
+    capability_string: Callable[[str, dict[str, Any], str], str]
+    current_model: Callable[[str, dict[str, Any]], str]
+    workflows_enabled: Callable[[str, dict[str, Any]], bool]
+    ultracode_enabled: Callable[[str, dict[str, Any]], bool]
+
+
+@dataclass(frozen=True)
+class OptionPanelProvider:
+    ollama_options: Callable[[dict[str, Any]], dict[str, Any]]
+    ollama_context_status: Callable[[dict[str, Any]], str]
+    ollama_think_status: Callable[[str, dict[str, Any]], str]
+    query_status: Callable[[str, dict[str, Any]], str]
+    tool_choice_status: Callable[[str, dict[str, Any]], str]
+    rate_limit_status: Callable[[str, dict[str, Any]], str]
+    rate_limit_rpm: Callable[[str, dict[str, Any]], str]
+    ip_family: Callable[[str, dict[str, Any]], str]
+    parse_bool: Callable[..., bool]
+    configured_rate_limit: Callable[[str, dict[str, Any]], int | None]
+
+
+@dataclass(frozen=True)
+class OptionPanelServices:
+    text: OptionPanelText
+    runtime: OptionPanelRuntime
+    provider: OptionPanelProvider
+
+
+@dataclass(frozen=True)
+class OptionValuePolicy:
+    context_strategy: str
+    native_default: bool
+
+
+def build_option_panel_rows(
+    provider: str,
+    config: dict[str, Any],
+    policy: OptionPanelPolicy,
+    services: OptionPanelServices,
+    *,
+    language: str,
+) -> tuple[list[str], list[str]]:
+    text = services.text
+    runtime = services.runtime
+    rows: list[str] = []
+    values: list[str] = []
+
+    def add(label: str, key: str, value: Any) -> None:
+        rows.append(f"{label:<24} [{text.compact_text(value, 56)}]")
+        values.append(key)
+
+    add(text.ui_text("context_setup", language), "context_setup", text.context_status(provider, config))
+    preset = text.applied_preset(provider, config)
+    add(text.ui_text("apply_preset", language), "preset", text.preset_text(preset, language)[0])
+    add(text.ui_text("timeout_preset", language), "timeout_profile", text.timeout_status(config, language))
+    add("Router debug external", "router_debug_external_access", "on" if runtime.router_debug_external() else "off")
+    add("Event message preview", "router_debug_message_preview_chars", runtime.message_preview_chars())
+    if not runtime.direct_native(provider, config) and policy.shows_workflows:
+        model = runtime.current_model(provider, config)
+        capabilities = runtime.capability_string(provider, config, model)
+        add("Claude Code workflows", "workflows_enabled", "on" if runtime.workflows_enabled(provider, config) else "off")
+        add("Claude Code ultracode", "ultracode_enabled", "on" if runtime.ultracode_enabled(provider, config) else "off")
+        add("Claude Code capabilities", "claude_code_supported_capabilities", capabilities or "auto/none")
+    if policy.context_strategy == "ollama":
+        _add_ollama_controls(add, provider, config, services)
+    else:
+        _add_standard_controls(add, provider, config, policy, services)
+    rows.append(text.ui_text("back", language))
+    values.append("back")
+    return rows, values
+
+
+def _add_ollama_controls(
+    add: Callable[[str, str, Any], None],
+    provider: str,
+    config: dict[str, Any],
+    services: OptionPanelServices,
+) -> None:
+    projection = services.provider
+    options = projection.ollama_options(config)
+    add("Context window", "num_ctx", projection.ollama_context_status(config))
+    add("Context min", "num_ctx_min", config.get("num_ctx_min", "default"))
+    add("Context max", "num_ctx_max", config.get("num_ctx_max", "default"))
+    add("Max output tokens", "num_predict", options.get("num_predict", "default"))
+    add("Query string", "force_query_string", projection.query_status(provider, config))
+    add("Tool choice", "supports_tool_choice", projection.tool_choice_status(provider, config))
+    add("Temperature", "temperature", options.get("temperature", "default"))
+    add("Top P", "top_p", options.get("top_p", "default"))
+    add("Top K", "top_k", options.get("top_k", "default"))
+    model = services.runtime.current_model(provider, config)
+    add("Think", "think", projection.ollama_think_status(model, config))
+    add("Keep alive", "keep_alive", config.get("keep_alive", "default"))
+    add("Timeout ms", "request_timeout_ms", config.get("request_timeout_ms", "default"))
+    _add_stream_controls(add, config)
+    add("RPM limiter", "rate_limit_enabled", projection.rate_limit_status(provider, config))
+    add("Rate limit RPM", "rate_limit_rpm", projection.rate_limit_rpm(provider, config))
+    add("Rate limit status", "rate_limit_status", "on" if bool(config.get("rate_limit_status", False)) else "off")
+    add("IP family", "ip_family", projection.ip_family(provider, config))
+
+
+def _add_standard_controls(
+    add: Callable[[str, str, Any], None],
+    provider: str,
+    config: dict[str, Any],
+    policy: OptionPanelPolicy,
+    services: OptionPanelServices,
+) -> None:
+    presentation = policy.presentation
+    projection = services.provider
+    if policy.context_strategy == "standard":
+        add("Context window", "context_window", config.get("context_window", "default"))
+        add("Context reserve", "context_reserve_tokens", config.get("context_reserve_tokens", "default"))
+    add("Max output tokens", "max_output_tokens", config.get("max_output_tokens", "default"))
+    add("Query string", "force_query_string", projection.query_status(provider, config))
+    if presentation.show_tool_choice:
+        add("Tool choice", "supports_tool_choice", projection.tool_choice_status(provider, config))
+    if policy.context_strategy == "standard":
+        add("Timeout ms", "request_timeout_ms", config.get("request_timeout_ms", "default"))
+        if presentation.show_rate_limit_controls:
+            add("RPM limiter", "rate_limit_enabled", projection.rate_limit_status(provider, config))
+            add("Rate limit RPM", "rate_limit_rpm", projection.rate_limit_rpm(provider, config))
+            add("Rate limit status", "rate_limit_status", "on" if bool(config.get("rate_limit_status", False)) else "off")
+        if presentation.show_sampling_controls:
+            for label, key in (("Temperature", "temperature"), ("Top P", "top_p"), ("Top K", "top_k")):
+                add(label, key, config.get(key, "default"))
+        if presentation.show_native:
+            add("Native compatibility", "native_compat", bool(config.get("native_compat", True)))
+        if presentation.show_stream:
+            _add_stream_controls(add, config)
+        if presentation.show_ip_family_control:
+            add("IP family", "ip_family", projection.ip_family(provider, config))
+    elif presentation.show_route:
+        routed = projection.parse_bool(config.get("route_through_router"), default=False)
+        add("Route through router", "route_through_router", "on" if routed else "off")
+        add("Timeout ms", "request_timeout_ms", config.get("request_timeout_ms", policy.timeout_default))
+        if presentation.show_ip_family_control and routed:
+            add("IP family", "ip_family", projection.ip_family(provider, config))
+
+
+def _add_stream_controls(
+    add: Callable[[str, str, Any], None], config: dict[str, Any]
+) -> None:
+    enabled = bool(config.get("stream_enabled", True))
+    add("Stream", "stream_enabled", "on" if enabled else "off")
+    if enabled:
+        add("Stream idle timeout ms", "stream_idle_timeout_ms", config.get("stream_idle_timeout_ms", "auto"))
+        add("Stream word chunking", "stream_word_chunking", "on" if bool(config.get("stream_word_chunking", False)) else "off")
+
+
+def current_option_bool(
+    provider: str,
+    config: dict[str, Any],
+    key: str,
+    policy: OptionValuePolicy,
+    services: OptionPanelServices,
+) -> bool:
+    runtime = services.runtime
+    projection = services.provider
+    if key == "stream_enabled":
+        return bool(config.get("stream_enabled", True))
+    if key == "stream_word_chunking":
+        return bool(config.get("stream_word_chunking", False))
+    if key == "native_compat":
+        return bool(config.get("native_compat", policy.native_default))
+    if key == "think":
+        return bool(config.get("think", False))
+    if key == "rate_limit_enabled":
+        return bool(projection.configured_rate_limit(provider, config))
+    if key == "rate_limit_status":
+        return bool(config.get("rate_limit_status", False))
+    if key == "router_debug_external_access":
+        return runtime.router_debug_external()
+    if key == "route_through_router":
+        return projection.parse_bool(config.get("route_through_router"), default=False)
+    if key == "workflows_enabled":
+        return runtime.workflows_enabled(provider, config)
+    if key == "ultracode_enabled":
+        return runtime.ultracode_enabled(provider, config)
+    return bool(config.get(key, False))
+
+
+def option_prompt_default(
+    provider: str,
+    config: dict[str, Any],
+    key: str,
+    policy: OptionValuePolicy,
+    services: OptionPanelServices,
+) -> str:
+    runtime = services.runtime
+    projection = services.provider
+    boolean_keys = {
+        "router_debug_external_access",
+        "route_through_router",
+        "stream_enabled",
+        "stream_word_chunking",
+        "rate_limit_status",
+        "rate_limit_enabled",
+        "workflows_enabled",
+        "ultracode_enabled",
+    }
+    if key in boolean_keys:
+        return "true" if current_option_bool(provider, config, key, policy, services) else "false"
+    if key == "router_debug_message_preview_chars":
+        return str(runtime.message_preview_chars())
+    if key == "claude_code_supported_capabilities":
+        model = runtime.current_model(provider, config)
+        return runtime.capability_string(provider, config, model)
+    if key == "force_query_string":
+        return str(config.get("force_query_string") or "")
+    if key == "supports_tool_choice":
+        value = config.get("supports_tool_choice")
+        return "auto" if value is None else ("true" if bool(value) else "false")
+    if key == "ip_family":
+        return projection.ip_family(provider, config)
+    if policy.context_strategy == "ollama":
+        options = projection.ollama_options(config)
+        if key == "num_ctx":
+            return str(config.get("num_ctx", "auto"))
+        if key in (
+            "num_ctx_min",
+            "num_ctx_max",
+            "keep_alive",
+            "think",
+            "request_timeout_ms",
+            "stream_idle_timeout_ms",
+        ):
+            return str(config.get(key, ""))
+        if key in options:
+            return str(options[key])
+        return ""
+    value = config.get(key)
+    return "" if value is None else str(value)
+
+
+__all__ = [
+    "OptionPanelPolicy",
+    "OptionPanelProvider",
+    "OptionPanelRuntime",
+    "OptionPanelServices",
+    "OptionPanelText",
+    "OptionValuePolicy",
+    "build_option_panel_rows",
+    "current_option_bool",
+    "option_prompt_default",
+]

package/ciel_runtime_support/provider_option_status.py

@@ -0,0 +1,192 @@
+"""Presentation projection for provider and LLM option status."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+def format_context_tokens(value: int | None) -> str:
+    if not value:
+        return "unknown"
+    if value >= 1024 * 1024 and value % (1024 * 1024) == 0:
+        return f"{value // (1024 * 1024)}M"
+    if value >= 1024 and value % 1024 == 0:
+        return f"{value // 1024}K"
+    return f"{value:,}"
+
+
+def format_parameter_count(
+    value: Any, positive_int: Callable[[Any], int | None]
+) -> str:
+    fixed = positive_int(value)
+    if not fixed:
+        return ""
+    for suffix, scale in (
+        ("T", 1_000_000_000_000),
+        ("B", 1_000_000_000),
+        ("M", 1_000_000),
+    ):
+        if fixed >= scale:
+            scaled = fixed / scale
+            text = f"{scaled:.1f}".rstrip("0").rstrip(".")
+            return f"{text}{suffix}"
+    return str(fixed)
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderContextStatusPorts:
+    capacity: Callable[[str, dict[str, Any]], int | None]
+    context_policy: Callable[..., Any]
+    ollama_num_ctx_status: Callable[[dict[str, Any]], str]
+    positive_int: Callable[[Any], int | None]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderContextStatusProjection:
+    ports: ProviderContextStatusPorts
+
+    def status(self, provider: str, config: dict[str, Any]) -> str:
+        capacity = self.ports.capacity(provider, config)
+        cap_text = format_context_tokens(capacity)
+        strategy = self.ports.context_policy(provider, config).settings_strategy
+        if strategy == "ollama":
+            return f"model max {cap_text}; {self.ports.ollama_num_ctx_status(config)}"
+        if strategy == "standard":
+            window = self.ports.positive_int(config.get("context_window"))
+            reserve = self.ports.positive_int(config.get("context_reserve_tokens"))
+            reserve_text = (
+                f"; reserve {format_context_tokens(reserve)}" if reserve else ""
+            )
+            return (
+                f"model max {cap_text}; window {format_context_tokens(window)}"
+                f"{reserve_text}"
+            )
+        if strategy == "managed":
+            return "managed by Claude Code"
+        return f"model max {cap_text}"
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderOptionStatusPorts:
+    configured_adapter: Callable[..., Any]
+    contract_config: Callable[..., Any]
+    rate_usage: Callable[..., tuple[int, int | None]]
+    ollama_num_ctx: Callable[[dict[str, Any]], str]
+    ollama_options_status: Callable[[dict[str, Any]], str]
+    ip_family: Callable[..., str]
+    parse_bool: Callable[..., bool]
+    tool_choice_status: Callable[..., str]
+    ollama_extra_options: Callable[[dict[str, Any]], dict[str, Any]]
+    anthropic_routed: Callable[..., bool]
+
+
+class ProviderOptionStatusProjection:
+    def __init__(
+        self,
+        sampling_options: tuple[str, ...],
+        ports: ProviderOptionStatusPorts,
+    ) -> None:
+        self.sampling_options = sampling_options
+        self.ports = ports
+
+    def sampling(self, config: dict[str, Any]) -> list[str]:
+        return [
+            f"{key}={config.get(key, 'default')}" for key in self.sampling_options
+        ]
+
+    def provider(self, provider: str, config: dict[str, Any]) -> str:
+        adapter = self.ports.configured_adapter(provider, config)
+        contract = self.ports.contract_config(provider, config)
+        presentation = adapter.option_presentation_policy(contract)
+        context_strategy = adapter.context_policy(contract).settings_strategy
+        timeout = config.get("request_timeout_ms", "default")
+        timeout_text = f"{timeout}ms" if timeout != "default" else "default"
+        parts = [
+            f"max_output_tokens={config.get('max_output_tokens', 'default')}",
+            f"timeout={timeout_text}",
+        ]
+        if config.get("stream_idle_timeout_ms") is not None:
+            parts.append(f"stream_idle_timeout={config['stream_idle_timeout_ms']}ms")
+        if presentation.show_rate_limit:
+            parts.extend(self._rate_limit(provider, config))
+        if context_strategy == "ollama":
+            parts.insert(0, f"num_ctx={self.ports.ollama_num_ctx(config)}")
+            parts.append(
+                f"ollama_options={self.ports.ollama_options_status(config)}"
+            )
+        if context_strategy == "standard":
+            parts.insert(0, f"context_window={config.get('context_window', 'default')}")
+            parts.insert(
+                1, f"reserve={config.get('context_reserve_tokens', 'default')}"
+            )
+        if presentation.show_native:
+            parts.append(f"native={bool(config.get('native_compat', True))}")
+        if presentation.show_ip_family:
+            overrides = config.get("model_endpoints")
+            parts.append(f"ip_family={self.ports.ip_family(provider, config)}")
+            parts.append(
+                f"endpoint_overrides={len(overrides) if isinstance(overrides, dict) else 0}"
+            )
+        if presentation.show_route:
+            routed = self.ports.parse_bool(
+                config.get("route_through_router"), default=False
+            )
+            parts.append(f"routed={'on' if routed else 'off'}")
+        elif presentation.show_tool_choice:
+            parts.append(
+                f"tool_choice={self.ports.tool_choice_status(provider, config)}"
+            )
+        query = str(config.get("force_query_string") or "").strip()
+        if query:
+            parts.append(f"query={query}")
+        if presentation.show_sampling:
+            parts.extend(self.sampling(config))
+        if presentation.show_stream:
+            parts.append(
+                f"stream={'on' if bool(config.get('stream_enabled', True)) else 'off'}"
+            )
+            if bool(config.get("stream_word_chunking", False)):
+                parts.append("word_chunk=on")
+        return ", ".join(parts)
+
+    def _rate_limit(self, provider: str, config: dict[str, Any]) -> list[str]:
+        parts = [f"rate_limit_rpm={config.get('rate_limit_rpm', 0)}"]
+        if bool(config.get("rate_limit_status", False)):
+            used, limit = self.ports.rate_usage(provider, config)
+            if limit is not None:
+                suffix = f"{used}/{limit}" if limit > 0 else f"{used}/min(unmanaged)"
+                parts.append(f"rpm_used={suffix}")
+        return parts
+
+    def llm(self, provider: str, config: dict[str, Any]) -> str:
+        adapter = self.ports.configured_adapter(provider, config)
+        contract = self.ports.contract_config(provider, config)
+        presentation = adapter.option_presentation_policy(contract)
+        if adapter.context_policy(contract).settings_strategy == "ollama":
+            options = self.ports.ollama_extra_options(config)
+            pieces = [
+                f"ctx {self.ports.ollama_num_ctx(config)}",
+                f"keep {config.get('keep_alive', 'default')}",
+                f"think {bool(config.get('think', False))}",
+                f"timeout {config.get('request_timeout_ms', 'default')}ms",
+            ]
+            if config.get("stream_idle_timeout_ms") is not None:
+                pieces.append(
+                    f"stream_idle_timeout={config['stream_idle_timeout_ms']}ms"
+                )
+            for key in ("num_predict", "temperature", "top_p", "top_k"):
+                if key in options:
+                    pieces.append(f"{key}={options[key]}")
+            return "; ".join(pieces)
+        owns_model = adapter.configuration_policy(contract).runtime_owns_model
+        if presentation.show_route and not owns_model:
+            return (
+                f"max_output_tokens={config.get('max_output_tokens', 'Claude Code default')}, "
+                f"timeout={config.get('request_timeout_ms', 'Claude Code default')}ms, "
+                f"routed={'on' if self.ports.anthropic_routed(provider, config) else 'off'}"
+            )
+        if presentation.show_tool_choice or presentation.show_route:
+            return self.provider(provider, config)
+        return "provider defaults"

package/ciel_runtime_support/provider_policy.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderWireServices:
+    normalize_model_id: Callable[..., Any]
+    openai_chat_reasoning_passback_enabled_for_body: Callable[..., Any]
+    preserves_anthropic_thinking_contract: Callable[..., Any]
+    provider_supports_tool_choice: Callable[..., Any]
+    resolve_requested_model: Callable[..., Any]
+    select_provider_protocol: Callable[..., Any]
+
+
+def resolve_provider_wire_profile(provider: str, pcfg: dict[str, Any], body: dict[str, Any] | None = None,
+    *,
+    services: ProviderWireServices,
+) -> dict[str, str]:
+    """Return the active provider/base-url wire profile for this request.
+
+    The same model id can travel through different protocol adapters depending
+    on provider and base URL. Keep this provider-scoped; model metadata only
+    supplies limits and hints.
+    """
+
+    normalize_model_id = services.normalize_model_id
+    openai_chat_reasoning_passback_enabled_for_body = services.openai_chat_reasoning_passback_enabled_for_body
+    preserves_anthropic_thinking_contract = services.preserves_anthropic_thinking_contract
+    provider_supports_tool_choice = services.provider_supports_tool_choice
+    resolve_requested_model = services.resolve_requested_model
+    select_provider_protocol = services.select_provider_protocol
+    request_model = str((body or {}).get("model") or pcfg.get("current_model") or "")
+    try:
+        model = resolve_requested_model(provider, pcfg, request_model)
+    except Exception:
+        model = normalize_model_id(provider, request_model)
+
+    selected_protocol = select_provider_protocol(provider, pcfg, "anthropic_messages", model)
+    upstream_format = str(selected_protocol).replace("_", "-")
+    endpoint_family = upstream_format
+
+    if preserves_anthropic_thinking_contract(provider, pcfg):
+        thinking_policy = "preserve"
+    elif (
+        upstream_format == "openai-chat"
+        and body is not None
+        and openai_chat_reasoning_passback_enabled_for_body(provider, pcfg, body)
+    ):
+        thinking_policy = "openai-reasoning-passback"
+    else:
+        thinking_policy = "strip"
+
+    return {
+        "provider": provider,
+        "model": model,
+        "endpoint_family": endpoint_family,
+        "upstream_format": upstream_format,
+        "thinking_policy": thinking_policy,
+        "tool_choice_policy": "forward" if provider_supports_tool_choice(provider, pcfg, body or {}) else "strip",
+        "metadata_policy": "strip-internal-upstream-only",
+    }
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderRequestServices:
+    apply_provider_adapter_request_policy: Callable[..., Any]
+    normalize_anthropic_system_role_messages: Callable[..., Any]
+    normalize_anthropic_tool_turns_for_provider: Callable[..., Any]
+    normalize_thinking_for_non_anthropic_provider: Callable[..., Any]
+    normalize_tool_choice_for_provider: Callable[..., Any]
+    provider_wire_profile: Callable[..., Any]
+    sanitize_assistant_pseudo_tool_text_history: Callable[..., Any]
+
+
+def normalize_provider_request(provider: str, pcfg: dict[str, Any], body: dict[str, Any],
+    *,
+    services: ProviderRequestServices,
+) -> dict[str, Any]:
+    """Normalize a Claude Code /v1/messages request for the active provider wire profile."""
+
+    apply_provider_adapter_request_policy = services.apply_provider_adapter_request_policy
+    normalize_anthropic_system_role_messages = services.normalize_anthropic_system_role_messages
+    normalize_anthropic_tool_turns_for_provider = services.normalize_anthropic_tool_turns_for_provider
+    normalize_thinking_for_non_anthropic_provider = services.normalize_thinking_for_non_anthropic_provider
+    normalize_tool_choice_for_provider = services.normalize_tool_choice_for_provider
+    provider_wire_profile = services.provider_wire_profile
+    sanitize_assistant_pseudo_tool_text_history = services.sanitize_assistant_pseudo_tool_text_history
+    profile = provider_wire_profile(provider, pcfg, body)
+    out = normalize_thinking_for_non_anthropic_provider(provider, pcfg, body)
+    out = apply_provider_adapter_request_policy(provider, pcfg, out)
+    out = normalize_tool_choice_for_provider(provider, pcfg, out)
+    out = sanitize_assistant_pseudo_tool_text_history(out)
+    out = normalize_anthropic_tool_turns_for_provider(provider, pcfg, out)
+    if profile.get("upstream_format") == "anthropic-messages":
+        out = normalize_anthropic_system_role_messages(out)
+    return out
+
+
+__all__ = ["ProviderRequestServices", "ProviderWireServices", "normalize_provider_request", "resolve_provider_wire_profile"]

package/ciel_runtime_support/provider_query_policy.py

@@ -0,0 +1,67 @@
+"""Provider-aware upstream query-string projection policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+from urllib.parse import parse_qs, urlparse
+
+
+ProviderConfig = dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderQueryPolicy:
+    normalize_provider: Callable[[str], str]
+    propagates_inbound_beta: Callable[[str, ProviderConfig], bool]
+
+    @staticmethod
+    def inbound_has_beta(request_path: str) -> bool:
+        query = urlparse(request_path).query
+        return any(
+            value.strip().lower() in {"true", "1"}
+            for value in parse_qs(query).get("beta", ())
+        )
+
+    def upstream_query(
+        self,
+        config: ProviderConfig,
+        request_path: str,
+        provider: str | None = None,
+    ) -> str:
+        forced = self._forced_query(config)
+        if forced:
+            return forced
+        provider_name = str(
+            provider or config.get("provider") or ""
+        ).strip()
+        if not provider_name:
+            return ""
+        provider_key = self.normalize_provider(provider_name)
+        if (
+            self.propagates_inbound_beta(provider_key, config)
+            and self.inbound_has_beta(request_path)
+        ):
+            return "beta=true"
+        return ""
+
+    def status(self, provider: str, config: ProviderConfig) -> str:
+        forced = self._forced_query(config)
+        if forced:
+            return forced
+        provider_key = self.normalize_provider(str(provider))
+        if self.propagates_inbound_beta(provider_key, config):
+            return "auto (beta=true when routed)"
+        return "empty"
+
+    @staticmethod
+    def _forced_query(config: ProviderConfig) -> str:
+        return (
+            str(config.get("force_query_string") or "")
+            .strip()
+            .lstrip("?")
+            .strip()
+        )
+
+
+__all__ = ["ProviderQueryPolicy"]