# `Pixir.Provider.ContextWindow`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/provider/context_window.ex#L1)

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).

# `assess`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*