# `ReqManagedAgents.ModelConfig`
[🔗](https://github.com/cash-mckeeman/req_managed_agents/blob/v0.14.0/req_managed_agents/lib/req_managed_agents/model_config.ex#L1)

The canonical `:model_config` session option, with a closed set of atom keys.

Every field is optional. `:model` carries a catalog model id or a provider-native
value, `:api_key`, `:bearer_token_file` and `:base_url` supply the provider's
credential and destination, and `:metadata` holds correlation information.

`ReqManagedAgents.Session` validates the option before opening the provider and
refuses fields the provider cannot apply. A binary `:model` is translated from
a catalog id through `ReqManagedAgents.Provider.native_model/2`; non-binary
models are treated as native values. Providers receive the map from `to_map/1`.

This differs from `ReqManagedAgents.Agent.Spec`'s `model_config`, the
provider-specific configuration interpreted by the selected provider at provisioning.

# `metadata`

```elixir
@type metadata() :: map()
```

Open correlation metadata supplied by the caller.

# `provider_projection`

```elixir
@type provider_projection() :: %{
  optional(:model) => term(),
  optional(:api_key) => String.t() | nil,
  optional(:bearer_token_file) => String.t() | nil,
  optional(:base_url) => String.t() | nil,
  optional(:metadata) => metadata()
}
```

Canonical provider-facing atom-keyed map; nil fields are tolerated.
The closed projection keeps metadata as an open caller-supplied bag.

# `reason`

```elixir
@type reason() :: {:unknown_keys, [term()]} | {:invalid, atom()} | :not_a_map
```

# `t`

```elixir
@type t() :: %ReqManagedAgents.ModelConfig{
  api_key: String.t() | nil,
  base_url: String.t() | nil,
  bearer_token_file: String.t() | nil,
  metadata: metadata(),
  model: term()
}
```

# `data_plane?`

```elixir
@spec data_plane?(t() | provider_projection()) :: boolean()
```

Returns true when a credential or destination field is non-nil.

# `new`

```elixir
@spec new(t() | map() | keyword()) :: {:ok, t()} | {:error, reason()}
```

Coerces a struct, an atom-keyed map or a keyword list into a validated config.

Unknown keys, including string keys, return `{:error, {:unknown_keys, keys}}`
with sorted keys. Credentials and destinations must be binaries or `nil`;
metadata must be a map or `nil`, which becomes an empty map. Invalid values
return `{:error, {:invalid, key}}`. The model is passed through unchanged.
Other inputs return `{:error, :not_a_map}`.

# `to_map`

```elixir
@spec to_map(t()) :: provider_projection()
```

Renders the provider-facing atom-keyed map, omitting nil fields and empty metadata.

---

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