Class: Ask::Result

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

Overview

Standardized return value from tool execution. Wraps the outcome of a tool call with status, content, and optional error metadata.

Ask::Result.success("Data processed")
Ask::Result.failure("API returned 500")

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, status: :success, error: nil, metadata: {}) ⇒ Result

Returns a new instance of Result.



61
62
63
64
65
66
67
 
# File 'lib/ask/result.rb', line 61

def initialize(content: nil, status: :success, error: nil, metadata: {})
  @content = content
  @status = validate_status!(status)
  @error = error
  @metadata = metadata.dup.freeze
  freeze
end

Instance Attribute Details

#content ⇒ Object? (readonly)

Returns the result content.

Returns:

  • (Object, nil) —

    the result content



50
51
52
 
# File 'lib/ask/result.rb', line 50

def content
  @content
end

#error ⇒ Object? (readonly)

Returns the underlying error, if any.

Returns:

  • (Object, nil) —

    the underlying error, if any



56
57
58
 
# File 'lib/ask/result.rb', line 56

def error
  @error
end

#metadata ⇒ Hash (readonly)

Returns additional metadata.

Returns:

  • (Hash) —

    additional metadata



59
60
61
 
# File 'lib/ask/result.rb', line 59

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)



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

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:



36
37
38
 
# File 'lib/ask/result.rb', line 36

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:



43
44
45
 
# File 'lib/ask/result.rb', line 43

def blocked(reason)
  new(content: reason, status: :blocked)
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

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

    additional metadata

Returns:



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

def failure(message, error: nil, metadata: {})
  new(content: message, status: :error, error: error, 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:



20
21
22
 
# File 'lib/ask/result.rb', line 20

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



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

def aborted? = @status == :aborted

#blocked? ⇒ Boolean

Returns true if status is :blocked.

Returns:

  • (Boolean) —

    true if status is :blocked



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

def blocked? = @status == :blocked

#error? ⇒ Boolean

Returns true if status is :error.

Returns:

  • (Boolean) —

    true if status is :error



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

def error? = @status == :error

#inspect ⇒ String

Returns human-readable representation.

Returns:

  • (String) —

    human-readable representation



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

def inspect
  "#<Ask::Result status=#{@status.inspect} content=#{@content.inspect}>"
end

#success? ⇒ Boolean

Returns true if status is :success.

Returns:

  • (Boolean) —

    true if status is :success



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

def success? = @status == :success

#to_h ⇒ Hash

Returns serialized representation.

Returns:

  • (Hash) —

    serialized representation



87
88
89
90
91
92
93
94
 
# File 'lib/ask/result.rb', line 87

def to_h
  {
    content: @content,
    status: @status,
    error: @error,
    metadata: @metadata
  }.compact
end

#to_s ⇒ String

Returns the content as a string.

Returns:

  • (String) —

    the content as a string



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

def to_s
  @content.to_s
end