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

Shared execution boundary for native provider calls and host-app callbacks.

# `request`

```elixir
@type request() :: %{
  optional(:documents) => [Aludel.Evals.TestCaseDocument.t()],
  optional(:messages) => [map()],
  optional(:metadata) => map(),
  kind: :run | :suite,
  prompt_version: Aludel.Prompts.PromptVersion.t(),
  variables: map(),
  provider: Aludel.Providers.Provider.t()
}
```

# `result`

```elixir
@type result() :: %{
  output: String.t(),
  input_tokens: non_neg_integer() | nil,
  output_tokens: non_neg_integer() | nil,
  latency_ms: non_neg_integer() | nil,
  cost_usd: float() | nil,
  metadata: map() | nil,
  artifacts: map()
}
```

# `execute`

```elixir
@spec execute(request()) :: {:ok, result()} | {:error, term()}
```

Executes one provider request through the configured execution mode.

Native mode renders the prompt and calls the configured provider. Callback
mode sends a sanitized input map to the host application's executor. Expected
failures return `{:error, reason}`.

# `execute_with_artifacts`

```elixir
@spec execute_with_artifacts(request()) :: {:ok, result()} | {:error, term(), map()}
```

Executes a provider request while retaining diagnostic artifacts on failure.

Documents are loaded concurrently before dispatch. Validation, storage,
configuration, provider, and callback failures return
`{:error, reason, artifacts}` so callers can persist the attempted input and
failure context.

---

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