Runs and Execution

Aludel runs one immutable prompt version with one variable set across one or more providers. Native execution calls provider adapters directly; callback execution invokes the host application's real workflow.

Run a Prompt in the UI

1. Open a prompt and select Run.
2. Enter each {{variable}} value.
3. Select one or more providers.
4. Start the run and watch each result update independently.

Each provider result records status, output, tokens, latency, estimated cost, callback metadata, and a normalized execution artifact. When only some providers fail, the run is marked as a partial failure and successful results remain available.

Dispatch and Lifecycle

Run states are pending, running, completed, partial_failure, and failed. Provider result states are pending, running, completed, and error.

Multi-provider calls are concurrent by default:

config :aludel,
  run_execution_mode: :concurrent

config :aludel, :llm,
  max_concurrency: 5,
  request_timeout_ms: 120_000

The defaults are three concurrent calls and a 120-second timeout. Set run_execution_mode: :sequential when calls must not overlap.

Native Execution

Native mode is the default:

config :aludel, execution_mode: :native

Aludel renders the selected template, loads any suite documents, calls the provider adapter, calculates cost from token counts and effective pricing, and normalizes the result.

App Callback Execution

Use callback mode when production behavior includes retrieval, tools, routing, retries, or post-processing:

config :aludel,
  execution_mode: :callback,
  executor: MyApp.AludelExecutor

defmodule MyApp.AludelExecutor do
  @behaviour Aludel.Executor

  @impl true
  def run(input) do
    case MyApp.AI.reply(%{
           variables: input.variables,
           messages: input.messages,
           documents: input.documents,
           model: input.provider && input.provider.model,
           context: input.metadata
         }) do
      {:ok, reply} ->
        {:ok, %{output: reply.text, metadata: %{trace_id: reply.trace_id}}}

      {:error, reason} ->
        {:error, reason}
    end
  end
end

Only output is required. Optional fields are input_tokens, output_tokens, latency_ms, cost_usd, and metadata. Missing metrics render as N/A.

Direct Execution API

Library callers can execute the same native or callback boundary without creating a run first:

prompt_version = Aludel.Prompts.get_prompt_version!(prompt_version_id)
provider = Aludel.Providers.get_provider!(provider_id)

request = %{
  kind: :run,
  prompt_version: prompt_version,
  provider: provider,
  variables: %{"question" => "Which planet is known as the Red Planet?"},
  messages: [],
  documents: [],
  metadata: %{trace_id: "eval-42"}
}

case Aludel.Execution.execute(request) do
  {:ok, result} -> result.output
  {:error, reason} -> {:error, reason}
end

Use Aludel.Execution.execute_with_artifacts/1 when an integration needs the normalized attempted input and bounded failure evidence even when execution fails:

case Aludel.Execution.execute_with_artifacts(request) do
  {:ok, result} -> {:ok, result}
  {:error, reason, artifacts} -> {:error, reason, artifacts}
end

Execution Artifacts

Artifacts provide a stable, JSON-encodable trace of one execution step:

• native, callback, or unavailable mode
• prompt version, variables, messages, provider, document metadata, and caller metadata
• raw output and parsed JSON when valid
• metric results and aggregate score for suite cases
• bounded structured errors

Artifacts are included in run and suite exports. They record document names, content types, and sizes, not document bytes.

Inspect and Export

The run page supports copying output or errors and downloading a JSON result. See Exports and CI for the export contract.

Related Pages

• Providers
• Evaluation Suites
• Embedding and Access