# `WardrikCore.Keys`

Gives your code the API keys it calls services with, such as a model provider's or a search
API's.

    defmodule MyApp.Keys do
      @behaviour WardrikCore.Keys

      @impl true
      def fetch(name, principal, _opts), do: MyApp.Vault.key(principal, name)
    end

Give it to an agent as `keys: {MyApp.Keys, opts}`. Keys are fetched by name, for the agent's
`WardrikCore.Principal`, so an org can bring its own. A capability or middleware fetches what it
needs:

    with {:ok, key} <- WardrikCore.Keys.fetch(context, "BRAVE_API_KEY") do
      Brave.search(key, query)
    end

## Model calls

Every model call fetches its provider's key by the name ReqLLM gives it, such as
`ANTHROPIC_API_KEY`, and passes it to that call only. If there's no keys module, or it has no
such key, ReqLLM finds one in its config or the environment.

## Keys and credentials

Keys are for the code you install. A tool that acts for a person uses their credentials instead,
from `WardrikCore.Credentials`. That way nothing an agent's owner configures can read your keys.

Keys are never kept in the context, so they're never saved or emitted.

# `fetch`

```elixir
@callback fetch(name :: String.t(), WardrikCore.Principal.t() | nil, opts :: term()) ::
  {:ok, String.t()} | :error
```

Returns the key `name` for `principal`, or `:error` if there's none.

# `fetch`

```elixir
@spec fetch(WardrikCore.Context.t(), String.t()) :: {:ok, String.t()} | :error
```

Fetches the key `name` for the agent's principal. Returns `:error` if there's none.

# `key_name`

```elixir
@spec key_name(LLMDB.Model.t() | String.t()) :: String.t() | nil
```

Returns the name of the key `model`'s provider takes, or `nil`.

    WardrikCore.Keys.key_name("zai:glm-5.1")
    #=> "ZAI_API_KEY"

# `model_options`

```elixir
@spec model_options(WardrikCore.Context.t(), LLMDB.Model.t() | String.t()) ::
  keyword()
```

Returns `[api_key: key]` for `model`'s provider, or `[]` if there's no key.

---

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