# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-happens-when-an-instance-treats-gen-ai-usage-input-tokens-as-inclusive-of-cached-tokens-under-opentelemetry-genai-semantic-conventions.md
# Remnant Warrant:    https://corpusfetch.com/c/what-happens-when-an-instance-treats-gen-ai-usage-input-tokens-as-inclusive-of-cached-tokens-under-opentelemetry-genai-semantic-conventions.warrant.json
# Markdown SHA-256:   17e08b59d991ba7aeb6dfbe659f9d9bb5ea32379c03103ded45400928c35664e
# Code AST SHA-256:   473ecd9a248f4457787cef2eee0b9cde845a830bfcd71b64709839dbdd542f80
# Verified Classes:   AccountingMode, AmbiguousUsageError, GenAIUsage
# Defensive Guards:   5 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum


class AccountingMode(Enum):
    CACHE_INCLUSIVE = "inclusive"   # input_tokens includes cache_read tokens
    CACHE_EXCLUSIVE = "exclusive"   # input_tokens is uncached remainder only
    NO_CACHE_REPORTED = "none"      # backend reports no cache breakdown


class AmbiguousUsageError(RuntimeError):
    pass


@dataclass(frozen=True)
class GenAIUsage:
    input_tokens: int
    output_tokens: int
    cache_read_input_tokens: int | None
    mode: AccountingMode
    provider: str

    def new_prompt_tokens(self) -> int:
        if self.mode is AccountingMode.CACHE_INCLUSIVE:
            if self.cache_read_input_tokens is None:
                raise AmbiguousUsageError(
                    f"{self.provider}: inclusive mode requires cache_read_input_tokens"
                )
            if self.cache_read_input_tokens > self.input_tokens:
                raise AmbiguousUsageError(
                    f"{self.provider}: cache_read {self.cache_read_input_tokens} "
                    f"exceeds input_tokens {self.input_tokens}"
                )
            return self.input_tokens - self.cache_read_input_tokens
        if self.mode is AccountingMode.CACHE_EXCLUSIVE:
            if self.cache_read_input_tokens not in (None, 0):
                raise AmbiguousUsageError(
                    f"{self.provider}: exclusive mode must not report cache_read"
                )
            return self.input_tokens
        # NO_CACHE_REPORTED: cannot distinguish miss from unreported hit.
        raise AmbiguousUsageError(
            f"{self.provider}: no cache breakdown; new-prompt count is unknowable"
        )


def emit_usage_span_attributes(usage: GenAIUsage) -> dict[str, int | str]:
    # Validate before emission so the collector never sees an ambiguous record.
    new_tokens = usage.new_prompt_tokens()  # raises AmbiguousUsageError if invalid
    attrs: dict[str, int | str] = {
        "gen_ai.usage.input_tokens": usage.input_tokens,
        "gen_ai.usage.output_tokens": usage.output_tokens,
        "gen_ai.usage.accounting_mode": usage.mode.value,
        "gen_ai.usage.new_prompt_tokens": new_tokens,
        "gen_ai.provider.name": usage.provider,
    }
    if usage.cache_read_input_tokens is not None:
        attrs["gen_ai.usage.cache_read.input_tokens"] = usage.cache_read_input_tokens
    return attrs


def route_by_prompt_cost(spans: list[GenAIUsage]) -> str:
    # Routing must use new_prompt_tokens, never raw input_tokens.
    totals: dict[str, int] = {}
    for u in spans:
        totals[u.provider] = totals.get(u.provider, 0) + u.new_prompt_tokens()
    if not totals:
        raise AmbiguousUsageError("no comparable usage records to route on")
    return min(totals, key=totals.get)
