"""Minimal UVOX OpenAI connection helper with selectable engine mode.

UVOX internal routing algorithms remain proprietary. Supported public modes:
``auto``, ``maximum_savings``, ``zero_loss_cache`` and ``disabled``.
"""
from __future__ import annotations

from typing import Literal

from openai import OpenAI

UvoxMode = Literal["auto", "maximum_savings", "zero_loss_cache", "disabled"]
_VALID_MODES = {"auto", "maximum_savings", "zero_loss_cache", "disabled"}


def uvox_openai_client(
    uvox_key: str,
    base_url: str = "https://api.uvox.tech/openai/v1",
    mode: UvoxMode = "zero_loss_cache",
) -> OpenAI:
    """Create an OpenAI client routed through UVOX.

    Existing accounts default to ``zero_loss_cache``. Combined modes require
    beta access on the tenant and otherwise fall back to Zero-Loss Cache.
    """
    if not uvox_key or not uvox_key.startswith("uvx_live_"):
        raise ValueError("A valid UVOX gateway key is required")
    if mode not in _VALID_MODES:
        raise ValueError(f"Unsupported UVOX mode: {mode}")
    return OpenAI(
        api_key=uvox_key,
        base_url=base_url.rstrip("/"),
        default_headers={"X-UVOX-Mode": mode},
    )