# `Jido.AI.Directive.Helpers`
[🔗](https://github.com/agentjido/jido_ai/blob/v2.4.0/lib/jido_ai/directive/helpers.ex#L1)

Helper functions for DirectiveExec implementations.

This module centralizes directive runtime helpers for:
- Task supervisor resolution
- Model resolution from directive fields
- Message normalization/building
- Request option assembly
- Error classification

# `add_req_http_options`

```elixir
@spec add_req_http_options(keyword(), list() | nil) :: keyword()
```

Adds req_http_options option to a keyword list if options are specified.

# `add_timeout_opt`

```elixir
@spec add_timeout_opt(keyword(), integer() | nil) :: keyword()
```

Adds timeout option to a keyword list if timeout is specified.

# `add_tools_opt`

```elixir
@spec add_tools_opt(keyword(), list()) :: keyword()
```

Adds tools option to a keyword list if tools are specified.

# `build_directive_messages`

```elixir
@spec build_directive_messages(term(), String.t() | nil) :: list()
```

Builds messages for LLM calls from context and optional system prompt.

# `classify_error`

```elixir
@spec classify_error(term()) :: atom()
```

Classifies an error into a runtime category.

Returns one of: `:rate_limit`, `:auth`, `:timeout`, `:provider_error`,
`:network`, `:validation`, `:unknown`.

# `emit_llm_usage_report`

Emits an `ai.usage` signal for per-call directive usage tracking.

# `finish_llm_complete`

Finishes a successful LLM directive telemetry span and emits completion telemetry.

# `get_task_supervisor`

Gets the task supervisor from agent state.

First checks the TaskSupervisorSkill's internal state (`__task_supervisor_skill__`),
then falls back to the top-level `:task_supervisor` field for standalone usage.

## Examples

    iex> state = %{__task_supervisor_skill__: %{supervisor: supervisor_pid}}
    iex> Jido.AI.Directive.Helpers.get_task_supervisor(state)
    supervisor_pid

    iex> state = %{task_supervisor: supervisor_pid}
    iex> Jido.AI.Directive.Helpers.get_task_supervisor(state)
    supervisor_pid

# `resolve_directive_model`

```elixir
@spec resolve_directive_model(map()) :: String.t()
```

Resolves a model from directive fields.

Supports both direct model specification and model alias resolution.

---

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