# `Alloy.ModelMetadata`
[🔗](https://github.com/alloy-ex/alloy/blob/v0.12.4/lib/alloy/model_metadata.ex#L1)

Built-in model metadata catalog used for context budgeting.

This is the default implementation of the `Alloy.ModelCatalog` behaviour.
It ships a small, hand-curated set of entries so Alloy works out of the
box; it is not meant to track every model release. To use a richer or
self-maintained source (a static map, your own service, or an adapter over
[`llm_db`](https://hex.pm/packages/llm_db)), implement `Alloy.ModelCatalog`
and pass the module via the `:model_catalog` option.

Per-run tweaks that don't warrant a catalog module belong in
`:model_metadata_overrides` — overrides always win over any catalog.

# `model_entry`

```elixir
@type model_entry() :: %{
  name: String.t(),
  limit: pos_integer(),
  suffix_patterns: [String.t() | Regex.t()]
}
```

# `override_entry`

```elixir
@type override_entry() ::
  pos_integer()
  | %{
      :limit => pos_integer(),
      optional(:suffix_patterns) => [String.t() | Regex.t()]
    }
```

# `catalog`

```elixir
@spec catalog() :: [model_entry()]
```

Returns the known model catalog.

# `context_window`

```elixir
@spec context_window(String.t()) :: pos_integer() | nil
```

Returns the known context window limit for a model name
(`Alloy.ModelCatalog` callback).

Returns `nil` when the model is not in the built-in catalog.

# `context_window`

```elixir
@spec context_window(
  String.t(),
  %{optional(String.t()) => override_entry()} | [{String.t(), override_entry()}]
) :: pos_integer() | nil
```

Returns the known context window limit for a model name, consulting
`overrides` ahead of the built-in catalog.

`overrides` may provide exact-model or family overrides as either:

- `%{"model-name" => 1_000_000}`
- `%{"model-name" => %{limit: 1_000_000, suffix_patterns: ["", ~r/^-+$/]}}`

For overrides that only provide a limit, existing catalog suffix patterns are
reused when available; unknown models default to exact-match only.

Returns `nil` when the model is not in the current catalog or overrides.

# `default_context_window`

```elixir
@spec default_context_window() :: pos_integer()
```

Returns the default fallback context window for unknown models.

# `override_window`

```elixir
@spec override_window(
  String.t(),
  %{optional(String.t()) => override_entry()} | [{String.t(), override_entry()}]
) :: pos_integer() | nil
```

Returns the context window for `model_name` from `overrides` alone,
ignoring the built-in catalog.

Used to apply `:model_metadata_overrides` ahead of any
`Alloy.ModelCatalog` implementation. Returns `nil` when no override
matches.

---

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