Class: OmniAI::Chat::FinishReason

Inherits:
Object
  • Object
show all
Defined in:
lib/omniai/chat/finish_reason.rb

Overview

A normalized, provider-agnostic reason a generation stopped, paired with the verbatim provider value.

‘#reason` is one of the canonical symbols (REASONS) for branching/alerting; `#value` is the raw provider token (e.g. “RECITATION”, “end_turn”, “stop”), preserved verbatim — including when the reason normalizes to `:other`. Each provider maps its own vocabulary onto a reason in its deserializer; the verbatim value is never discarded, so consumers keep provider granularity without digging the provider-specific response `data`.

Constant Summary collapse

STOP =

A natural stopping point was reached.

:stop
LENGTH =

The token budget (requested max tokens or the model’s context window) was reached.

:length
TOOL_CALL =

The model is requesting a tool / function call.

:tool_call
FILTER =

The provider deliberately suppressed or blocked output (safety, policy, recitation, unsupported language).

:filter
OTHER =

A value was present but does not map to a known category (forward-compatible fallback).

:other
REASONS =

The canonical normalized reasons.

%i[stop length tool_call filter other].freeze
CHAT_COMPLETIONS =

The Chat Completions ‘finish_reason` vocabulary (originated by OpenAI; also emitted by Mistral and OpenAI-compatible gateways). Applied by the base `Choice.deserialize` path, which models that schema.

{
  "stop" => STOP,
  "length" => LENGTH,
  "tool_calls" => TOOL_CALL,
  "function_call" => TOOL_CALL,
  "content_filter" => FILTER,
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(reason:, value:) ⇒ FinishReason

Returns a new instance of FinishReason.

Parameters:

  • reason (Symbol) —

    one of REASONS

  • value (String) —

    the verbatim provider token



66
67
68
69
 
# File 'lib/omniai/chat/finish_reason.rb', line 66

def initialize(reason:, value:)
  @reason = reason
  @value = value
end

Instance Attribute Details

#reason ⇒ Object (readonly)

Returns the value of attribute reason.



42
43
44
 
# File 'lib/omniai/chat/finish_reason.rb', line 42

def reason
  @reason
end

#value ⇒ Object (readonly)

Returns the value of attribute value.



46
47
48
 
# File 'lib/omniai/chat/finish_reason.rb', line 46

def value
  @value
end

Class Method Details

.deserialize(value, table: CHAT_COMPLETIONS) ⇒ FinishReason?

Normalizes a raw provider value through a mapping table into a FinishReason.

  • ‘nil` in → `nil` out (absence is not the same as unrecognized).

  • otherwise → a FinishReason whose ‘reason` is the table’s mapping (or ‘:other` when unmapped) and whose `value` is the raw token, preserved verbatim — always, including on `:other`.

Parameters:

  • value (String, nil) —

    the raw provider value

  • table (Hash{String => Symbol}) (defaults to: CHAT_COMPLETIONS) —

    the provider’s mapping table (defaults to the Chat Completions vocabulary)

Returns:



58
59
60
61
62
 
# File 'lib/omniai/chat/finish_reason.rb', line 58

def self.deserialize(value, table: CHAT_COMPLETIONS)
  return if value.nil?

  new(reason: table.fetch(value, OTHER), value:)
end

Instance Method Details

#filter? ⇒ Boolean

Returns:

  • (Boolean) 


92
93
94
 
# File 'lib/omniai/chat/finish_reason.rb', line 92

def filter?
  reason == FILTER
end

#inspect ⇒ String

Returns:

  • (String) 


72
73
74
 
# File 'lib/omniai/chat/finish_reason.rb', line 72

def inspect
  "#<#{self.class.name} reason=#{reason.inspect} value=#{value.inspect}>"
end

#length? ⇒ Boolean

Returns:

  • (Boolean) 


82
83
84
 
# File 'lib/omniai/chat/finish_reason.rb', line 82

def length?
  reason == LENGTH
end

#other? ⇒ Boolean

Returns:

  • (Boolean) 


97
98
99
 
# File 'lib/omniai/chat/finish_reason.rb', line 97

def other?
  reason == OTHER
end

#stop? ⇒ Boolean

Returns:

  • (Boolean) 


77
78
79
 
# File 'lib/omniai/chat/finish_reason.rb', line 77

def stop?
  reason == STOP
end

#tool_call? ⇒ Boolean

Returns:

  • (Boolean) 


87
88
89
 
# File 'lib/omniai/chat/finish_reason.rb', line 87

def tool_call?
  reason == TOOL_CALL
end