Module: ActiveAgent::View

Extended by:
ActiveSupport::Concern
Included in:
Base
Defined in:
lib/active_agent/concerns/view.rb

Overview

Provides template lookup and rendering for agent classes.

Enables agents to render instructions, schemas, and messages from ERB templates with flexible directory structures and fallback paths.

Instance Method Summary collapse

Instance Method Details

#_prefixes ⇒ Array<String>

Builds template lookup paths supporting both flat and nested directory structures.

Templates are searched in priority order:

  • ‘app/views/agent_name/` (e.g., `app/views/support_agent/`)

  • ‘app/views/agents/agent_without_suffix/` (e.g., `app/views/agents/support/`)

With action_name present:

  • ‘app/views/agents/agent_without_suffix/action_name/`

  • ‘app/views/agent_name/action_name/`

  • ‘app/views/agent_name/`

  • ‘app/views/agents/agent_without_suffix/`

Returns:

  • (Array<String>) —

    ordered prefixes for template lookup



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/active_agent/concerns/view.rb', line 28

def _prefixes
  @_prefixes ||= begin
    # Get the base agent name (e.g., "statements_agent" or "view_test/test_agent")
    base = agent_name

    # Build the nested structure under agents/
    # e.g., "agents/statements" for StatementsAgent
    nested = "agents/#{base.delete_suffix("_agent")}"

    # Build prefixes with action_name if present
    if action_name.present?
      # Priority order: nested/action, base/action, base, nested
      [  "#{nested}/#{action_name}", "#{base}/#{action_name}", base, nested ]
    else
      # Priority order: base, nested
      [ nested, base ]
    end
  end
end

#embed_view_input(action_name, **locals) ⇒ String?

Renders template for embedding input.

Parameters:

  • action_name (String, Symbol)
  • locals (Hash)

Returns:

  • (String, nil) 


121
122
123
 
# File 'lib/active_agent/concerns/view.rb', line 121

def embed_view_input(action_name, **locals)
  view_render_template(action_name, **locals)
end

#prompt_view_instructions(value) ⇒ String, ...

Prepares instructions from various input formats.

Supported formats:

  • ‘String`: returned as-is

  • ‘Symbol`: invokes method with that name (like ActiveRecord callbacks)

  • ‘Array<String>`: returned as-is if all elements are strings

  • ‘Hash`: requires `:template` key, optional `:locals`

  • ‘nil` or `true`: renders default “instructions” template

Parameters:

  • value (Hash, String, Symbol, Array<String>, Boolean, nil)

Returns:

  • (String, Array<String>, nil) —

    nil if template not found

Raises:

  • (ArgumentError) —

    if format is invalid or Hash missing :template key



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/active_agent/concerns/view.rb', line 62

def prompt_view_instructions(value)
  case value
  when String
    value.presence

  when Symbol
    send(value)

  when Array
    raise ArgumentError, "Instructions array must contain only strings" unless value.all?(String)
    value.presence

  when Hash
    view_render_template(value[:template] || "instructions",  strict: true, **value[:locals])

  when nil, true
    view_render_template("instructions", strict: value == true, **(params.dig(:instructions, :locals) || {}))

  else
    raise ArgumentError, "Instructions must be Hash, String, Symbol or nil"
  end
end

#prompt_view_message(action_name, strict:, **locals) ⇒ String?

Renders template for a prompt action or message.

Parameters:

  • action_name (String, Symbol)
  • locals (Hash)

Returns:

  • (String, nil) 


92
93
94
 
# File 'lib/active_agent/concerns/view.rb', line 92

def prompt_view_message(action_name, strict:, **locals)
  view_render_template(action_name, strict:, **locals)
end

#prompt_view_schema(value) ⇒ Hash, ...

Renders JSON schema from template or returns Hash directly.

Schema templates are looked up as ‘name.json`:

  • When value is ‘true` or `nil`: looks for `action_name.json`

  • When value is a String/Symbol: looks for ‘value.json`

  • When value is a Hash: returns the Hash directly

Parameters:

  • value (Hash, String, Symbol, Boolean, nil)

Returns:

  • (Hash, String, nil) 


105
106
107
108
109
110
111
112
113
114
 
# File 'lib/active_agent/concerns/view.rb', line 105

def prompt_view_schema(value)
  case value
  when Hash
    value
  when String, Symbol
    JSON.parse(view_render_template(value, strict: true, formats: [ :json ]), symbolize_names: true)
  when true, nil
    JSON.parse(view_render_template(action_name, strict: true, formats: [ :json ]), symbolize_names: true)
  end
end