Class: Zephira::Tools::BaseTool

Inherits:
Object
  • Object
show all
Defined in:
lib/zephira/tools/base_tool.rb

Defined Under Namespace

Classes: ToolUseError

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args:, agent:) ⇒ BaseTool

Returns a new instance of BaseTool.



10
11
12
13
 
# File 'lib/zephira/tools/base_tool.rb', line 10

def initialize(args:, agent:)
  @args = args
  @agent = agent
end

Instance Attribute Details

#agent ⇒ Object (readonly)

Returns the value of attribute agent.



8
9
10
 
# File 'lib/zephira/tools/base_tool.rb', line 8

def agent
  @agent
end

#args ⇒ Object (readonly)

Returns the value of attribute args.



8
9
10
 
# File 'lib/zephira/tools/base_tool.rb', line 8

def args
  @args
end

Class Method Details

.announces_intent? ⇒ Boolean

Override to false in tools that emit their own per-item status lines (e.g. one line per query). Suppresses the auto-printed ‘→ intent` line that BaseTool.run emits before #run.

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/zephira/tools/base_tool.rb', line 99

def announces_intent?
  true
end

.description ⇒ Object

Raises:

  • (NotImplementedError) 


81
82
83
 
# File 'lib/zephira/tools/base_tool.rb', line 81

def description
  raise NotImplementedError, "This method should be overridden in a subclass"
end

.name ⇒ Object

Raises:

  • (NotImplementedError) 


77
78
79
 
# File 'lib/zephira/tools/base_tool.rb', line 77

def name
  raise NotImplementedError, "This method should be overridden in a subclass"
end

.parameters ⇒ Object

Raises:

  • (NotImplementedError) 


85
86
87
 
# File 'lib/zephira/tools/base_tool.rb', line 85

def parameters
  raise NotImplementedError, "This method should be overridden in a subclass"
end

.read_only? ⇒ Boolean

Override and return true in read-only tools so the agent can run them concurrently. Anything that mutates filesystem, network state, memory store, or agent state must remain false (the default).

Returns:

  • (Boolean) 


92
93
94
 
# File 'lib/zephira/tools/base_tool.rb', line 92

def read_only?
  false
end

.run(args:, agent:) ⇒ Object 



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/zephira/tools/base_tool.rb', line 52

def run(args:, agent:)
  result = begin
    tool_instance = new(args: args, agent: agent)
    intent_value = tool_instance.arg(:intent)
    tool_instance.validate(intent_value, arg_path: "args[:intent]", type: String)
    agent.update_status(Formatter.color(:green, "→ ") + intent_value) if announces_intent?
    tool_instance.run
  rescue => exception
    log_message = "Tool call `#{name}` with args `#{args.inspect}` returned error: #{exception.message}"
    agent.logger.warn(log_message)
    agent.status.warn("ERROR: Tool call `#{name}` returned error: #{exception.message}")
    return {outcome: "error", error: exception.message, data: nil}
  end

  if result[:outcome] == "success"
    agent.logger.info("Tool call `#{name}` with args `#{args.inspect}` completed successfully: #{result[:data]}")
    agent.status.verbose("Tool call `#{name}` completed successfully")
  elsif result[:outcome] == "error"
    agent.logger.warn("Tool call `#{name}` with args `#{args.inspect}` returned error: #{result[:error]}")
    agent.status.warn("ERROR: Tool call `#{name}` returned error: #{result[:error]}")
  end

  result
end

Instance Method Details

#arg(name) ⇒ Object 



15
16
17
 
# File 'lib/zephira/tools/base_tool.rb', line 15

def arg(name)
  @args[name] || @args[name.to_s]
end

#error_result(message:) ⇒ Object 



43
44
45
 
# File 'lib/zephira/tools/base_tool.rb', line 43

def error_result(message:)
  {outcome: "error", error: message, data: nil}
end

#run ⇒ Object

Raises:

  • (NotImplementedError) 


39
40
41
 
# File 'lib/zephira/tools/base_tool.rb', line 39

def run
  raise NotImplementedError, "This method should be overridden in a subclass"
end

#success_result(data) ⇒ Object 



47
48
49
 
# File 'lib/zephira/tools/base_tool.rb', line 47

def success_result(data)
  {outcome: "success", error: nil, data: data}
end

#validate(actual, arg_path:, type:, allow_nil: false, allow_empty: false) ⇒ Object 



19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/zephira/tools/base_tool.rb', line 19

def validate(actual, arg_path:, type:, allow_nil: false, allow_empty: false)
  if !allow_nil && actual.nil?
    raise ToolUseError, "argument `#{arg_path}` must be supplied"
  end

  unless actual.is_a?(type)
    raise ToolUseError, "argument `#{arg_path}` must be of type #{type} and non-empty"
  end

  if !allow_empty && type == String && actual.strip.empty?
    raise ToolUseError, "argument `#{arg_path}` must be of type #{type} and non-empty"
  end

  if !allow_empty && actual.respond_to?(:empty?) && actual.empty?
    raise ToolUseError, "argument `#{arg_path}` must be of type #{type} and non-empty"
  end

  actual
end