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

Multi-objective prompt analysis and failure-grounded prompt suggestions.

Pareto analysis compares eligible prompt versions across pass rate, cost per
passed test, and latency per passed test. Reflection builds bounded evidence
from failed suite results, generates a variable-preserving suggestion, and
requires an explicit accept or dismiss transition.

# `accept_suggestion`

```elixir
@spec accept_suggestion(binary(), binary() | nil) ::
  {:ok, Aludel.Prompts.PromptSuggestion.t()} | {:error, term()}
```

Accepts a pending suggestion and creates an immutable prompt version.

Pass `prompt_id` to scope the transition when accepting from a prompt-specific
interface. Concurrent and repeated transitions return an error.

# `analyze`

```elixir
@spec analyze([map()]) :: %{candidates: [map()], frontier: [map()]}
```

Classifies prompt-version metrics by multi-objective Pareto status.

Candidates missing pass rate, cost per passed test, or latency per passed test
are marked `:insufficient`. Eligible candidates are marked `:frontier` unless
another candidate is no worse on every objective and better on at least one.

# `create_suggestion`

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

Persists a prompt suggestion from validated attributes.

Most callers should use `generate_suggestion/3`, which constructs a suggestion
from bounded evaluation evidence.

# `dismiss_suggestion`

```elixir
@spec dismiss_suggestion(binary(), binary() | nil) ::
  {:ok, Aludel.Prompts.PromptSuggestion.t()} | {:error, term()}
```

Dismisses a pending suggestion without creating a prompt version.

Pass `prompt_id` to scope the transition when dismissing from a
prompt-specific interface. Concurrent and repeated transitions return an
error.

# `generate_suggestion`

```elixir
@spec generate_suggestion(binary(), binary(), binary()) ::
  {:ok, Aludel.Prompts.PromptSuggestion.t()} | {:error, term()}
```

Generates a prompt revision from recent failed suite results.

The source version and suite must belong to the same prompt. Only one pending
suggestion is allowed for a source-version, suite, and provider combination.
No suggestion is persisted when evidence is unavailable or the generated
template fails validation.

# `list_suggestions`

```elixir
@spec list_suggestions(binary()) :: [Aludel.Prompts.PromptSuggestion.t()]
```

Lists prompt suggestions newest first with their related records preloaded.

---

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