ruby-pi 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e996e18be62d604fb9950b3f1ffa3951be1cf89f9bcc56bdedee790a7fc6c042
-  data.tar.gz: 48ecbe8c92e41bfeeaa723d05230ad8d8d58eaf13da2019f87bc19614342de98
+  metadata.gz: 45a50058497c3e040f81e977ffdbe0030b901ea053e91002e4ddddba06c23a6f
+  data.tar.gz: 6066bc184d7f8eb951ae137595a8ed082ec41c3abc8ca84cbfe5b4206fde6f66
 SHA512:
-  metadata.gz: 923f10b140fdf2fa78948d515c97ee2f5ed48ba29d7bb7c20cd3cbb6b2b253690972a40a1e2edf3a1ec5aa460c09aabf03ce074a2713a6b841be9000101941c0
-  data.tar.gz: 261ab3f511a1f8abef34f438a842be7648c8a327df72540523c7c0538b127743cb03ec7a80992856d26addeef7c1c654b5e649fe0aec818c544cdc1acc6085d4
+  metadata.gz: d486b3a171dca8c59bf442ba5c03f135ee450a083c47c05f075af6b23d87eb24285c72c734a9579456d71d6ac247ed4357f7bd16b813219e77655a98f44b0cc2
+  data.tar.gz: 602ed6dc493731203c9fedb8d69f118c81ce292c653ca42ac4ca0d9f8d793dc281697fa87f9df9f7601022812dd791d4420d0f22ba89ad6051119791e87f33ca

data/CHANGELOG.md

@@ -5,6 +5,57 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.5] - 2026-04-30
+
+### Fixed (adversarial review round 3)
+
+- **Streaming error body recovery — Gemini and OpenAI**: The 0.1.4 fix accumulated `error_body` in the `on_data` callback for all three providers but only Anthropic actually passed it to `handle_error_response`. Gemini (`gemini.rb`) and OpenAI (`openai.rb`) now also pass `override_body: error_body` so `ApiError#response_body` carries the real server error message on streaming HTTP failures, matching Anthropic's behavior
+- **Compaction consecutive same-role messages**: The 0.1.4 fix changed the summary role from `:user` to `:assistant` to avoid consecutive user messages, but produced consecutive assistants when the first preserved message was already `:assistant`. The summary role is now chosen based on the first preserved message's role: `:user` when the next message is `:assistant`, `:assistant` otherwise. New compaction spec exercises both orderings
+- **`:fallback_start` not surfaced to agent users**: `RubyPi::LLM::Fallback` emits a `:fallback_start` `StreamEvent` when the primary fails mid-stream, but the agent loop's stream block only handled `:text_delta` and `:tool_call_delta`, dropping the signal. The loop now translates `:fallback_start` into a new agent-level `:provider_fallback` event, and clears the streamed-content accumulator so the recorded response reflects only the fallback's output. Subscribers register with `agent.on(:provider_fallback) { |e| ... }`
+- **`StreamEvent#fallback_start?` predicate**: Added to match `text_delta?`, `tool_call_delta?`, and `done?` so consumers can branch on it without comparing `event.type` directly
+- **Tool result JSON serialization crash**: `Loop#act` called `JSON.generate(result.value)` unconditionally; tools returning Time, Date, or other non-JSON-serializable objects raised `JSON::GeneratorError` and aborted the agent run. The serialization is now wrapped in a rescue that falls back to `result.value.to_s`
+- **`tool_calls_made` argument shape inconsistency**: The arguments recorded in `Result#tool_calls_made` were the raw string-keyed `JSON.parse` output, while the tool block itself received the symbol-keyed copy `Tools::Executor` produces. Both now use the symbolized form, and `Tools::Executor.deep_symbolize_keys` is exposed as a public class method so the loop can apply the same transformation up front
+- **`Agent::Core` `config:` kwarg honesty**: The 0.1.4 changelog claimed the kwarg "flows through to provider construction." It does not — the model is constructed before the agent. The kwarg is informational only; users who want per-agent provider config must pass `config:` to the model factory: `RubyPi::LLM.model(:openai, "gpt-4o", config: cfg)`. The Agent::Core docstring and CHANGELOG now reflect this
+- **CHANGELOG references to nonexistent `BufferedStreamProxy`**: The 0.1.4 entry referenced a `BufferedStreamProxy` class that does not exist in the codebase; the buffering logic was inline in `Fallback`. Removed those references
+- **CLAUDE.md provider/extension guides**: "Adding a New LLM Provider" still referenced the deleted `parse_sse_events` helper; updated to describe the `on_data` streaming pattern. The `:agent_end` extension example used `event[:iterations]` (no such key) — replaced with `event[:result].turns`. Added `:tool_call_delta` and `:provider_fallback` to the available events list
+- **README streaming docs**: Documented the `:fallback_start` stream event and the agent-level `:provider_fallback` event with payload schema
+
+## [0.1.4] - 2026-04-30
+
+### Fixed (adversarial review round 2)
+
+- **Anthropic ProviderError string interpolation**: Removed backslash-escaping on `#{}` interpolation in the ProviderError message for malformed tool call JSON, so actual tool name and parser error appear instead of literal `\#{...}` text
+- **Thread-unsafe streaming instance variables**: Replaced `@_stream_*` instance variables in Anthropic provider with method-local variables via a `process_anthropic_stream_event` helper that returns updated state as a hash, making streaming safe for concurrent requests
+- **Streaming error body recovery (Anthropic)**: Anthropic's streaming path now detects HTTP error status in the `on_data` callback, accumulates the error response body separately, and passes it to `handle_error_response` via the new `override_body:` kwarg so `ApiError#response_body` carries the server's error message even though `on_data` consumed the response. (Note: 0.1.5 extends this to Gemini and OpenAI, which were missed in 0.1.4)
+- **Compaction `:system` poisoning**: Changed compaction summary role from `:system` to a non-system role to prevent overwriting the real system prompt on Anthropic. (Note: 0.1.5 refines the role choice to also avoid consecutive same-role messages)
+- **OpenAI missing tool_call_id**: OpenAI provider now raises `RubyPi::ProviderError` on nil/blank `tool_call_id` in tool result messages and assistant tool calls (same fail-fast pattern as Anthropic), instead of silently sending `"unknown"`
+- **Gemini streaming finish_reason**: Streaming responses now parse the actual `finishReason` from the Gemini candidate object instead of hardcoding `"stop"`
+- **README incorrect event keys**: Fixed `e[:iteration]` to `e[:turn]` and `event[:iterations]` to `event[:result].turns` throughout README examples
+- **Dead `parse_sse_events` method**: Removed unused `parse_sse_events` from `BaseProvider` (all providers now use real incremental streaming via `on_data`)
+- **`faraday-net_http` version cap**: Removed arbitrary `< 3.4` upper bound from both Gemfile and gemspec
+- **`Fallback` no longer buffers happy-path streams**: `Fallback#perform_complete_with_streaming_fallback` previously buffered all primary events and flushed them after completion, destroying the streaming UX even when nothing went wrong. Events now flow through to the consumer in real time. On primary failure, a `:fallback_start` `StreamEvent` is emitted before the fallback streams, signaling consumers to clear partial output
+
+#### Previously Addressed (adversarial review round 1, 35 items)
+
+- API key exposure in Gemini URL query strings (moved to header)
+- Provider `format_tool` accepting `Definition` objects
+- Retry-after header parsing for `RateLimitError`
+- Max iterations boundary condition (off-by-one)
+- Token usage accumulation across turns
+- Agent result `success?` semantics for max-iteration stops
+- Context compaction system prompt poisoning
+- `nil` tool guard in executor
+- Tool call ID validation (Anthropic fail-fast)
+- Streaming event types (`:text_delta` for text, `:tool_call_delta` for tools)
+- Concurrent tool execution thread safety
+- `before_tool_call` / `after_tool_call` lifecycle hooks
+- `transform_context` pipeline support
+- Extension base class DSL (`on_event`, `before_tool`, `after_tool`)
+- `Agent::Core#config:` kwarg accepted (informational only — pass `config:` to the model factory to actually override provider config)
+- Typed error hierarchy with `response_body` on `ApiError`
+- `ostruct` runtime dependency declaration
+- Comprehensive test coverage (440+ examples)
+
 ## [0.1.3] - 2026-04-29
 
 ### Added

data/README.md

@@ -73,15 +73,19 @@ registry = RubyPi::Tools::Registry.new
 registry.register(weather)
 
 model = RubyPi::LLM.model(:gemini, "gemini-2.0-flash")
-agent = RubyPi::Agent.new(model: model, tools: registry, stream: true)
+agent = RubyPi::Agent.new(
+  system_prompt: "You are a helpful weather assistant.",
+  model: model,
+  tools: registry
+)
 
 # 4. Subscribe to events
-agent.on(:text_delta) { |e| print e[:data] }
-agent.on(:tool_execution_end) { |e| puts "\n[Tool] #{e[:name]} => #{e[:result]}" }
+agent.on(:text_delta) { |e| print e[:content] }
+agent.on(:tool_execution_end) { |e| puts "\n[Tool] #{e[:tool_name]} => #{e[:result].value}" }
 
 # 5. Run
 result = agent.run("What's the weather in San Francisco?")
-puts "\nDone: #{result.output}"
+puts "\nDone: #{result.content}"
 ```
 
 ---
@@ -126,12 +130,24 @@ model.complete(messages: messages, stream: true) do |event|
     print event.data           # incremental text chunk
   when :tool_call_delta
     handle_fragment(event.data) # partial tool call JSON
+  when :fallback_start
+    # Only emitted by RubyPi::LLM::Fallback when the primary provider
+    # fails mid-stream. Discard any partial output rendered from the
+    # primary; the fallback provider is about to stream its full reply.
+    # Payload: { failed_provider:, error:, fallback_provider: }
+    clear_partial_output
   when :done
     puts "\nStream finished"
   end
 end
 ```
 
+When using `RubyPi::Agent`, the loop translates a `:fallback_start` stream
+event into an agent-level `:provider_fallback` event you can subscribe to
+with `agent.on(:provider_fallback) { |e| ... }`. The agent also discards
+any partial text it accumulated from the failed primary so the recorded
+response reflects only the fallback's output.
+
 #### Response & ToolCall
 
 | Class | Attributes |
@@ -161,6 +177,12 @@ Authentication errors (401/403) are **not** retried with the fallback -- they in
 
 A lightweight DSL for defining tools (functions) that LLMs can call, plus a registry and executor for dispatching them.
 
+> **`RubyPi::Tool` vs `RubyPi::Tools`:** `RubyPi::Tool.define(...)` is the convenience API
+> for creating tool definitions with a clean syntax. `RubyPi::Tools` is the internal namespace
+> containing the supporting classes (`Definition`, `Registry`, `Executor`, `Result`, `Schema`).
+> Use `RubyPi::Tool.define` in application code; reference `RubyPi::Tools::*` when you need
+> direct access to the underlying components.
+
 #### Defining Tools
 
 ```ruby
@@ -247,14 +269,19 @@ The Agent implements a **think-act-observe** loop: send messages to the LLM, exe
 
 ```ruby
 agent = RubyPi::Agent.new(
+  system_prompt: "You are a helpful assistant.",  # required: system-level instruction
   model: model,                        # required: an LLM provider instance
   tools: registry,                     # optional: a Tools::Registry
-  stream: false,                       # optional: enable streaming
-  max_iterations: 10,                  # optional: loop safety limit
-  context_compaction: compaction,      # optional: Context::Compaction instance
-  context_transform: transform,        # optional: Context::Transform instance
-  extensions: [my_extension]           # optional: Extension instances
+  max_iterations: 10,                  # optional: loop safety limit (default: 10)
+  compaction: compaction,              # optional: Context::Compaction instance
+  transform_context: transform,        # optional: context transform callable
+  before_tool_call: ->(tc) { },        # optional: pre-tool-execution hook
+  after_tool_call: ->(tc, r) { },      # optional: post-tool-execution hook
+  user_data: {}                        # optional: arbitrary data for transforms/extensions
 )
+
+# Extensions are registered after construction via `use` (takes a CLASS, not an instance):
+agent.use(MetricsExtension)
 ```
 
 #### Running the Agent
@@ -262,11 +289,10 @@ agent = RubyPi::Agent.new(
 ```ruby
 # Single run
 result = agent.run("What is the weather in Tokyo?")
-result.output            # => "The weather in Tokyo is..."
+result.content           # => "The weather in Tokyo is..."
 result.messages          # => full conversation history
 result.tool_calls_made   # => [{ name: "get_weather", ... }, ...]
-result.iterations        # => 2
-result.stop_reason       # => :complete or :max_iterations
+result.turns             # => 2
 
 # Continue the conversation
 result2 = agent.continue("And in London?")
@@ -277,13 +303,15 @@ result2 = agent.continue("And in London?")
 Subscribe to lifecycle events for logging, monitoring, or custom behavior:
 
 ```ruby
-agent.on(:turn_start)          { |e| puts "Turn #{e[:iteration]} starting" }
-agent.on(:turn_end)            { |e| puts "Turn #{e[:iteration]} ended" }
-agent.on(:text_delta)          { |e| print e[:data] }
+agent.on(:turn_start)          { |e| puts "Turn #{e[:turn]} starting" }
+agent.on(:turn_end)            { |e| puts "Turn #{e[:turn]} ended" }
+agent.on(:text_delta)          { |e| print e[:content] }
 agent.on(:tool_execution_start){ |e| puts "Calling #{e[:tool_name]}" }
-agent.on(:tool_execution_end)  { |e| puts "#{e[:name]} => #{e[:result]}" }
-agent.on(:before_tool_call)    { |e| puts "About to call #{e[:tool_name]}" }
-agent.on(:after_tool_call)     { |e| puts "Finished #{e[:tool_name]}" }
+agent.on(:tool_execution_end)  { |e| puts "#{e[:tool_name]} => #{e[:result].value}" }
+# Note: before_tool_call and after_tool_call are constructor hooks (Procs),
+# not subscribable events. Use the constructor kwargs instead:
+#   before_tool_call: ->(tc) { puts "About to call #{tc.name}" }
+#   after_tool_call: ->(tc, result) { puts "Finished #{tc.name}" }
 agent.on(:agent_end)           { |e| puts "Agent finished" }
 agent.on(:error)               { |e| warn "Error: #{e[:error].message}" }
 ```
@@ -300,11 +328,16 @@ Prevent unbounded context growth by compacting older messages:
 
 ```ruby
 compaction = RubyPi::Context::Compaction.new(
-  max_tokens: 4000,         # trigger compaction above this threshold
-  strategy: :truncate       # :truncate removes oldest messages
+  summary_model: summary_model,  # required: LLM provider for generating summaries
+  max_tokens: 4000,              # optional: trigger compaction above this threshold (default: 8000)
+  preserve_last_n: 4             # optional: always keep the last N messages (default: 4)
 )
 
-agent = RubyPi::Agent.new(model: model, context_compaction: compaction)
+agent = RubyPi::Agent.new(
+  system_prompt: "You are helpful.",
+  model: model,
+  compaction: compaction
+)
 ```
 
 #### Transform
@@ -312,12 +345,23 @@ agent = RubyPi::Agent.new(model: model, context_compaction: compaction)
 Apply arbitrary transformations to the message list before each LLM call:
 
 ```ruby
-transform = RubyPi::Context::Transform.new do |messages|
-  # Inject a system prompt at the beginning
-  [{ role: "system", content: "You are a helpful Ruby assistant." }] + messages
+# Transform is a module with factory methods, not a class.
+# Use the built-in transforms or compose your own:
+transform = RubyPi::Context::Transform.compose(
+  RubyPi::Context::Transform.inject_datetime,
+  RubyPi::Context::Transform.inject_user_preferences { |state| state.user_data[:prefs] }
+)
+
+# Or write a custom transform as a lambda that receives the Agent::State:
+custom_transform = ->(state) do
+  state.system_prompt += "\n\nAdditional context here."
 end
 
-agent = RubyPi::Agent.new(model: model, context_transform: transform)
+agent = RubyPi::Agent.new(
+  system_prompt: "You are a helpful Ruby assistant.",
+  model: model,
+  transform_context: transform
+)
 ```
 
 ---
@@ -336,11 +380,11 @@ class MetricsExtension < RubyPi::Extensions::Base
 
   on_event :turn_end do |event|
     elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @turn_timer
-    puts "Turn #{event[:iteration]} took #{elapsed.round(2)}s"
+    puts "Turn #{event[:turn]} took #{elapsed.round(2)}s"
   end
 
   on_event :agent_end do |event|
-    puts "Agent completed in #{event[:iterations]} iterations"
+    puts "Agent completed in #{event[:result].turns} turns"
   end
 end
 ```
@@ -349,9 +393,13 @@ end
 
 ```ruby
 agent = RubyPi::Agent.new(
-  model: model,
-  extensions: [MetricsExtension.new, AnotherExtension.new]
+  system_prompt: "You are helpful.",
+  model: model
 )
+
+# Register extensions using `use` — pass the CLASS, not an instance:
+agent.use(MetricsExtension)
+agent.use(AnotherExtension)
 ```
 
 Extensions receive the same event payloads as `agent.on(...)` callbacks. Use them when you want reusable, self-contained behavior modules.

data/lib/ruby_pi/agent/core.rb

@@ -45,6 +45,24 @@ module RubyPi
       # @return [RubyPi::Agent::State] the agent's mutable state
       attr_reader :state
 
+      # @return [Array<Class>] registered extension classes for introspection
+      attr_reader :extensions
+
+      # @return [RubyPi::Configuration, nil] per-agent configuration handle
+      #   exposed for inspection only — see {#config=} caveats below. The
+      #   actual provider config is resolved at model construction time:
+      #
+      #     custom = RubyPi::Configuration.new
+      #     custom.openai_api_key = "sk-..."
+      #     model = RubyPi::LLM.model(:openai, "gpt-4o", config: custom)
+      #     agent = RubyPi::Agent.new(model: model, config: custom, ...)
+      #
+      #   Passing `config:` to `Agent.new` does NOT retroactively change the
+      #   model's behavior — it is informational, intended for inspection by
+      #   transforms and extensions. To override provider config you must
+      #   pass `config:` to the model factory as shown above.
+      attr_reader :config
+
       # Creates a new Agent instance.
       #
       # @param system_prompt [String] the system-level instruction prompt
@@ -57,6 +75,17 @@ module RubyPi
       # @param after_tool_call [Proc, nil] post-tool-execution hook
       # @param compaction [RubyPi::Context::Compaction, nil] compaction strategy
       # @param user_data [Hash] arbitrary data bag for transforms/extensions
+      # @param config [RubyPi::Configuration, nil] informational handle to
+      #   the per-agent configuration. Stored for inspection by transforms
+      #   and extensions but does NOT override the model's provider config —
+      #   the model is already constructed by the time it reaches the agent.
+      #   To use a per-agent config for actual API calls, pass it to the
+      #   model factory:
+      #     RubyPi::LLM.model(:openai, "gpt-4o", config: custom_config)
+      # @param execution_mode [Symbol] tool execution mode (:parallel or :sequential,
+      #   default: :parallel)
+      # @param tool_timeout [Numeric] per-tool execution timeout in seconds
+      #   (default: 30)
       def initialize(
         system_prompt:,
         model:,
@@ -67,7 +96,10 @@ module RubyPi
         before_tool_call: nil,
         after_tool_call: nil,
         compaction: nil,
-        user_data: {}
+        user_data: {},
+        config: nil,
+        execution_mode: :parallel,
+        tool_timeout: 30
       )
         @state = State.new(
           system_prompt: system_prompt,
@@ -82,15 +114,24 @@ module RubyPi
         )
         @compaction = compaction
         @extensions = []
+        @config = config
+        @execution_mode = execution_mode
+        @tool_timeout = tool_timeout
       end
 
       # Runs the agent with an initial user prompt. Adds the prompt to the
       # conversation history, executes the think-act-observe loop, emits
       # :agent_end when done, and returns the result.
       #
+      # Issue #16: Resets the iteration counter at the start of each run()
+      # call using the encapsulated reset_iteration! method. Previously,
+      # the counter was never reset on run(), so a second call to run()
+      # on the same agent instance could immediately trip max_iterations_reached?.
+      #
       # @param prompt [String] the user's initial message
       # @return [RubyPi::Agent::Result] the outcome of the agent run
       def run(prompt)
+        @state.reset_iteration!
         @state.add_message(role: :user, content: prompt)
         execute_loop
       end
@@ -99,11 +140,14 @@ module RubyPi
       # the existing conversation history and appends the new prompt before
       # resuming the loop.
       #
+      # Issue #16: Uses the encapsulated reset_iteration! method instead of
+      # the old approach that bypassed encapsulation
+      # and was fragile.
+      #
       # @param prompt [String] the follow-up user message
       # @return [RubyPi::Agent::Result] the outcome of the continued run
       def continue(prompt)
-        # Reset the iteration counter for the new run while keeping history
-        @state.instance_variable_set(:@iteration, 0)
+        @state.reset_iteration!
         @state.add_message(role: :user, content: prompt)
         execute_loop
       end
@@ -132,6 +176,15 @@ module RubyPi
         @extensions << extension_class
       end
 
+      # Returns the effective configuration for this agent. If a per-agent
+      # config was provided, returns that; otherwise falls back to the
+      # global RubyPi.configuration.
+      #
+      # @return [RubyPi::Configuration] the active configuration
+      def effective_config
+        @config || RubyPi.configuration
+      end
+
       private
 
       # Creates a Loop instance and executes it, emitting :agent_end when
@@ -142,7 +195,9 @@ module RubyPi
         loop_runner = Loop.new(
           state: @state,
           emitter: self,
-          compaction: @compaction
+          compaction: @compaction,
+          execution_mode: @execution_mode,
+          tool_timeout: @tool_timeout
         )
 
         result = loop_runner.run

data/lib/ruby_pi/agent/events.rb

@@ -14,6 +14,7 @@ module RubyPi
     # represents a specific moment or occurrence:
     #
     # - :text_delta           — An incremental text chunk from the LLM stream.
+    # - :tool_call_delta      — An incremental tool call chunk from the LLM stream.
     # - :tool_execution_start — A tool is about to be executed.
     # - :tool_execution_end   — A tool has finished executing.
     # - :turn_start           — A new think-act-observe cycle is beginning.
@@ -21,8 +22,13 @@ module RubyPi
     # - :agent_end            — The agent has finished its run (final event).
     # - :error                — A recoverable or fatal error occurred.
     # - :compaction           — Context compaction was triggered.
+    # - :provider_fallback    — A Fallback provider switched from primary
+    #                           to backup mid-stream. Subscribers should
+    #                           discard any partial text_delta output that
+    #                           arrived before this event.
     EVENTS = %i[
       text_delta
+      tool_call_delta
       tool_execution_start
       tool_execution_end
       turn_start
@@ -30,6 +36,7 @@ module RubyPi
       agent_end
       error
       compaction
+      provider_fallback
     ].freeze
 
     # Mixin that adds event subscription and emission to any class. Include
@@ -65,6 +72,12 @@ module RubyPi
       # rescued individually — one failing handler does not prevent others
       # from executing.
       #
+      # If a handler raises during a non-error event, the error is re-emitted
+      # as an :error event so subscribers can observe it. To prevent infinite
+      # recursion, errors raised inside :error event handlers are silently
+      # swallowed — they are not re-emitted. This ensures that a broken error
+      # handler cannot crash the agent loop.
+      #
       # @param event [Symbol] the event type to fire
       # @param data [Hash] arbitrary payload passed to each handler
       # @return [void]
@@ -73,9 +86,10 @@ module RubyPi
         event_handlers[event].each do |handler|
           handler.call(data)
         rescue StandardError => e
-          # Log but do not propagate handler errors — they should not break
-          # the agent loop. Emit an :error event if this is not already an
-          # error event (to prevent infinite recursion).
+          # Guard against infinite recursion: if we are already emitting an
+          # :error event and the error handler itself raises, we must not
+          # re-emit — that would cause unbounded recursion. Silently discard
+          # the secondary error instead.
           if event != :error
             emit(:error, error: e, source: :event_handler, event: event)
           end