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

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

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

@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.

@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

@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"

@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"

@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.0-flash-lite"

@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.0-flash-lite"

Detect authentication type based on environment variables.

Detect authentication type based on configuration map.

@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,
#=>   ...
#=> }

@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 configuration based on environment variables and application config. Returns a structured configuration map.

Get configuration with overrides.

@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"}

@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-1.5-pro")
"gemini-1.5-pro"

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

@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

@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

@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

@spec model_for_use_case(
  atom(),
  keyword()
) :: String.t()

Resolve a use-case alias (e.g., :cache_context) to a model string.

Options

• :api - Validate that the resolved model is compatible with :gemini or :vertex_ai
• :strict - Raise on incompatible models instead of logging a warning

@spec models() :: map()

Get all available model definitions (combined for backward compatibility).

For API-specific models, use models_for/1 instead.

Returns

A map of model keys to model names (universal + Gemini API models).

@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_0: "gemini-2.0-flash", ...}

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

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

@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

@spec resolved_use_case_models(keyword()) :: map()

Return resolved model strings for all use-case aliases.

@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

Get HTTP timeout in milliseconds.

@spec use_case_models() :: map()

Built-in use-case aliases mapped to model keys.

@spec use_case_token_minima() :: map()

Recommended minimum token budgets per use case alias.

@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 that required configuration is present.