# `LLMDB.Runtime`
[🔗](https://github.com/agentjido/llm_db/blob/main/lib/llm_db/runtime.ex#L1)

Runtime configuration compilation for consumer applications.

Phase 2 of LLMDB: Compile runtime configuration by merging application
environment config with per-call options, enabling consumers to:
- Filter models by provider/model patterns (allow/deny)
- Define provider preferences
- Add custom providers/models

This module handles the consumer-facing runtime configuration that gets
applied when loading the packaged snapshot into the Store.

## Example

    # Compile runtime config from app env + per-call opts
    runtime = LLMDB.Runtime.compile(
      allow: [:openai, :anthropic],
      custom: %{
        providers: [%{id: :myprov, name: "My Provider"}],
        models: [%{provider: :myprov, id: "my-model", capabilities: %{chat: true}}]
      }
    )

    # Runtime config can then be used to filter and customize the catalog

# `apply`

```elixir
@spec apply(map(), map() | nil) :: {:ok, map()} | {:error, term()}
```

Applies runtime overrides to an existing snapshot.

## Parameters

- `snapshot` - The current snapshot map
- `overrides` - Map with optional `:filter` and `:prefer` keys

## Override Options

- `:filter` - %{allow: patterns, deny: patterns} to recompile and reapply
- `:prefer` - List of provider atoms to update preference order

## Returns

- `{:ok, updated_snapshot}` - Success with updated snapshot
- `{:error, reason}` - Validation or processing error

# `compile`

```elixir
@spec compile(keyword()) :: map()
```

Compiles runtime configuration by merging app env and per-call options.

Merges application environment configuration (from `config :llm_db, ...`) with
options passed at load time, normalizes the configuration, and compiles filters.

## Parameters

- `opts` - Keyword list of per-call options that override app env:
  - `:allow` - `:all`, list of providers `[:openai]`, or map `%{openai: :all | [patterns]}`
  - `:deny` - List of providers `[:provider]` or map `%{provider: [patterns]}`
  - `:prefer` - List of provider atoms in preference order
  - `:custom` - Map with provider IDs as keys, provider configs (with models) as values
  - `:provider_ids` - Optional list of known provider IDs for validation

## Returns

Map with compiled runtime configuration:
- `:filters` - Compiled allow/deny patterns
- `:prefer` - Provider preference list
- `:custom` - Normalized custom providers/models (%{providers: [...], models: [...]})
- `:unknown` - List of unknown providers in filters (for warnings)

## Examples

    # Simple provider allow list
    runtime = Runtime.compile(allow: [:openai, :anthropic])
    runtime.filters.allow
    #=> %{openai: :all, anthropic: :all}

    # Provider allow list with model patterns
    runtime = Runtime.compile(
      allow: %{openai: ["gpt-4*"], anthropic: :all},
      deny: %{openai: ["gpt-4-0613"]}
    )

    # With custom providers
    runtime = Runtime.compile(
      custom: %{
        vllm: [
          name: "Local vLLM Provider",
          models: %{
            "llama-3" => %{capabilities: %{chat: true}}
          }
        ]
      }
    )

---

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