Class: OllamaAgent::Core::ActionEnvelope

Inherits:
Object
  • Object
show all
Defined in:
lib/ollama_agent/core/action_envelope.rb

Overview

Wraps every structured response from the planner. Enforces a fixed contract so the runner stays deterministic.

Types:

:tool_call        — execute a tool with args
:final            — model is done; surface content to the user
:ask_clarification— model needs more info before proceeding
:error            — unrecoverable error in the action
:handoff          — delegate to another agent

Constant Summary collapse

VALID_TYPES = 
%i[tool_call final ask_clarification error handoff].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(type:, payload:, confidence: nil, envelope_id: nil) ⇒ ActionEnvelope

Returns a new instance of ActionEnvelope.

Raises:

  • (ArgumentError) 


19
20
21
22
23
24
25
26
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 19

def initialize(type:, payload:, confidence: nil, envelope_id: nil)
  raise ArgumentError, "Unknown action type: #{type}" unless VALID_TYPES.include?(type.to_sym)

  @type        = type.to_sym
  @payload     = payload
  @confidence  = confidence
  @envelope_id = envelope_id || generate_id
end

Instance Attribute Details

#confidence ⇒ Object (readonly)

Returns the value of attribute confidence.



17
18
19
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 17

def confidence
  @confidence
end

#envelope_id ⇒ Object (readonly)

Returns the value of attribute envelope_id.



17
18
19
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 17

def envelope_id
  @envelope_id
end

#payload ⇒ Object (readonly)

Returns the value of attribute payload.



17
18
19
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 17

def payload
  @payload
end

#type ⇒ Object (readonly)

Returns the value of attribute type.



17
18
19
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 17

def type
  @type
end

Class Method Details

.ask_clarification(question:) ⇒ Object 



38
39
40
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 38

def self.ask_clarification(question:)
  new(type: :ask_clarification, payload: { question: question.to_s })
end

.error(message:, cause: nil) ⇒ Object 



42
43
44
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 42

def self.error(message:, cause: nil)
  new(type: :error, payload: { message: message.to_s, cause: cause })
end

.final(content:) ⇒ Object 



34
35
36
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 34

def self.final(content:)
  new(type: :final, payload: { content: content.to_s })
end

.handoff(agent:, query:) ⇒ Object 



46
47
48
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 46

def self.handoff(agent:, query:)
  new(type: :handoff, payload: { agent: agent.to_s, query: query.to_s })
end

.tool_call(tool:, args:, confidence: nil) ⇒ Object

— Factory constructors —



30
31
32
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 30

def self.tool_call(tool:, args:, confidence: nil)
  new(type: :tool_call, payload: { tool: tool.to_s, args: args || {} }, confidence: confidence)
end

Instance Method Details

#args ⇒ Object 



61
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 61

def args    = @payload[:args] || {}

#ask_clarification? ⇒ Boolean

Returns:

  • (Boolean) 


54
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 54

def ask_clarification? = @type == :ask_clarification

#content ⇒ Object 



62
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 62

def content = @payload[:content]

#error? ⇒ Boolean

Returns:

  • (Boolean) 


55
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 55

def error?            = @type == :error

#final? ⇒ Boolean

Returns:

  • (Boolean) 


53
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 53

def final?            = @type == :final

#handoff? ⇒ Boolean

Returns:

  • (Boolean) 


56
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 56

def handoff?          = @type == :handoff

#message ⇒ Object 



64
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 64

def message = @payload[:message]

#question ⇒ Object 



63
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 63

def question = @payload[:question]

#to_h ⇒ Object 



66
67
68
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 66

def to_h
  { type: @type, payload: @payload, confidence: @confidence, envelope_id: @envelope_id }
end

#to_s ⇒ Object 



70
71
72
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 70

def to_s
  "#<ActionEnvelope type=#{@type} id=#{@envelope_id}>"
end

#tool ⇒ Object

— Accessors for common payload fields —



60
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 60

def tool    = @payload[:tool]

#tool_call? ⇒ Boolean

— Predicate helpers —

Returns:

  • (Boolean) 


52
 
# File 'lib/ollama_agent/core/action_envelope.rb', line 52

def tool_call?        = @type == :tool_call