Cost Control and Observability in Innova AI Engine

class TokenUsage(BaseModel):
    """SDK-agnostic token tally for one or more LLM calls."""

    input_tokens: int = 0
    output_tokens: int = 0
    cache_creation_input_tokens: int = 0  # tokens paid to write an ephemeral cache block
    cache_read_input_tokens: int = 0       # tokens served from cache (discounted)

    def __add__(self, other: TokenUsage) -> TokenUsage:
        return TokenUsage(
            input_tokens=self.input_tokens + other.input_tokens,
            output_tokens=self.output_tokens + other.output_tokens,
            cache_creation_input_tokens=(
                self.cache_creation_input_tokens + other.cache_creation_input_tokens
            ),
            cache_read_input_tokens=(
                self.cache_read_input_tokens + other.cache_read_input_tokens
            ),
        )

    @property
    def total_input_tokens(self) -> int:
        """All input billed: fresh + cache-write (seeding) + cache-read (hits)."""
        return self.input_tokens + self.cache_creation_input_tokens + self.cache_read_input_tokens

    @property
    def cache_hit_rate(self) -> float:
        """Share of input tokens served from cache (0..1); 0 when there is no input."""
        denom = self.total_input_tokens
        return self.cache_read_input_tokens / denom if denom else 0.0

def usage_from_response(usage: Usage) -> TokenUsage:
    """Map an Anthropic `Usage` (cache fields are Optional) into our `TokenUsage`."""
    return TokenUsage(
        input_tokens=usage.input_tokens,
        output_tokens=usage.output_tokens,
        cache_creation_input_tokens=usage.cache_creation_input_tokens or 0,
        cache_read_input_tokens=usage.cache_read_input_tokens or 0,
    )

def cost_usd(usage: TokenUsage, model: str) -> float:
    """Compute the USD cost of `usage` at `model` list prices. Unknown models cost 0.0
    (the metric degrades gracefully rather than crashing the worker)."""
    pricing = _PRICING.get(model)
    if pricing is None:
        return 0.0
    return (
        usage.input_tokens * pricing.input_per_mtok
        + usage.output_tokens * pricing.output_per_mtok
        + usage.cache_creation_input_tokens * pricing.cache_write_per_mtok
        + usage.cache_read_input_tokens * pricing.cache_read_per_mtok
    ) / _PER_MTOK  # _PER_MTOK = 1_000_000.0