Prompts

Templates with variable interpolation executed across multiple LLM providers.

Structure

• name - String identifier
• description - Purpose
• tags - Array of strings (optional)
• project_id - Foreign key to a typed :prompt project (optional)

template is authored through prompt versions. The prompt itself is the stable container, while each template revision is stored as a separate immutable PromptVersion.

Creating Prompts

Aludel.Prompts.create_prompt(%{
  name: "Gandalf's Light",
  tags: ["you-shall-not-pass", "fellowship"]
})

{:ok, prompt} =
  Aludel.Prompts.create_prompt(%{
    name: "Gandalf's Light",
    tags: ["you-shall-not-pass", "fellowship"]
  })

Aludel.Prompts.create_prompt_version(
  prompt,
  "{{language}}! Speak, friend, and enter:\n\n{{code}}"
)

Variable Syntax

{{variable_name}} - Alphanumeric and underscores only, case-sensitive.

Valid: {{article}}, {{user_input}}, {{item1}} Invalid: {{user input}}, {{user-input}}

Variables extracted automatically:

Aludel.Prompts.extract_variables("Translate {{text}} to {{language}}")
# => ["text", "language"]

Provide variable values as map:

%{"text" => "Hello", "language" => "Spanish"}
# Result: "Translate Hello to Spanish"

Versioning

Edits create immutable versions automatically when the template changes. The current prompt body is always represented by the latest PromptVersion, while older versions remain available for comparison.

The prompt detail page can compare any two versions side by side. The Evolution page adds:

• pass rate and structured-output score by version
• cost and latency trends overall or by provider
• version-over-version deltas and regression/stability signals
• suite-scoped quality/cost/latency Pareto analysis
• failure-grounded prompt suggestions with explicit accept or dismiss decisions
• JSON and CSV exports

Tags and Projects

# Tags
tags: ["summarization", "articles"]

# Projects (grouping)
{:ok, project} = Aludel.Projects.create_project(%{name: "Marketing", type: :prompt})
Aludel.Prompts.create_prompt(%{project_id: project.id, ...})

Projects are typed. Prompt screens create and display :prompt projects, while suite screens use separate :suite projects.

Prompt index filters apply before pagination and preserve project, search, and tag selections in the URL. Projects can be created, renamed, expanded, filtered, and deleted from the catalog.

Failure Reflection

When a suite has failed results, open Evolution, select the suite and a provider, and generate a suggestion. Aludel sends bounded failure evidence to the selected provider and requires the response to preserve the source template variables.

A suggestion records its proposed template, rationale, failure summary, source version, suite, provider, and status. Accepting creates a new immutable version; dismissing preserves the decision without changing the prompt.

API Reference

# CRUD
create_prompt(attrs)
update_prompt(prompt, attrs)
delete_prompt(prompt)
get_prompt!(id)
list_prompts()
list_prompts(params)

# Versioning
create_prompt_version(prompt, template)
get_prompt_with_versions!(id)
get_prompt_version!(id)

# Variables
extract_variables(template)

See Analytics and Prompt Evolution for the complete comparison workflow.