turn_cost.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/turn_cost.py
 
"""
Per-turn USD cost, computed in the render lane and honesty-gated — plan 188 T4,
re-priced by :mod:`oc_pricing` (plan 202).
 
Purpose
-------
The synthesis asks for a per-turn ``$`` line beside the token gauges.
Everything needed already reaches the render lane: ``run_turn``
accumulates the provider's own cache-hit / cache-miss / completion token
split per iteration, and the **effective-dated, TOU-aware price table
now ships as the standalone** :mod:`oc_pricing` **package** (plans
206/210/211) — the one authoritative pricing source every Option C
client imports. This module joins the two. No pricing data is invented
here — if the package cannot price a sample *at the sample's instant*,
there is no line.
 
The governing rule (plan 188 T4): **no line is better than a false
line.** Every gate below prefers silence over a plausible number. Plan
202 adds the converse hazard: a misfiring timestamp would make EVERY
sample unpriceable — a silent pricing blackout that reads as honest
"unknown" while hiding real spend. The pricing instant therefore
arrives as an explicit, required ``at`` captured once per sample at the
send seam (:mod:`oc_chat.core.react_loop`'s ``_now_utc``), never read
ambiently here.
 
Responsibilities
----------------
- :class:`TurnCost` — the immutable result handed to presenters:
  the figure plus the provenance that makes it auditable.
- :func:`price_usage` — price ONE usage sample at ONE instant, or
  ``None`` when any input makes the answer a guess.
- :class:`TurnCostAccumulator` — fold a turn's samples exactly
  (Decimal); one unpriceable sample suppresses the whole turn.
 
Why per-sample rather than per-turn: a turn's iterations each carry
their own model (``route.model``), their own cache split, and — now —
their own pricing instant, and a sub-loop folds in usage of its own.
Pricing each sample at the model AND tariff that actually produced it
is exact; pricing the turn's summed tokens at one rate would silently
mis-rate a routed turn or a turn straddling a tariff boundary.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — a turn suppressed as unpriceable.
    L3 — per-sample gate rejections.
    L4 — module-load coverage marker.
 
Contracts
---------
- ``price_usage`` returns ``None`` — never 0.0 as a stand-in — when:
  the package has no rate for (provider, model) in force at ``at``; the
  reported cache split does not ACCOUNT for the prompt
  (``hit + miss != prompt_tokens``, so the input side is unknown —
  costing it all as a miss would overstate); there are no tokens at
  all; or ``at`` is ``None``/naive (oc_pricing prices a time-dependent
  row only from an aware instant — a guessed tariff would be a wrong
  number).
- Usage is reduced to :class:`oc_pricing.CanonicalUsage` DIRECTLY from
  OC_Chat's own ``(hit, miss)`` extraction — NEVER via
  ``oc_pricing.usage_from_deepseek``. That reducer reads only the
  explicit ``prompt_cache_hit_tokens``/``prompt_cache_miss_tokens``
  fields, but real DeepSeek-via-OpenAI-SDK usage reports cache via
  ``prompt_tokens_details.cached_tokens`` — routing live usage through
  it would price EVERY live turn to ``None`` (plan 202 decision 2).
- A turn is priced only if EVERY sample priced. A partial total is a
  wrong number, not a smaller one.
- The turn total is accumulated as exact ``Decimal`` from
  ``oc_pricing.breakdown_usd`` and quantized ONCE at :meth:`result` —
  never a sum of per-sample floats. This exactness claim is the live
  ``$`` line's alone; the event projection still folds the float
  ``cost_usd`` published on the bus (plan 202 residual).
- One ``at`` prices a whole sample; a turn straddling a TOU boundary
  prices each sample at its own send instant (deliberate, observable
  approximation — plan 202 residual).
- Nothing here publishes an event or mutates session state.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_pricing (the one authoritative effective-dated, TOU-aware table)
"""
from __future__ import annotations
 
from dataclasses import dataclass
from datetime import datetime
from decimal import ROUND_HALF_EVEN, Context, Decimal, localcontext
from typing import Optional
 
from oc_diagnostics import _dbg
 
import oc_pricing
from oc_pricing import CanonicalUsage, RateQuote
 
_dbg("OC_CHAT.MAIN", "turn_cost", "module", 4)
 
 
#: Label used when a turn's samples span more than one model — the total is
#: still exact (each sample was priced at its own rate) but no single model
#: name would be true of it.
MIXED_MODEL: str = "mixed"
 
#: The pinned money context, mirroring oc_pricing's own: accumulation and
#: the final quantize run under a COPY of this, never the ambient
#: thread-local decimal context — a host that sets ``prec=4`` or traps
#: ``Inexact`` can neither change a total nor crash the money path.
_MONEY_CONTEXT = Context(prec=28, rounding=ROUND_HALF_EVEN)
 
#: Quantum of the displayed figure: micro-dollar, matching the six decimal
#: places the pre-202 ``round(total, 6)`` presented.
_USD_QUANTUM = Decimal("0.000001")
 
 
@dataclass(frozen=True, slots=True)
class TurnCost:
    """A priced turn plus the provenance that makes the figure auditable."""
 
    total_usd: float
    """Modelled spend for the turn, in USD. Always an estimate, never a bill."""
    model: str
    # OCT-LINT: disable=no_hardcoded_secrets reason="Dataclass field docstring prose trips the Shannon entropy heuristic (4.57 bits/char); no secret material - this module carries published per-million-token rates via oc_pricing only"
    """The model priced, or :data:`MIXED_MODEL` when the turn spanned several."""
    provider: str
    """The provider whose published rates were applied."""
    as_of: str
    """Vendor-verification date of the SELECTED rate version
    (``RateQuote.verified_at``) — the figure is only as fresh as this."""
    source: str
    """Where the selected version's rates came from
    (``RateQuote.source``), so a reader can re-check them."""
 
 
def _canonical_sample(
    cache_hit_tokens: int,
    cache_miss_tokens: int,
    prompt_tokens: int,
    completion_tokens: int,
) -> Optional[CanonicalUsage]:
    """Reduce one OC_Chat usage sample to a :class:`CanonicalUsage`, or ``None``.
 
    The two fail-closed gates the DIRECT build must re-establish live here,
    because bypassing ``usage_from_deepseek`` (deliberately — see the module
    Contracts) also bypasses that reducer's own split gate:
 
    - nothing happened (all-zero) → ``None``: preserves plan 188's
      suppression — a ``$0.000000`` line for an empty sample is noise
      presented as a price (oc_pricing would price it 0.0).
    - ``hit + miss != prompt`` → ``None``: the input side is priced at two
      different rates, so an unaccounted prompt cannot be costed — charging
      the remainder at either rate would be a guess.
 
    Completion maps whole to ``out``: DeepSeek bills chain-of-thought as
    output (the table's rows carry ``reasoning: null``), which is why the
    pre-202 distinct-reasoning-rate gate no longer exists.
    """
    func = "_canonical_sample"
    hit = max(0, int(cache_hit_tokens or 0))
    miss = max(0, int(cache_miss_tokens or 0))
    prompt = max(0, int(prompt_tokens or 0))
    completion = max(0, int(completion_tokens or 0))
 
    if hit + miss == 0 and completion == 0:
        return None  # nothing happened worth costing
 
    if hit + miss != prompt:
        _dbg("OC_CHAT.MAIN", func,
             f"cache split {hit}+{miss} does not account for prompt {prompt}", 3)
        return None
 
    return CanonicalUsage(
        uncached_in=miss, cache_read=hit, cache_write=0, out=completion,
    )
 
 
def price_usage(
    provider: str,
    model: str,
    *,
    cache_hit_tokens: int,
    cache_miss_tokens: int,
    prompt_tokens: int,
    completion_tokens: int,
    at: Optional[datetime],
) -> float | None:
    """Price one usage sample in USD at instant ``at``, or ``None``.
 
    ``at`` is required and must be the sample's ONE captured, tz-aware
    instant (react_loop's ``_now_utc`` seam) — the tariff in force is a
    function of it, and today's table is effective-dated AND time-of-use
    banded, so ``at`` changes the number in production. A ``None`` or
    naive ``at`` yields ``None`` (unpriceable), never a guessed tariff.
 
    See the module Contracts for the exact gates. The caller must treat
    ``None`` as "suppress the line", never as zero.
    """
    func = "price_usage"
    usage = _canonical_sample(
        cache_hit_tokens, cache_miss_tokens, prompt_tokens, completion_tokens,
    )
    if usage is None:
        return None
    usd = oc_pricing.cost_usd(usage, provider=provider, model=model, at=at)
    if usd is None:
        _dbg("OC_CHAT.MAIN", func,
             f"no rate in force for {provider}/{model} at={at!r}", 3)
    return usd
 
 
class TurnCostAccumulator:
    """Folds a turn's usage samples into one :class:`TurnCost`, or nothing.
 
    Each :meth:`add` prices at the model AND instant that actually produced
    the sample. The first sample that cannot be priced latches the turn
    unpriceable — reporting the priced subset would understate the turn
    while looking authoritative, which is the exact failure mode plan 188
    T4 forbids.
 
    The running total is an exact ``Decimal`` sum of per-sample
    ``breakdown_usd(...)["total"]`` values, quantized once at
    :meth:`result` — the 200-sample fold and the one-aggregate figure are
    equal by construction (the live ``$`` line's exactness win; the event
    projection is NOT covered by this claim).
    """
 
    __slots__ = ("_total", "_models", "_provider", "_priceable", "_samples",
                 "_last_quote")
 
    def __init__(self) -> None:
        self._total = Decimal(0)
        self._models: set[str] = set()
        self._provider = ""
        self._priceable = True
        self._samples = 0
        self._last_quote: Optional[RateQuote] = None
 
    def add(
        self,
        provider: str,
        model: str,
        *,
        cache_hit_tokens: int,
        cache_miss_tokens: int,
        prompt_tokens: int,
        completion_tokens: int,
        at: Optional[datetime],
    ) -> None:
        """Fold one usage sample priced at ``at``. No-op once unpriceable."""
        if not self._priceable:
            return
        usage = _canonical_sample(
            cache_hit_tokens, cache_miss_tokens, prompt_tokens, completion_tokens,
        )
        if usage is None:
            self._priceable = False
            return
        breakdown = oc_pricing.breakdown_usd(
            usage, provider=provider, model=model, at=at,
        )
        if breakdown is None:
            self._priceable = False
            return
        # Selection is a pure function of (provider, model, at) against the
        # process-cached table, so this quote is the SAME version + band that
        # just priced the breakdown; captured per-sample so a MIXED_MODEL
        # turn carries the last-priced sample's provenance (plan 202 dec. 6).
        self._last_quote = oc_pricing.rate_at(provider, model, at=at)
        with localcontext(_MONEY_CONTEXT):
            self._total += breakdown["total"]
        self._models.add(model)
        self._provider = provider or self._provider
        self._samples += 1
 
    def result(self) -> TurnCost | None:
        """The turn's cost, or ``None`` when any part of it was unpriceable."""
        func = "result"
        if not self._priceable:
            _dbg("OC_CHAT.MAIN", func, "turn not priceable; no cost line", 2)
            return None
        if self._samples == 0 or self._last_quote is None:
            return None
        quote = self._last_quote
        model = next(iter(self._models)) if len(self._models) == 1 else MIXED_MODEL
        with localcontext(_MONEY_CONTEXT):
            total = float(self._total.quantize(_USD_QUANTUM))
        return TurnCost(
            total_usd=total,
            model=model,
            provider=self._provider,
            as_of=quote.verified_at or "",
            source=quote.source or "",
        )
 
 
__all__ = ["MIXED_MODEL", "TurnCost", "TurnCostAccumulator", "price_usage"]