Jido.AI.Actions.LLM.GenerateObject (Jido AI v2.2.0)

Copy Markdown View Source

A Jido.Action for generating structured JSON objects using LLM with schema validation.

This action wraps ReqLLM.generate_object/4 for schema-constrained generation, returning validated JSON objects that conform to a provided schema.

Parameters

  • model (optional) - Model alias (e.g., :fast, :capable) or direct spec (e.g., "anthropic:claude-haiku-4-5")
  • prompt (required) - The prompt describing what object to generate
  • object_schema (required) - Zoi schema or NimbleOptions keyword list defining the expected structure
  • system_prompt (optional) - System prompt to guide the LLM's behavior
  • max_tokens (optional) - Maximum tokens to generate (default: 1024)
  • temperature (optional) - Sampling temperature 0.0-2.0 (default: 0.7)
  • timeout (optional) - Request timeout in milliseconds

Examples

# Basic object generation with Zoi schema
schema = Zoi.object(%{
  name: Zoi.string(),
  age: Zoi.integer(),
  occupation: Zoi.string()
})

{:ok, result} = Jido.Exec.run(Jido.AI.Actions.LLM.GenerateObject, %{
  prompt: "Generate a person named Alice who is a software engineer",
  object_schema: schema
})
# => %{object: %{name: "Alice", age: 28, occupation: "Software Engineer"}, ...}

# With model and system prompt
{:ok, result} = Jido.Exec.run(Jido.AI.Actions.LLM.GenerateObject, %{
  model: :capable,
  prompt: "Generate a product review",
  object_schema: review_schema,
  system_prompt: "You are generating structured product review data.",
  temperature: 0.5
})

Result Format

%{
  object: %{name: "Alice", age: 28, occupation: "Software Engineer"},
  model: "anthropic:claude-haiku-4-5",
  usage: %{
    input_tokens: 25,
    output_tokens: 15,
    total_tokens: 40
  }
}

Summary

Functions

__action_metadata__()

Returns the Action metadata. Alias for to_json/0.

category()

Returns the category of the Action.

description()

Returns the description of the Action.

name()

Returns the name of the Action.

on_after_run(result)

Lifecycle hook called after Action execution.

on_after_validate_output(output)

Lifecycle hook called after output validation.

on_after_validate_params(params)

Lifecycle hook called after parameter validation.

on_before_validate_output(output)

Lifecycle hook called before output validation.

on_before_validate_params(params)

Lifecycle hook called before parameter validation.

on_error(failed_params, error, context, opts)

Lifecycle hook called when an error occurs.

output_schema()

Returns the output schema of the Action.

run(params, context)

Executes the generate_object action.

schema()

Returns the input schema of the Action.

tags()

Returns the tags associated with the Action.

to_json()

Returns the Action metadata as a JSON-serializable map.

to_tool()

Converts the Action to an LLM-compatible tool format.

validate_output(output)

Validates the output result for the Action.

validate_params(params)

Validates the input parameters for the Action.

vsn()

Returns the version of the Action.

Functions

__action_metadata__()

Returns the Action metadata. Alias for to_json/0.

category()

Returns the category of the Action.

description()

Returns the description of the Action.

name()

Returns the name of the Action.

on_after_run(result)

Lifecycle hook called after Action execution.

on_after_validate_output(output)

Lifecycle hook called after output validation.

on_after_validate_params(params)

Lifecycle hook called after parameter validation.

on_before_validate_output(output)

Lifecycle hook called before output validation.

on_before_validate_params(params)

Lifecycle hook called before parameter validation.

on_error(failed_params, error, context, opts)

Lifecycle hook called when an error occurs.

output_schema()

Returns the output schema of the Action.

run(params, context)

Executes the generate_object action.

Returns

  • {:ok, result} - Successful response with object, model, and usage keys
  • {:error, reason} - Error from ReqLLM or validation

Result Format

%{
  object: %{name: "Alice", age: 28, occupation: "Software Engineer"},
  model: "anthropic:claude-haiku-4-5",
  usage: %{
    input_tokens: 25,
    output_tokens: 15,
    total_tokens: 40
  }
}

schema()

Returns the input schema of the Action.

tags()

Returns the tags associated with the Action.

to_json()

Returns the Action metadata as a JSON-serializable map.

to_tool()

Converts the Action to an LLM-compatible tool format.

validate_output(output)

@spec validate_output(map()) :: {:ok, map()} | {:error, String.t()}

Validates the output result for the Action.

Examples

iex> defmodule ExampleAction do
...>   use Jido.Action,
...>     name: "example_action",
...>     output_schema: [
...>       result: [type: :string, required: true]
...>     ]
...> end
...> ExampleAction.validate_output(%{result: "test", extra: "ignored"})
{:ok, %{result: "test", extra: "ignored"}}

iex> ExampleAction.validate_output(%{extra: "ignored"})
{:error, "Invalid output for Action: Required key :result not found"}

validate_params(params)

@spec validate_params(map()) :: {:ok, map()} | {:error, String.t()}

Validates the input parameters for the Action.

Examples

iex> defmodule ExampleAction do
...>   use Jido.Action,
...>     name: "example_action",
...>     schema: [
...>       input: [type: :string, required: true]
...>     ]
...> end
...> ExampleAction.validate_params(%{input: "test"})
{:ok, %{input: "test"}}

iex> ExampleAction.validate_params(%{})
{:error, "Invalid parameters for Action: Required key :input not found"}

vsn()

Returns the version of the Action.