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].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



99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/ask/result.rb', line 99

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)



78
79
80
 
# File 'lib/ask/result.rb', line 78

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



84
85
86
 
# File 'lib/ask/result.rb', line 84

def error
  @error
end

#metadata ⇒ Hash (readonly)

Returns additional metadata.

Returns:

  • (Hash) —

    additional metadata



87
88
89
 
# File 'lib/ask/result.rb', line 87

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)



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

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:



70
71
72
 
# File 'lib/ask/result.rb', line 70

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:



62
63
64
 
# File 'lib/ask/result.rb', line 62

def ok(data:, metadata: {})
  new(content: data, status: :success, 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



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

def aborted? = @status == :aborted

#blocked? ⇒ Boolean

Returns true if status is :blocked.

Returns:

  • (Boolean) —

    true if status is :blocked



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

def blocked? = @status == :blocked

#error? ⇒ Boolean

Returns true if status is :error.

Returns:

  • (Boolean) —

    true if status is :error



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

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



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

def error_message = @error

#inspect ⇒ String

Returns human-readable representation.

Returns:

  • (String) —

    human-readable representation



154
155
156
157
158
159
160
 
# File 'lib/ask/result.rb', line 154

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)



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

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)



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

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)



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

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

#success? ⇒ Boolean

Returns true if status is :success.

Returns:

  • (Boolean) —

    true if status is :success



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

def success? = @status == :success

#to_h ⇒ Hash

Returns serialized representation.

Returns:

  • (Hash) —

    serialized representation



144
145
146
147
148
149
150
151
 
# File 'lib/ask/result.rb', line 144

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)



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

def to_s
  @content.to_s
end