# `Gemini.Config`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L1)

Unified configuration management for both Gemini and Vertex AI authentication.

Supports multiple authentication strategies:
- Gemini API (AI Studio): API key authentication
- Vertex AI: OAuth2 or Service Account authentication

## Model Registry

Models are organized by API compatibility:
- **Universal models**: Work identically in both Gemini API and Vertex AI
- **Gemini API models**: Only available in AI Studio (convenience aliases like `-latest`)
- **Vertex AI models**: Only available in Vertex AI (e.g., EmbeddingGemma)

Use `models_for/1` to discover available models for your auth type.

## Auth-Aware Defaults

Default models are automatically selected based on detected authentication:
- Gemini API: `gemini-flash-lite-latest` (convenience alias)
- Vertex AI: `gemini-2.5-flash-lite` (universal name)

For embeddings:
- Gemini API: `gemini-embedding-001` (3072 dimensions)
- Vertex AI: `embeddinggemma` (768 dimensions)

## Examples

    # Auto-detects auth and uses appropriate default
    Gemini.generate("Hello")

    # Get models available for specific API
    Config.models_for(:vertex_ai)

    # Check if a model works with an API
    Config.model_available?(:flash_lite_latest, :vertex_ai)
    #=> false

    # Get auth-aware embedding model
    Config.default_embedding_model()

# `api_type`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L53)

```elixir
@type api_type() :: :gemini | :vertex_ai | :both
```

# `auth_config`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L48)

```elixir
@type auth_config() :: %{type: :gemini | :vertex_ai, credentials: map()}
```

# `model_category`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L54)

```elixir
@type model_category() :: :generation | :embedding | :thinking | :image | :live | :tts
```

# `api_key`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L310)

Get the API key from environment or application config.
(Legacy function for backward compatibility)

# `auth_config`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L299)

```elixir
@spec auth_config() :: auth_config() | nil
```

Get the authentication configuration.

Returns a map with the authentication type and credentials.
Priority order:
1. Environment variables
2. Application configuration
3. Default to Gemini with API key

# `available_use_cases`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L827)

```elixir
@spec available_use_cases() :: [atom()]
```

List available use-case aliases.

## Examples

    iex> Gemini.Config.available_use_cases()
    [:cache_context, :fast_path, :report_section]

# `base_url`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L1035)

Get the base URL for the current authentication type.
(Legacy function - now determined by auth strategy)

# `current_api_type`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L513)

```elixir
@spec current_api_type() :: :gemini | :vertex_ai
```

Get the current API type based on detected authentication.

Returns `:gemini` or `:vertex_ai` based on which credentials are configured.

# `default_embedding_dimensions`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L940)

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

Get the default output dimensionality for an embedding model.

## Examples

    Config.default_embedding_dimensions("gemini-embedding-001")
    #=> 3072

    Config.default_embedding_dimensions("embeddinggemma")
    #=> 768

# `default_embedding_model`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L466)

```elixir
@spec default_embedding_model() :: String.t()
```

Get the default embedding model for the current authentication type.

Returns different defaults based on detected auth:
- Gemini API (AI Studio): `"gemini-embedding-001"` (3072 dimensions)
- Vertex AI: `"embeddinggemma"` (768 dimensions)

Can be overridden via application config:

    config :gemini_ex, :default_embedding_model, "your-model"

## Examples

    # With GEMINI_API_KEY set
    Config.default_embedding_model()
    #=> "gemini-embedding-001"

    # With VERTEX_PROJECT_ID set
    Config.default_embedding_model()
    #=> "embeddinggemma"

# `default_embedding_model_for`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L488)

```elixir
@spec default_embedding_model_for(api_type()) :: String.t()
```

Get the default embedding model for a specific API type.

## Parameters
- `api_type`: `:gemini` or `:vertex_ai`

## Examples

    Config.default_embedding_model_for(:gemini)
    #=> "gemini-embedding-001"

    Config.default_embedding_model_for(:vertex_ai)
    #=> "embeddinggemma"

# `default_model`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L418)

```elixir
@spec default_model() :: String.t()
```

Get the default generation model for the current authentication type.

Returns different defaults based on detected auth:
- Gemini API (AI Studio): `"gemini-flash-lite-latest"` (convenience alias)
- Vertex AI: `"gemini-2.0-flash-lite"` (universal name)

Can be overridden via application config:

    config :gemini_ex, :default_model, "your-model"

## Examples

    # With GEMINI_API_KEY set
    Config.default_model()
    #=> "gemini-flash-lite-latest"

    # With VERTEX_PROJECT_ID set
    Config.default_model()
    #=> "gemini-2.5-flash-lite"

# `default_model_for`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L440)

```elixir
@spec default_model_for(api_type()) :: String.t()
```

Get the default model for a specific API type.

## Parameters
- `api_type`: `:gemini` or `:vertex_ai`

## Examples

    Config.default_model_for(:gemini)
    #=> "gemini-flash-lite-latest"

    Config.default_model_for(:vertex_ai)
    #=> "gemini-2.5-flash-lite"

# `detect_auth_type`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L259)

Detect authentication type based on environment variables.

# `detect_auth_type`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L271)

Detect authentication type based on configuration map.

# `embedding_config`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L867)

```elixir
@spec embedding_config(String.t()) :: map() | nil
```

Get embedding configuration for a specific model.

Returns configuration including supported dimensions, task type handling, etc.

## Parameters
- `model`: Model name string

## Returns
Map with embedding configuration or nil if not an embedding model.

## Examples

    Config.embedding_config("gemini-embedding-001")
    #=> %{
    #=>   default_dimensions: 3072,
    #=>   supported_dimensions: [128, 256, 512, 768, 1536, 3072],
    #=>   recommended_dimensions: [768, 1536, 3072],
    #=>   uses_task_type_param: true,
    #=>   requires_normalization_below: 3072
    #=> }

    Config.embedding_config("embeddinggemma")
    #=> %{
    #=>   default_dimensions: 768,
    #=>   supported_dimensions: [128, 256, 512, 768],
    #=>   uses_task_type_param: false,
    #=>   uses_prompt_prefix: true,
    #=>   ...
    #=> }

# `embedding_prompt_prefix`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L913)

```elixir
@spec embedding_prompt_prefix(
  atom(),
  keyword()
) :: String.t()
```

Get the prompt prefix for an EmbeddingGemma task type.

## Parameters
- `task_type`: Task type atom (e.g., `:retrieval_query`, `:semantic_similarity`)
- `opts`: Optional keyword list
  - `:title` - Document title for `:retrieval_document` task type

## Examples

    Config.embedding_prompt_prefix(:retrieval_query)
    #=> "task: search result | query: "

    Config.embedding_prompt_prefix(:retrieval_document, title: "My Document")
    #=> "title: My Document | text: "

    Config.embedding_prompt_prefix(:retrieval_document)
    #=> "title: none | text: "

# `get`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L225)

Get configuration based on environment variables and application config.
Returns a structured configuration map.

# `get`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L249)

Get configuration with overrides.

# `get_auth_config`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L1143)

```elixir
@spec get_auth_config(:gemini | :vertex_ai) :: map()
```

Get authentication configuration for a specific strategy.

## Parameters
- `strategy`: The authentication strategy (`:gemini` or `:vertex_ai`)

## Returns
- A map containing configuration for the specified strategy
- Returns empty map if no configuration found

## Examples

    iex> Gemini.Config.get_auth_config(:gemini)
    %{api_key: "your_api_key"}

    iex> Gemini.Config.get_auth_config(:vertex_ai)
    %{project_id: "your-project", location: "us-central1"}

# `get_model`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L551)

```elixir
@spec get_model(
  atom() | String.t(),
  keyword()
) :: String.t()
```

Get a model name by its key or return the string if it's already a model name.

Optionally validates that the model is available for a specific API.

## Parameters
- `model_key`: Atom key or string model name
- `opts`: Optional keyword list
  - `:api` - Validate model works with `:gemini` or `:vertex_ai`
  - `:strict` - If true, raise on incompatible model (default: false, warns)

## Examples

    iex> Gemini.Config.get_model(:flash_2_0)
    "gemini-2.0-flash"

    iex> Gemini.Config.get_model("gemini-2.5-flash")
    "gemini-2.5-flash"

    iex> Gemini.Config.get_model(:flash_lite_latest, api: :vertex_ai)
    # Logs warning: Model flash_lite_latest (gemini-flash-lite-latest) may not be available on vertex_ai
    "gemini-flash-lite-latest"

    iex> Gemini.Config.get_model(:flash_lite_latest, api: :vertex_ai, strict: true)
    # ** (ArgumentError) Model :flash_lite_latest not available on vertex_ai

# `has_model?`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L631)

```elixir
@spec has_model?(atom()) :: boolean()
```

Check if a model key exists in the combined model registry.

## Examples

    iex> Gemini.Config.has_model?(:flash_2_0)
    true

    iex> Gemini.Config.has_model?(:unknown)
    false

# `live_registry_candidates`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L715)

```elixir
@spec live_registry_candidates(:text | :audio) :: [String.t()]
```

Return registry-backed Live API candidate model codes for a modality.

# `model_api`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L657)

```elixir
@spec model_api(atom()) :: api_type() | nil
```

Get the API compatibility of a model key.

## Returns
- `:both` - Model works in both Gemini API and Vertex AI
- `:gemini` - Model only works in Gemini API (AI Studio)
- `:vertex_ai` - Model only works in Vertex AI

## Examples

    Config.model_api(:flash_2_0)
    #=> :both

    Config.model_api(:flash_lite_latest)
    #=> :gemini

    Config.model_api(:embedding_gemma)
    #=> :vertex_ai

# `model_available?`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L615)

```elixir
@spec model_available?(atom(), api_type()) :: boolean()
```

Check if a model key is available for a specific API type.

## Parameters
- `model_key`: Atom model key to check
- `api_type`: `:gemini` or `:vertex_ai`

## Examples

    Config.model_available?(:flash_2_0, :vertex_ai)
    #=> true

    Config.model_available?(:flash_lite_latest, :vertex_ai)
    #=> false

    Config.model_available?(:embedding_gemma, :gemini)
    #=> false

# `model_for_use_case`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L753)

```elixir
@spec model_for_use_case(atom(), api_type() | nil) :: String.t()
```

Get the model string for a use-case alias.

Use-case aliases provide consistent model selection with recommended token budgets.
This avoids scattering raw model strings throughout the codebase.

## Parameters
- `use_case`: Use-case atom (`:cache_context`, `:report_section`, `:fast_path`)
- `api_type`: Optional API type for validation (`:gemini` or `:vertex_ai`)

## Available Use Cases

| Use Case | Model | Recommended Token Budget |
|----------|-------|--------------------------|
| `:cache_context` | gemini-2.5-flash | 32,000 |
| `:report_section` | gemini-2.5-pro | 16,000 |
| `:fast_path` | gemini-2.5-flash-lite | 8,000 |

## Examples

    iex> Gemini.Config.model_for_use_case(:cache_context)
    "gemini-2.5-flash"

    iex> Gemini.Config.model_for_use_case(:fast_path)
    "gemini-2.5-flash-lite"

    iex> Gemini.Config.model_for_use_case(:cache_context, :vertex_ai)
    "gemini-2.5-flash"

# `model_info`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L673)

```elixir
@spec model_info(atom() | String.t()) :: Gemini.ModelRegistry.entry() | nil
```

Return model metadata from `Gemini.ModelRegistry`.

Accepts either a registry key atom (resolved through `get_model/1`) or a
concrete model string.

# `model_supports?`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L690)

```elixir
@spec model_supports?(
  atom() | String.t(),
  Gemini.ModelRegistry.capability(),
  Gemini.ModelRegistry.support_state()
) :: boolean()
```

Check model capability support state from `Gemini.ModelRegistry`.

Defaults to checking for `:supported`.

# `models_for`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L592)

```elixir
@spec models_for(api_type()) :: map()
```

List all models available for a specific API type.

## Parameters
- `api_type`: `:gemini`, `:vertex_ai`, or `:both` (universal only)

## Examples

    Config.models_for(:gemini)
    #=> %{flash_lite_latest: "gemini-flash-lite-latest", flash_2_5: "gemini-2.5-flash", ...}

    Config.models_for(:vertex_ai)
    #=> %{embedding_gemma: "embeddinggemma", flash_2_5: "gemini-2.5-flash", ...}

    Config.models_for(:both)
    #=> %{flash_2_5: "gemini-2.5-flash", ...}  # Only universal models

# `models_with_capability`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L706)

```elixir
@spec models_with_capability(
  Gemini.ModelRegistry.capability(),
  Gemini.ModelRegistry.support_state()
) :: [String.t()]
```

List model codes that match a capability support state.

# `needs_normalization?`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L965)

```elixir
@spec needs_normalization?(String.t(), pos_integer()) :: boolean()
```

Check if an embedding needs normalization for a given dimensionality.

Gemini embedding models only return normalized embeddings at full dimensionality.
Lower dimensions need manual normalization. EmbeddingGemma is always normalized.

## Examples

    Config.needs_normalization?("gemini-embedding-001", 768)
    #=> true

    Config.needs_normalization?("gemini-embedding-001", 3072)
    #=> false

    Config.needs_normalization?("embeddinggemma", 256)
    #=> false  # EmbeddingGemma is always normalized

# `resolved_use_case_models`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L812)

```elixir
@spec resolved_use_case_models() :: %{required(atom()) => String.t()}
```

Get all resolved use-case model mappings.

Returns a map of use-case atoms to their resolved model strings.

## Examples

    iex> Gemini.Config.resolved_use_case_models()
    %{
      cache_context: "gemini-2.5-flash",
      report_section: "gemini-2.5-pro",
      fast_path: "gemini-2.5-flash-lite"
    }

# `telemetry_enabled?`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L1117)

```elixir
@spec telemetry_enabled?() :: boolean()
```

Check if telemetry is enabled.

Determines whether telemetry events should be emitted based on the
application configuration. Telemetry is enabled by default unless
explicitly disabled.

## Configuration

Set `:telemetry_enabled` to `false` in your application config to disable:

    config :gemini, telemetry_enabled: false

## Returns

- `true` - Telemetry is enabled (default)
- `false` - Telemetry is explicitly disabled

## Examples

    iex> # Default behavior (telemetry enabled)
    iex> Gemini.Config.telemetry_enabled?()
    true

    iex> # Explicitly disabled
    iex> Application.put_env(:gemini, :telemetry_enabled, false)
    iex> Gemini.Config.telemetry_enabled?()
    false

    iex> # Any other value defaults to enabled
    iex> Application.put_env(:gemini, :telemetry_enabled, :maybe)
    iex> Gemini.Config.telemetry_enabled?()
    true

# `timeout`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L1027)

Get HTTP timeout in milliseconds.

# `use_case_token_budget`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L784)

```elixir
@spec use_case_token_budget(atom()) :: pos_integer()
```

Get the recommended token budget for a use-case alias.

## Parameters
- `use_case`: Use-case atom

## Examples

    iex> Gemini.Config.use_case_token_budget(:cache_context)
    32000

    iex> Gemini.Config.use_case_token_budget(:fast_path)
    8000

# `uses_prompt_prefix?`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L886)

```elixir
@spec uses_prompt_prefix?(String.t()) :: boolean()
```

Check if an embedding model uses prompt prefixes for task types.

EmbeddingGemma uses prompt prefixes like "task: search result | query: "
while Gemini embedding models use a taskType parameter.

## Examples

    Config.uses_prompt_prefix?("embeddinggemma")
    #=> true

    Config.uses_prompt_prefix?("gemini-embedding-001")
    #=> false

# `validate!`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/config.ex#L1055)

Validate that required configuration is present.

---

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