Class: Ask::Result

Inherits:
Object
  • Object
show all
Defined in:
lib/ask/result.rb

Overview

Standardized return value from tool execution.

This is the single Ask::Result for the whole ecosystem. It supports both the foundational API (+success+/+failure+/+aborted+/+blocked+ with content and status) and the tool API (+ok+/+error+ with ok?, output, and error_message):

Ask::Result.success("Data processed")
Ask::Result.ok(data: "Data processed")

Both are the same class and share the same to_h shape, so a result created by a provider's embed or a tool's execute can be inspected uniformly.

Feature gems extend this class or build on it — they never redefine it. See ask-docs "Architecture & ownership" for the rule.

Constant Summary collapse

STATUSES = 
%i[success error aborted blocked short_circuited pending].freeze

Instance Attribute Summary collapse

Factory Methods collapse

Instance Method Summary collapse

Constructor Details

#initialize(content: nil, output: nil, status: :success, ok: nil, error: nil, metadata: {}) ⇒ Result

Accepts both the foundational keywords (+content+, status) and the tool keywords (+ok+, output). ok: derives the status: true means :success, false means :error.

Parameters:

  • content (Object, nil) (defaults to: nil) —

    result content

  • output (Object, nil) (defaults to: nil) —

    tool output (takes precedence over content)

  • status (Symbol) (defaults to: :success) —

    result status

  • ok (Boolean, nil) (defaults to: nil) —

    whether the result is a success (derives status)

  • error (Object, nil) (defaults to: nil) —

    error message or underlying error object

  • metadata (Hash) (defaults to: {}) —

    additional metadata



110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/ask/result.rb', line 110

def initialize(content: nil, output: nil, status: :success, ok: nil, error: nil, metadata: {})
  @content = output.nil? ? content : output
  @status = if ok == true
              :success
            elsif ok == false
              :error
            else
              status
            end
  @status = validate_status!(@status)
  @error = error
  @metadata = metadata.dup.freeze
  freeze
end

Instance Attribute Details

#content ⇒ Object? (readonly)

Returns the result content (for +success+/+ok+ results, this is the payload; for failure it is the error message).

Returns:

  • (Object, nil) —

    the result content (for +success+/+ok+ results, this is the payload; for failure it is the error message)



89
90
91
 
# File 'lib/ask/result.rb', line 89

def content
  @content
end

#error ⇒ Object? (readonly)

Returns the error message or underlying error object, if any.

Returns:

  • (Object, nil) —

    the error message or underlying error object, if any



95
96
97
 
# File 'lib/ask/result.rb', line 95

def error
  @error
end

#metadata ⇒ Hash (readonly)

Returns additional metadata.

Returns:

  • (Hash) —

    additional metadata



98
99
100
 
# File 'lib/ask/result.rb', line 98

def metadata
  @metadata
end

#status ⇒ Symbol (readonly)

Returns the status (:success, :error, :aborted, :blocked, :short_circuited).

Returns:

  • (Symbol) —

    the status (:success, :error, :aborted, :blocked, :short_circuited)



92
93
94
 
# File 'lib/ask/result.rb', line 92

def status
  @status
end

Class Method Details

.aborted(reason = "Aborted") ⇒ Ask::Result

Create an aborted result (cancelled by sibling failure).

Parameters:

  • reason (String) (defaults to: "Aborted") —

    the abort reason

Returns:



47
48
49
 
# File 'lib/ask/result.rb', line 47

def aborted(reason = "Aborted")
  new(content: reason, status: :aborted)
end

.blocked(reason) ⇒ Ask::Result

Create a blocked result (prevented by a hook or guard).

Parameters:

  • reason (String) —

    the block reason

Returns:



54
55
56
 
# File 'lib/ask/result.rb', line 54

def blocked(reason)
  new(content: reason, status: :blocked)
end

.error(message:, metadata: {}) ⇒ Ask::Result

Create a failed result (tool API).

Parameters:

  • message (String) —

    description of the failure

  • metadata (Hash) (defaults to: {}) —

    optional metadata

Returns:



81
82
83
 
# File 'lib/ask/result.rb', line 81

def error(message:, metadata: {})
  new(content: message, status: :error, error: message, metadata: metadata)
end

.failure(message, error: nil, metadata: {}) ⇒ Ask::Result

Create a failure result.

Parameters:

  • message (String) —

    the error description

  • error (Object, nil) (defaults to: nil) —

    the underlying error object (defaults to message so failure(msg).error reads as the message)

  • metadata (Hash) (defaults to: {}) —

    additional metadata

Returns:



40
41
42
 
# File 'lib/ask/result.rb', line 40

def failure(message, error: nil, metadata: {})
  new(content: message, status: :error, error: error.nil? ? message : error, metadata: metadata)
end

.ok(data:, metadata: {}) ⇒ Ask::Result

Create a successful result (tool API — alias for success).

Parameters:

  • data (Object) —

    the tool's output

  • metadata (Hash) (defaults to: {}) —

    optional metadata

Returns:



73
74
75
 
# File 'lib/ask/result.rb', line 73

def ok(data:, metadata: {})
  new(content: data, status: :success, metadata: metadata)
end

.pending(message, metadata: {}) ⇒ Ask::Result

Create a pending result (async tool): the work continues in the background and the session completes it later via Ask::Agent::Session#complete_pending_tool. The agent voices the tool's interim message immediately and keeps talking.

Parameters:

  • message (String) —

    interim status the model can voice

  • metadata (Hash) (defaults to: {}) —

    additional metadata

Returns:



65
66
67
 
# File 'lib/ask/result.rb', line 65

def pending(message, metadata: {})
  new(content: message, status: :pending, metadata: metadata)
end

.success(content = nil, metadata: {}) ⇒ Ask::Result

Create a successful result.

Parameters:

  • content (Object, nil) (defaults to: nil) —

    the result content

  • metadata (Hash) (defaults to: {}) —

    additional metadata

Returns:



30
31
32
 
# File 'lib/ask/result.rb', line 30

def success(content = nil, metadata: {})
  new(content: content, status: :success, metadata: metadata)
end

Instance Method Details

#aborted? ⇒ Boolean

Returns true if status is :aborted.

Returns:

  • (Boolean) —

    true if status is :aborted



141
 
# File 'lib/ask/result.rb', line 141

def aborted? = @status == :aborted

#blocked? ⇒ Boolean

Returns true if status is :blocked.

Returns:

  • (Boolean) —

    true if status is :blocked



144
 
# File 'lib/ask/result.rb', line 144

def blocked? = @status == :blocked

#error? ⇒ Boolean

Returns true if status is :error.

Returns:

  • (Boolean) —

    true if status is :error



138
 
# File 'lib/ask/result.rb', line 138

def error? = @status == :error

#error_message ⇒ Object?

Returns the error message or underlying error object.

Returns:

  • (Object, nil) —

    the error message or underlying error object



150
 
# File 'lib/ask/result.rb', line 150

def error_message = @error

#inspect ⇒ String

Returns human-readable representation.

Returns:

  • (String) —

    human-readable representation



168
169
170
171
172
173
174
 
# File 'lib/ask/result.rb', line 168

def inspect
  if @status == :success
    "#<Ask::Result ok=true output=#{@content.inspect}>"
  else
    "#<Ask::Result ok=false error=#{@error.inspect} status=#{@status.inspect}>"
  end
end

#ok ⇒ Boolean

Returns true if the result is a success (tool API).

Returns:

  • (Boolean) —

    true if the result is a success (tool API)



135
 
# File 'lib/ask/result.rb', line 135

def ok = @status == :success

#ok? ⇒ Boolean

Returns true if the result is a success (tool API).

Returns:

  • (Boolean) —

    true if the result is a success (tool API)



129
 
# File 'lib/ask/result.rb', line 129

def ok? = @status == :success

#output ⇒ Object?

Returns the output data when successful, nil otherwise (tool API).

Returns:

  • (Object, nil) —

    the output data when successful, nil otherwise (tool API)



147
 
# File 'lib/ask/result.rb', line 147

def output = @status == :success ? @content : nil

#pending? ⇒ Boolean

Returns true if the result is pending (async tool running).

Returns:

  • (Boolean) —

    true if the result is pending (async tool running)



132
 
# File 'lib/ask/result.rb', line 132

def pending? = @status == :pending

#success? ⇒ Boolean

Returns true if status is :success.

Returns:

  • (Boolean) —

    true if status is :success



126
 
# File 'lib/ask/result.rb', line 126

def success? = @status == :success

#to_h ⇒ Hash

Returns serialized representation.

Returns:

  • (Hash) —

    serialized representation



158
159
160
161
162
163
164
165
 
# File 'lib/ask/result.rb', line 158

def to_h
  {
    ok: @status == :success,
    output: @status == :success ? @content : nil,
    error: @error,
    metadata: @metadata
  }
end

#to_s ⇒ String

Returns the content as a string (for failures, the message).

Returns:

  • (String) —

    the content as a string (for failures, the message)



153
154
155
 
# File 'lib/ask/result.rb', line 153

def to_s
  @content.to_s
end