# `Aludel.Prompts`
[🔗](https://github.com/ccarvalho-eng/aludel/blob/main/lib/aludel/prompts.ex#L1)

Context for managing prompts and their versions.

# `change_prompt`

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

Returns a changeset for tracking prompt changes.

# `create_prompt`

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

Creates a new prompt.

# `create_prompt_version`

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

# `create_prompt_with_initial_version`

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

# `delete_prompt`

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

Deletes a prompt.

# `extract_variables`

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

# `get_evolution_metrics`

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

# `get_prompt!`

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

Gets a prompt by ID, raising if not found.

# `get_prompt_version!`

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

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

Preloads the associated prompt.

# `get_prompt_with_versions!`

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

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

# `list_prompts`

```elixir
@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

# `list_prompts`

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

# `list_prompts_with_versions`

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

Lists all prompts with their versions preloaded.

Versions are ordered by version number descending.

# `update_prompt`

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

Updates an existing prompt.

# `update_prompt_with_optional_version`

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

---

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