Shared helper functions for Jido.AI skill actions.
This module provides common functionality used across multiple action modules to reduce code duplication and ensure consistent behavior.
Functions
resolve_model/2- Resolve model alias to specbuild_opts/2- Build options for LLM requestsextract_text/1- Extract text from LLM responseextract_usage/1- Extract usage information from responsevalidate_and_sanitize_input/2- Validate input with security checks
Examples
use Jido.AI.Actions.Helpers
# In an action
def run(params, _context) do
with {:ok, model} <- resolve_model(params[:model], :fast),
{:ok, messages} <- build_messages(params),
opts <- build_opts(params),
{:ok, response} <- ReqLLM.Generation.generate_text(model, messages, opts) do
{:ok, format_result(response)}
end
endSummary
Functions
Builds ReqLLM options from action parameters.
Extracts text content from an LLM response.
Extracts usage information from an LLM response.
Formats a result with error sanitization.
Resolves a model parameter to a model spec.
Sanitizes an error for user-facing display.
Classifies action-layer LLM errors into canonical telemetry error types.
Builds canonical AI telemetry metadata for direct LLM actions.
Validates and sanitizes input parameters with security checks.
Functions
Builds ReqLLM options from action parameters.
Parameters
params- Map containing :max_tokens, :temperature, :timeout keys
Returns
Keyword list of options for ReqLLM
Examples
iex> build_opts(%{max_tokens: 1000, temperature: 0.5})
[max_tokens: 1000, temperature: 0.5]
iex> build_opts(%{max_tokens: 1000, temperature: 0.5, timeout: 5000})
[max_tokens: 1000, temperature: 0.5, receive_timeout: 5000]Extracts text content from an LLM response.
Delegates to Jido.AI.Turn.extract_text/1 which handles
multiple response shapes consistently.
Parameters
response- LLM response map
Returns
Extracted text string
Examples
iex> extract_text(%{message: %{content: "Hello"}})
"Hello"
iex> extract_text(%{message: %{content: [%{type: :text, text: "Hi"}]}})
"Hi"Extracts usage information from an LLM response.
Parameters
response- LLM response map
Returns
Map with :input_tokens, :output_tokens, :total_tokens keys
Examples
iex> extract_text(%{usage: %{input_tokens: 10, output_tokens: 20}})
%{input_tokens: 10, output_tokens: 20, total_tokens: 30}Formats a result with error sanitization.
If the result is {:ok, }, returns it as-is. If the result is {:error, }, sanitizes the error message.
Parameters
result- The result tuple to format
Returns
Formatted result tuple
Examples
iex> format_result({:ok, %{text: "Hello"}})
{:ok, %{text: "Hello"}}
iex> format_result({:error, %RuntimeError{message: "Internal"}})
{:error, "An error occurred"}Resolves a model parameter to a model spec.
Parameters
model- Model alias or direct ReqLLM model inputdefault- Default model alias to use if model is nil
Returns
{:ok, model_input}- Successfully resolved model{:error, :invalid_model_format}- Invalid model format
Examples
iex> resolve_model(nil, :fast)
{:ok, "anthropic:claude-haiku-4-5"}
iex> resolve_model(:capable, :fast)
{:ok, "anthropic:claude-sonnet-4-20250514"}
iex> resolve_model("openai:gpt-4", :fast)
{:ok, "openai:gpt-4"}Sanitizes an error for user-facing display.
Uses Jido.AI.Error.Sanitize.sanitize_error_message/1 to convert
detailed errors into generic user-safe messages.
Parameters
error- The error term to sanitize
Returns
Sanitized error message string
Examples
iex> sanitize_error(%RuntimeError{message: "Internal error"})
"An error occurred"
iex> sanitize_error(:timeout)
"Request timed out"Classifies action-layer LLM errors into canonical telemetry error types.
Builds canonical AI telemetry metadata for direct LLM actions.
Validates and sanitizes input parameters with security checks.
Parameters
params- Map of input parametersopts- Validation options::required_prompt- Whether prompt is required (default: true):required_system_prompt- Whether system_prompt must be validated if present:max_prompt_length- Max length for prompt (default: Validation.max_input_length()):max_system_prompt_length- Max length for system_prompt (default: Validation.max_prompt_length())
Returns
{:ok, params}- Validation passed{:error, reason}- Validation failed
Examples
iex> validate_and_sanitize_input(%{prompt: "Hello"})
{:ok, %{prompt: "Hello"}}
iex> validate_and_sanitize_input(%{prompt: ""})
{:error, :prompt_required}