# `gate.cost`: Spend correlation

```{py:currentmodule} gate.cost
```

Correlate private model request IDs with explicit-confidence spend records from a
LiteLLM gateway. Only exact request identifiers cross the local ledger-to-gateway
boundary. The result distinguishes provider-billed, gateway-calculated, estimated,
local-zero-marginal, and unavailable costs.

Data models are frozen `dataclasses`; monetary amounts are `decimal.Decimal`.

## Exceptions

```{eval-rst}
.. autoexception:: gate.cost.CostLookupError
```

## Session interface

```{eval-rst}
.. autoclass:: gate.cost.SessionRecord
   :members:
```

## Spend correlation

```{eval-rst}
.. autofunction:: gate.cost.correlate_session
.. autofunction:: gate.cost.approximate_session_cost
.. autofunction:: gate.cost.baseline_session_cost
.. autofunction:: gate.cost.unavailable_cost
```

## Data models

```{eval-rst}
.. autoclass:: gate.cost.SpendRecord
.. autoclass:: gate.cost.SpendSnapshot
.. autoclass:: gate.cost.SessionCost
.. autoclass:: gate.cost.GatewayRow
.. autoclass:: gate.cost.SpendWindow
```

## Spend API

```{eval-rst}
.. autofunction:: gate.cost.fetch_spend_snapshot
.. autofunction:: gate.cost.fetch_spend_window
.. autofunction:: gate.cost.fetch_spend_summary
```

## Energy estimation

```{eval-rst}
.. autofunction:: gate.cost.local_energy_cost
.. autofunction:: gate.cost.local_energy
.. autofunction:: gate.cost.energy_from_tokens
.. autoclass:: gate.cost.EnergyRecord
.. autoclass:: gate.cost.EnergyCoeff
```

## Aggregation

```{eval-rst}
.. autoclass:: gate.cost.ModelSpendSummary
.. autoclass:: gate.cost.ProjectSpendSummary
.. autoclass:: gate.cost.SpendSummary
.. autofunction:: gate.cost.aggregate_by_model
.. autofunction:: gate.cost.aggregate_by_project
```