riffer 0.45.0 → 0.46.1

data/sig/generated/riffer/agent/response.rbs

@@ -1,29 +1,28 @@
 # Generated from lib/riffer/agent/response.rb with RBS::Inline
 
-# Wraps an agent generation response. When a guardrail blocks execution,
-# +content+ is empty and +tripwire+ carries the block details.
+# Wraps an agent generation response. +outcome+ says how the run ended; when a
+# guardrail blocks execution, +content+ is empty and +tripwire+ carries the
+# block details.
 #
 #   response = agent.generate("Hello")
-#   if response.blocked?
-#     puts "Blocked: #{response.tripwire.reason}"
-#   else
+#   if response.outcome.success?
 #     puts response.content
+#   else
+#     puts "#{response.outcome.reason}: #{response.outcome.detail}"
 #   end
 class Riffer::Agent::Response
-  @interrupted: bool
-
   # The response content.
   attr_reader content: String
 
+  # How the run ended.
+  attr_reader outcome: Riffer::Agent::Outcome
+
   # The tripwire if execution was blocked.
   attr_reader tripwire: Riffer::Guardrails::Tripwire?
 
   # The modifications made by guardrails during processing.
   attr_reader modifications: Array[Riffer::Guardrails::Modification]
 
-  # The reason provided with the interrupt, if any.
-  attr_reader interrupt_reason: (String | Symbol)?
-
   # The parsed structured output, if structured output was configured.
   attr_reader structured_output: Hash[Symbol, untyped]?
 
@@ -44,34 +43,20 @@ class Riffer::Agent::Response
   # --
   # : (
   #     String,
+  #     outcome: Riffer::Agent::Outcome,
   #     ?tripwire: Riffer::Guardrails::Tripwire?,
   #     ?modifications: Array[Riffer::Guardrails::Modification],
-  #     ?interrupted: bool,
-  #     ?interrupt_reason: (String | Symbol)?,
   #     ?structured_output: Hash[Symbol, untyped]?,
   #     ?messages: Array[Riffer::Messages::Base],
   #     ?healed_tool_call_ids: Array[String],
   #     ?token_usage: Riffer::Providers::TokenUsage?,
   #     ?steps: Integer
   #   ) -> void
-  def initialize: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
-
-  # Returns true if the response was blocked by a guardrail.
-  #
-  # --
-  # : () -> bool
-  def blocked?: () -> bool
+  def initialize: (String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> void
 
   # Returns true if any guardrail modified data during processing.
   #
   # --
   # : () -> bool
   def modified?: () -> bool
-
-  # Returns true if the agent loop was interrupted by a callback
-  # via <tt>throw :riffer_interrupt</tt>.
-  #
-  # --
-  # : () -> bool
-  def interrupted?: () -> bool
 end

data/sig/generated/riffer/agent/run.rbs

@@ -14,8 +14,8 @@ module Riffer::Agent::Run
   # for prompt/files semantics.
   #
   # --
-  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  def stream: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
 
   private
 
@@ -45,8 +45,16 @@ module Riffer::Agent::Run
   def tripwire_response: (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
 
   # --
-  # : (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
-  def final_response: (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
+  # : (Riffer::Agent, Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, **untyped) -> Riffer::Agent::Response
+  def final_response: (Riffer::Agent, Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, **untyped) -> Riffer::Agent::Response
+
+  # Checked in the order things happened. The loop being stopped (max_steps or
+  # an interrupt) beats the provider's finish reason, which beats riffer's own
+  # validation of the content. A truncated response that also fails the schema
+  # therefore reports :length, not :invalid_structured_output.
+  # --
+  # : (Riffer::Messages::Assistant?, Riffer::Agent::StructuredOutput::Result?, interrupted: bool, interrupt_reason: (String | Symbol)?) -> Riffer::Agent::Outcome
+  def final_outcome: (Riffer::Messages::Assistant?, Riffer::Agent::StructuredOutput::Result?, interrupted: bool, interrupt_reason: (String | Symbol)?) -> Riffer::Agent::Outcome
 
   # --
   # : (Riffer::Agent, ?Hash[String, String]) -> Riffer::Messages::Assistant
@@ -77,8 +85,8 @@ module Riffer::Agent::Run
   def run_after_guardrails: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
 
   # --
-  # : (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
-  def validate_structured_output: (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
+  # : (Riffer::Agent, Riffer::Messages::Assistant?) -> Riffer::Agent::StructuredOutput::Result?
+  def structured_output_result: (Riffer::Agent, Riffer::Messages::Assistant?) -> Riffer::Agent::StructuredOutput::Result?
 
   # --
   # : (Riffer::Agent) -> Array[singleton(Riffer::Tool)]
@@ -96,16 +104,15 @@ module Riffer::Agent::Run
   # : (
   #     Riffer::Agent,
   #     String,
+  #     outcome: Riffer::Agent::Outcome,
   #     ?tripwire: Riffer::Guardrails::Tripwire?,
   #     ?modifications: Array[Riffer::Guardrails::Modification],
-  #     ?interrupted: bool,
-  #     ?interrupt_reason: (String | Symbol)?,
   #     ?structured_output: Hash[Symbol, untyped]?,
   #     ?healed_tool_call_ids: Array[String],
   #     ?token_usage: Riffer::Providers::TokenUsage?,
   #     ?steps: Integer
   #   ) -> Riffer::Agent::Response
-  def build_response: (Riffer::Agent, String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
+  def build_response: (Riffer::Agent, String, outcome: Riffer::Agent::Outcome, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String], ?token_usage: Riffer::Providers::TokenUsage?, ?steps: Integer) -> Riffer::Agent::Response
 
   # Raises when +files+ are supplied without a +prompt+ — the provider needs
   # text to anchor the attachments.
@@ -136,4 +143,8 @@ module Riffer::Agent::Run
   # --
   # : (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Agent::Response) -> void
   def record_run_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Agent::Response) -> void
+
+  # --
+  # : (Riffer::Agent::Outcome) -> String?
+  def interrupt_reason_attribute: (Riffer::Agent::Outcome) -> String?
 end

data/sig/generated/riffer/agent.rbs

@@ -113,8 +113,8 @@ class Riffer::Agent
 
   # Streams a response using a new agent instance.
   # --
-  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def self.stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  def self.stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
 
   # Reconstructs a runnable agent from a wire hash produced by +#to_h+.
   # --
@@ -208,14 +208,15 @@ class Riffer::Agent
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
   def generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
-  # Streams a response from the agent, returning an +Enumerator+ of
-  # +Riffer::StreamEvents+. See +#generate+ for prompt/files/tags semantics.
+  # Streams a response from the agent as an +Enumerator+ of
+  # +Riffer::StreamEvents+ whose block-form +each+ returns the final
+  # Riffer::Agent::Response. See +#generate+ for prompt/files/tags semantics.
   #
   # Raises Riffer::ArgumentError if structured output is configured.
   #
   # --
-  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  def stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
 
   # Interrupts the agent loop from an +on_message+ callback. Equivalent to
   # <tt>throw :riffer_interrupt, reason</tt>.

data/sig/generated/riffer/messages/assistant.rbs

@@ -27,11 +27,23 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   # <tt>Riffer::Providers::FinishReason::VALUES</tt>).
   attr_reader finish_reason: Symbol?
 
+  # The provider's raw finish-reason value behind +finish_reason+, when one
+  # exists on the wire.
+  attr_reader finish_reason_raw: String?
+
   # Raises Riffer::ArgumentError when +finish_reason+ is outside the
   # normalized vocabulary.
   # --
-  # : (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?) -> void
-  def initialize: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?) -> void
+  # : (
+  #    String,
+  #    ?id: String?,
+  #    ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall],
+  #    ?token_usage: Riffer::Providers::TokenUsage?,
+  #    ?structured_output: Hash[Symbol, untyped]?,
+  #    ?finish_reason: Symbol?,
+  #    ?finish_reason_raw: String?
+  #  ) -> void
+  def initialize: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?, ?finish_reason: Symbol?, ?finish_reason_raw: String?) -> void
 
   # --
   # : () -> Symbol

data/sig/generated/riffer/params.rbs

@@ -40,6 +40,11 @@ class Riffer::Params
 
   # Validates arguments against parameter definitions.
   #
+  # A Float param accepts an Integer (JSON Schema <tt>"number"</tt> covers
+  # integers) and its value is coerced with +to_f+, so callers always get a
+  # Float. The same holds for the items of an <tt>of: Float</tt> array. No other
+  # type is coerced.
+  #
   # Raises Riffer::ValidationError if validation fails.
   #
   # --
@@ -71,7 +76,16 @@ class Riffer::Params
   # : (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
   def validate_nested_array_of_objects: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
 
+  # Returns the array with its valid items coerced by +coerce_value+.
+  # --
+  # : (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
+  def validate_typed_array: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
+
+  # Coerces an already-validated value to the Ruby type its param declares.
+  # Only Float coerces today, because JSON Schema "number" accepts integers and
+  # callers should not get a type that depends on whether the model wrote a
+  # decimal point. Add a branch here rather than inline at a call site.
   # --
-  # : (Riffer::Params::Param, Array[untyped], Array[String]) -> void
-  def validate_typed_array: (Riffer::Params::Param, Array[untyped], Array[String]) -> void
+  # : (Module, untyped) -> untyped
+  def coerce_value: (Module, untyped) -> untyped
 end

data/sig/generated/riffer/runner/fibers.rbs

@@ -4,6 +4,8 @@
 # +max_concurrency+ caps simultaneous fibers via an <tt>Async::Semaphore</tt>.
 # If multiple fibers raise, only the first exception is re-raised after all
 # finish.
+# Joins the current reactor task when one is already running, and otherwise
+# starts its own.
 class Riffer::Runner::Fibers < Riffer::Runner
   @max_concurrency: Integer?
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.45.0
+  version: 0.46.1
 platform: ruby
 authors:
 - Jake Bottrall
@@ -110,6 +110,7 @@ files:
 - lib/riffer/agent.rb
 - lib/riffer/agent/config.rb
 - lib/riffer/agent/context.rb
+- lib/riffer/agent/outcome.rb
 - lib/riffer/agent/response.rb
 - lib/riffer/agent/run.rb
 - lib/riffer/agent/serializer.rb
@@ -239,6 +240,7 @@ files:
 - sig/generated/riffer/agent.rbs
 - sig/generated/riffer/agent/config.rbs
 - sig/generated/riffer/agent/context.rbs
+- sig/generated/riffer/agent/outcome.rbs
 - sig/generated/riffer/agent/response.rbs
 - sig/generated/riffer/agent/run.rbs
 - sig/generated/riffer/agent/serializer.rbs