@spec change_prompt(Aludel.Prompts.Prompt.t(), map()) :: Ecto.Changeset.t()

Returns a changeset for tracking prompt changes.

@spec create_prompt(map()) ::
  {:ok, Aludel.Prompts.Prompt.t()} | {:error, Ecto.Changeset.t()}

Creates a new prompt.

@spec create_prompt_version(Aludel.Prompts.Prompt.t(), String.t()) ::
  {:ok, Aludel.Prompts.PromptVersion.t()} | {:error, Ecto.Changeset.t()}

Creates a new version of a prompt.

Auto-increments the version number and extracts variables from the template.

@spec create_prompt_with_initial_version(map()) ::
  {:ok, Aludel.Prompts.Prompt.t()} | {:error, Ecto.Changeset.t()}

Creates a prompt and its initial version in a single transaction.

Blank templates do not create an initial prompt version.

@spec delete_prompt(Aludel.Prompts.Prompt.t()) ::
  {:ok, Aludel.Prompts.Prompt.t()} | {:error, Ecto.Changeset.t()}

Deletes a prompt.

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

Extracts variable names from a template.

Variables are identified by {{variable_name}} syntax. Returns unique variable names in order of first appearance.

@spec get_evolution_metrics(binary()) :: [map()]

Returns aggregated evolution metrics for all versions of a prompt.

Includes pass rates, cost, latency, and per-provider breakdown.

@spec get_prompt!(binary()) :: Aludel.Prompts.Prompt.t()

Gets a prompt by ID, raising if not found.

@spec get_prompt_version!(binary()) :: Aludel.Prompts.PromptVersion.t()

Gets a prompt version by ID, raising if not found.

Preloads the associated prompt.

@spec get_prompt_with_versions!(binary()) :: Aludel.Prompts.Prompt.t()

Gets a prompt with all versions preloaded, ordered by version descending.

@spec list_prompts() :: [Aludel.Prompts.Prompt.t()]

Lists all prompts in the system.

When called without params, returns all prompts as a list. When called with filter params, returns the filtered prompt list.

Options

• :search - Case-insensitive search applied to prompt name and description
• :tags - Filter by any matching prompt tag
• :project_id - Filter by project ID

@spec list_prompts_with_versions() :: [Aludel.Prompts.Prompt.t()]

Lists all prompts with their versions preloaded.

Versions are ordered by version number descending.

@spec update_prompt(Aludel.Prompts.Prompt.t(), map()) ::
  {:ok, Aludel.Prompts.Prompt.t()} | {:error, Ecto.Changeset.t()}

Updates an existing prompt.

@spec update_prompt_with_optional_version(Aludel.Prompts.Prompt.t(), map()) ::
  {:ok, Aludel.Prompts.Prompt.t()} | {:error, Ecto.Changeset.t()}

Updates a prompt and creates a new version if the template changed.

The prompt update and optional version creation run in a single transaction.