Per-prediction LM usage ledger.
Ports DSPy 3.2.1's track_usage / UsageTracker surface
(dspy/utils/usage_tracker.py): when the :track_usage setting is true,
Imp.Predict.call runs inside track/1, every LM call that reports
provider usage is recorded against its model, and the aggregate lands on the
returned prediction (read it with Imp.Prediction.get_lm_usage/1).
The tracker is a per-process stack. Nested trackers shadow outer ones for the
duration of the inner call, exactly as DSPy's settings.context(usage_tracker=...)
does. Parallel program runs (Imp.Predict.Parallel) execute in separate
processes, so each result carries only its own usage — the isolation DSPy's
thread-local tracker provides.
Summary
Functions
Records one LM call's usage from an LM result, if a frame is active.
Adds a usage entry for model_key to the innermost active frame.
Runs fun with a fresh usage frame and returns {result, usage}.
True when a usage frame is active in this process.
Functions
Records one LM call's usage from an LM result, if a frame is active.
The model key and usage entry come from the result's provider metadata
(Imp.LM.Result envelope, :req_llm entry). Results without usage
metadata record nothing.
Adds a usage entry for model_key to the innermost active frame.
Runs fun with a fresh usage frame and returns {result, usage}.
usage maps a model key (for example "openai/gpt-4o-mini") to a merged
usage entry, the same shape DSPy's UsageTracker.get_total_tokens() returns.
True when a usage frame is active in this process.