Normandy.Behaviours.ModelCatalog behaviour (normandy v2.2.0)

Contract for model capability/limit lookup.

BaseAgent.Handlers.compact_turn_memory/3 reads context_window/2 to size the :steering-boundary compaction. The default impl, ModelsAPI, asks the Anthropic Models API at runtime, so new models need no Normandy release.

Callbacks receive the opts from the {module, opts} reference in Normandy.Behaviours.Config. BaseAgent adds :client (a Claudio client built from the agent's Normandy.LLM.ClaudioAdapter) when the reference sets none.

Summary

Callbacks

context_window(model, opts)

Returns {:ok, window}, the model's context window in tokens (a positive integer), or {:error, reason}.

needs_claudio_client?(opts)

Optional. Whether context_window/2 needs the agent's client to be a Normandy.LLM.ClaudioAdapter (the Anthropic Models API lookup). BaseAgent.init/1 refuses the combination of such a catalog, a compactor that needs a window and another client. A module without the callback is taken not to.

Callbacks

context_window(model, opts)

@callback context_window(model :: String.t(), opts :: keyword()) ::
  {:ok, pos_integer()} | {:error, term()}

Returns {:ok, window}, the model's context window in tokens (a positive integer), or {:error, reason}.

The turn calls it when the agent's compactor needs a window and the compactor's opts pin none, then keeps the answer on the config per model. Any other {:ok, value}, and {:error, reason}, fail the turn with a Normandy.ModelCatalogError.

needs_claudio_client?(opts)

(optional)

@callback needs_claudio_client?(opts :: keyword()) :: boolean()