Pixir.Provider.ContextWindow (pixir v0.1.0)

Copy Markdown View Source

The conservative model context-window table and the context-pressure gauge (ADR 0020, "advisory before failure").

Pressure is read from durable local evidence — the input_tokens field of the usage_summary already recorded per Provider call (ADR 0019) — against a conservative per-model window. Two rules are load-bearing:

  • Conservative, justified values only. The built-in table covers the model catalog (Pixir.Provider.models/0) with documented or observed per-SKU bounds. Large GPT-5/Codex-family models use the documented 400K total context window with a 272K max-input ceiling; gpt-5.3-codex-spark is a smaller real-time SKU with a documented 128K context window. Pixir gauges pressure against recorded input tokens, so the input bound is the honest ceiling; if a successor model is actually larger, advisories merely fire early (the safe direction).
  • An unknown model never fakes a threshold. window_tokens/1 returns a structured :context_window_unknown error and assess/2 degrades to an explicit advisory-unavailable result — no tier, no ratio, no advisory.

Values are overrideable via ~/.pixir/config.json:

{"context_windows": {"gpt-5.5": 200000, "my-local-model": 32000}}

Tiers (ADR 0020 Decision 4; boundaries are inclusive on the lower edge): below 70% nothing, 70–80% light advisory, 80–90% visible warning, 90%+ recovery-eligible ("critical"). Reaching critical makes the session eligible for preflight compaction before the next Turn and for pragmatic recovery on low-level transport failures (e.g. WebSocket read errors) when the local gauge shows we were near the window. Recovery actions still record explicit history_compaction checkpoints (see ADR 0020).

Summary

Functions

assess(usage_summary, model)

Assess context pressure for one recorded call: usage_summary is the Pixir.Provider.usage_summary/1 shape (atom- or string-keyed, as recorded in provider_usage evidence).

window_tokens(model)

The conservative context window (in input tokens) for model. Config overrides ("context_windows" in ~/.pixir/config.json) win over the built-in table; an unknown model is an explicit :context_window_unknown error, never a guess.

Functions

assess(usage_summary, model)

@spec assess(map() | nil, String.t() | nil) :: {:ok, map()} | {:error, map()}

Assess context pressure for one recorded call: usage_summary is the Pixir.Provider.usage_summary/1 shape (atom- or string-keyed, as recorded in provider_usage evidence).

Returns {:ok, assessment} where the string-keyed assessment is either

  • "available" => true with "tier" ("none" | "advisory" | "warning" | "critical"), "ratio", "input_tokens", and "window_tokens", or

  • "available" => false with "tier" => "unavailable" and a "reason" — the unknown-model degradation; callers must fire no advisory from it.

window_tokens(model)

@spec window_tokens(String.t() | nil) :: {:ok, pos_integer()} | {:error, map()}

The conservative context window (in input tokens) for model. Config overrides ("context_windows" in ~/.pixir/config.json) win over the built-in table; an unknown model is an explicit :context_window_unknown error, never a guess.