PhoenixKitAI.Endpoint (PhoenixKitAI v0.10.0)

Copy Markdown View Source

AI endpoint schema for PhoenixKit AI system.

An endpoint is a unified configuration that combines provider credentials, model selection, and generation parameters into a single entity. Each endpoint represents one complete AI configuration ready for making API requests.

Schema Fields

Identity

  • name: Display name for the endpoint (e.g., "Claude Fast", "GPT-4 Creative")
  • description: Optional description of the endpoint's purpose

Provider Configuration

  • provider: Integration connection key (e.g. "openrouter" or "openrouter:my-key"). Resolved via PhoenixKit.Integrations.
  • api_key: Deprecated. Legacy field retained for pre-Integrations endpoints — OpenRouterClient.resolve_api_key/2 reads it as a fallback when no PhoenixKit.Integrations connection is configured for the endpoint's provider. The column is NOT NULL in core's V34 migration, so for now you must provide a value (an empty string is accepted by the DB but will trigger a per-call Logger.warning if no Integrations connection is set up either). The recommended migration path is documented in AGENTS.md "Migrating from legacy endpoint.api_key" — set up an OpenRouter connection under Settings → Integrations and point provider at it; the legacy column then becomes unused. Planned for removal in a future major version once operators have had time to migrate.
  • base_url: Optional custom base URL for the provider
  • provider_settings: Provider-specific settings (JSON)
    • For OpenRouter: http_referer, x_title headers
    • For TTS: voice — default voice / voice id used by PhoenixKitAI.speak/3 when the caller passes no explicit voice

Model Configuration

  • model: AI model identifier (e.g., "anthropic/claude-3-haiku")

Generation Parameters

  • temperature: Sampling temperature (0-2, default: 0.7)
  • max_tokens: Maximum tokens to generate (nil = model default)
  • top_p: Nucleus sampling threshold (0-1)
  • top_k: Top-k sampling parameter
  • frequency_penalty: Frequency penalty (-2 to 2)
  • presence_penalty: Presence penalty (-2 to 2)
  • repetition_penalty: Repetition penalty (0-2)
  • stop: Stop sequences (array of strings)
  • seed: Random seed for reproducibility

Image Generation Parameters

  • image_size: Image size (e.g., "1024x1024", "1792x1024")
  • image_quality: Image quality ("standard", "hd")

Embeddings Parameters

  • dimensions: Embedding dimensions (model-specific)

Status

  • enabled: Whether the endpoint is active
  • sort_order: Display order for listing
  • last_validated_at: Last successful API key validation

Usage Examples

# Create an endpoint
{:ok, endpoint} = PhoenixKitAI.create_endpoint(%{
  name: "Claude Fast",
  provider: "openrouter",
  api_key: "sk-or-v1-...",
  model: "anthropic/claude-3-haiku",
  temperature: 0.7
})

# Use the endpoint
{:ok, response} = PhoenixKitAI.ask(endpoint.uuid, "Hello!")

Summary

Types

t()

Functions

changeset(endpoint, attrs)

Creates a changeset for endpoint creation and updates.

default_base_url(provider)

Returns the default base URL for a provider, read from the Integrations registry (PhoenixKit.Integrations.Providers.base_url/1).

image_quality_options()

Returns image quality options for form selects.

image_size_options()

Returns image size options for form selects.

kind(model)

Classifies an endpoint by the kind of model it points at.

kind_icon(atom)

Heroicon name representing an endpoint kind/1.

masked_api_key(api_key)

Masks the API key for display.

provider_label(provider)

Returns a display label for the provider, read from the Integrations registry (the provider's name).

provider_options()

Returns provider options ({label, key}) for form selects.

reasoning_effort_options()

Returns reasoning effort options for form selects.

recently_validated?(endpoint)

Checks if the endpoint has been validated recently (within the last 24 hours).

short_model_name(model)

Extracts the model name without the provider prefix.

valid_providers()

Returns the list of valid provider keys.

validation_changeset(endpoint)

Creates a changeset for updating the last_validated_at timestamp.

Types

t()

@type t() :: %PhoenixKitAI.Endpoint{
  __meta__: term(),
  api_key: term(),
  base_url: term(),
  description: term(),
  dimensions: term(),
  enabled: term(),
  frequency_penalty: term(),
  image_quality: term(),
  image_size: term(),
  inserted_at: term(),
  integration_uuid: term(),
  last_validated_at: term(),
  max_tokens: term(),
  model: term(),
  name: term(),
  presence_penalty: term(),
  provider: term(),
  provider_settings: term(),
  reasoning_effort: term(),
  reasoning_enabled: term(),
  reasoning_exclude: term(),
  reasoning_max_tokens: term(),
  repetition_penalty: term(),
  requests: term(),
  seed: term(),
  sort_order: term(),
  stop: term(),
  temperature: term(),
  top_k: term(),
  top_p: term(),
  updated_at: term(),
  uuid: term()
}

Functions

changeset(endpoint, attrs)

Creates a changeset for endpoint creation and updates.

default_base_url(provider)

@spec default_base_url(String.t()) :: String.t() | nil

Returns the default base URL for a provider, read from the Integrations registry (PhoenixKit.Integrations.Providers.base_url/1).

All :ai_completions providers expose an OpenAI-compatible chat completions endpoint at <base>/chat/completions, so the same Completion HTTP layer works for them. Returns nil when the registry has no base URL for the key (e.g. a legacy integration-uuid provider value) — the operator can still set base_url manually on the endpoint.

image_quality_options()

Returns image quality options for form selects.

image_size_options()

Returns image size options for form selects.

kind(model)

@spec kind(t() | String.t() | nil) :: :chat | :tts | :embedding

Classifies an endpoint by the kind of model it points at.

Endpoints don't store a model type, so this infers it from the model id using the same heuristic the model picker uses (see PhoenixKitAI.OpenRouterClient :tts filter): a tts substring marks text-to-speech, embed marks an embedding model, and everything else is treated as chat/completion. Used to badge rows in the admin UI.

kind_icon(atom)

@spec kind_icon(:chat | :tts | :embedding) :: String.t()

Heroicon name representing an endpoint kind/1.

masked_api_key(api_key)

@spec masked_api_key(String.t() | nil) :: String.t()

Masks the API key for display.

  • nil or "" → "Not set".
  • Keys shorter than 14 chars → "•••" (a 13-char key would otherwise leak most of itself with the head+tail shape).
  • Longer keys → first 8 + … + last 4 (e.g. "sk-or-v1…mnop"). Recognisable provider prefix retained, identifying suffix retained, middle elided. Useful for human-recognition in admin cards while still hiding the bulk of the secret.

provider_label(provider)

@spec provider_label(String.t()) :: String.t()

Returns a display label for the provider, read from the Integrations registry (the provider's name).

Unknown providers — e.g. a legacy integration uuid stored in the column — fall back to the raw string. Brand names stay effectively un-translated: registry names are gettext strings, but product trademarks like "OpenRouter" / "Mistral" have no translations, so gettext returns them verbatim rather than producing mixed "OpenRouter Соединение" strings.

provider_options()

@spec provider_options() :: [{String.t(), String.t()}]

Returns provider options ({label, key}) for form selects.

Built from the same capability-discovered list as valid_providers/0; labels come from each provider's registry name.

reasoning_effort_options()

Returns reasoning effort options for form selects.

recently_validated?(endpoint)

Checks if the endpoint has been validated recently (within the last 24 hours).

short_model_name(model)

Extracts the model name without the provider prefix.

valid_providers()

@spec valid_providers() :: [String.t()]

Returns the list of valid provider keys.

Discovered from the Integrations registry — every provider declaring the :ai_completions capability (built-in, or contributed by an external module via integration_providers/0). Adding a chat provider to the registry makes it valid here automatically; nothing is hardcoded.

validation_changeset(endpoint)

Creates a changeset for updating the last_validated_at timestamp.