Class: Protege::Result

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

Overview

Immutable outcome value — the standard return type passed between system parts across the LOGI pipeline: tools (+Tool#use+), resolvers, and gateway operations all hand back a Result. Carrying success/failure as data (rather than raising across layer boundaries) lets the Orchestrator serialize a failed tool outcome straight into the LLM's tool message so the model can self-correct. Frozen on construction; build via Result.success / Result.failure.

Examples:

Result.success(id: 42)
Result.failure(reason: 'bad input', field: :email)
Result.failure(reason: exception)

Constant Summary collapse

SERIALIZED_BACKTRACE_FRAMES =

Number of backtrace frames retained in the serialized error.

The serialized result is encoded into the LLM's tool message, where a deep backtrace is just token-costly noise — the class and message are what the model reasons over. Operators still get the full backtrace via the engine log (see ToolMixin.invoke) and the persisted Message#last_processing_error.

3

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(success:, data: {}, error: nil) ⇒ void

Initialize and freeze the result.

Parameters:

  • success (Boolean) —

    whether the operation succeeded

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

    arbitrary payload keyed by symbol

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

    the captured error, present only on failure



74
75
76
77
78
79
80
 
# File 'lib/protege/types/result.rb', line 74

def initialize(success:, data: {}, error: nil)
  @success = success
  @data    = data
  @error   = error

  freeze
end

Instance Attribute Details

#data ⇒ Boolean, ... (readonly)

Returns:

  • (Boolean) —

    true when the operation succeeded

  • (Hash) —

    the payload data attached to the outcome

  • (Exception, nil) —

    the captured error on failure, otherwise nil



26
27
28
 
# File 'lib/protege/types/result.rb', line 26

def data
  @data
end

#error ⇒ Boolean, ... (readonly)

Returns:

  • (Boolean) —

    true when the operation succeeded

  • (Hash) —

    the payload data attached to the outcome

  • (Exception, nil) —

    the captured error on failure, otherwise nil



26
27
28
 
# File 'lib/protege/types/result.rb', line 26

def error
  @error
end

#success ⇒ Boolean, ... (readonly)

Returns:

  • (Boolean) —

    true when the operation succeeded

  • (Hash) —

    the payload data attached to the outcome

  • (Exception, nil) —

    the captured error on failure, otherwise nil



26
27
28
 
# File 'lib/protege/types/result.rb', line 26

def success
  @success
end

Class Method Details

.failure(reason:, **data) ⇒ Protege::Result

Build a failed Result.

reason may be a String or an Exception; strings are wrapped in Protege::GenericError so #error is always an Exception.

Parameters:

  • reason (String, Exception) —

    the failure cause

  • data (Hash) —

    arbitrary payload keyed by symbol

Returns:



48
49
50
 
# File 'lib/protege/types/result.rb', line 48

def failure(reason:, **data)
  new success: false, data:, error: wrap_generic_error(reason)
end

.success(**data) ⇒ Protege::Result

Build a successful Result.

Parameters:

  • data (Hash) —

    arbitrary payload keyed by symbol

Returns:



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

def success(**data)
  new success: true, data:
end

Instance Method Details

#failure? ⇒ Boolean

Returns true when the operation failed.

Returns:

  • (Boolean) —

    true when the operation failed



83
84
85
 
# File 'lib/protege/types/result.rb', line 83

def failure?
  !success
end

#success? ⇒ Boolean, ...

Returns:

  • (Boolean) —

    true when the operation succeeded

  • (Hash) —

    the payload data attached to the outcome

  • (Exception, nil) —

    the captured error on failure, otherwise nil

  • (Boolean) —

    alias of #success — true when the operation succeeded



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

def success
  @success
end

#to_h ⇒ Hash

Serialize the result to a plain hash suitable for JSON encoding into a tool message.

Returns:

  • (Hash) —

    { success:, data:, error: } where error is a serialized hash or nil



90
91
92
93
94
95
96
 
# File 'lib/protege/types/result.rb', line 90

def to_h
  {
    success:,
    data:,
    error:   serialized_error
  }
end