ruby-pi 0.1.6 → 0.1.9

data/lib/ruby_pi/llm/stream_event.rb

@@ -25,10 +25,10 @@ module RubyPi
     #   end
     class StreamEvent
       # Valid event types for stream events.
-      VALID_TYPES = %i[text_delta tool_call_delta done fallback_start].freeze
+      VALID_TYPES = %i[text_delta tool_call_delta done retry_start fallback_start].freeze
 
       # @return [Symbol] the type of stream event — one of :text_delta,
-      #   :tool_call_delta, :done, or :fallback_start
+      #   :tool_call_delta, :done, :retry_start, or :fallback_start
       attr_reader :type
 
       # @return [Object] the event payload. For :text_delta this is a String
@@ -38,7 +38,8 @@ module RubyPi
 
       # Creates a new StreamEvent instance.
       #
-      # @param type [Symbol] event type (:text_delta, :tool_call_delta, :done, :fallback_start)
+      # @param type [Symbol] event type (:text_delta, :tool_call_delta, :done,
+      #   :retry_start, :fallback_start)
       # @param data [Object] event payload
       # @raise [ArgumentError] if the type is not recognized
       def initialize(type:, data: nil)
@@ -71,6 +72,12 @@ module RubyPi
         @type == :done
       end
 
+      # Returns true when a failed streaming attempt is being discarded and
+      # the same provider is about to retry from the beginning.
+      def retry_start?
+        @type == :retry_start
+      end
+
       # Returns true if this is a fallback_start event, signaling that the
       # primary provider failed mid-stream and the fallback provider is
       # taking over. Consumers should clear any partial output rendered

data/lib/ruby_pi/llm/tool_call.rb

@@ -6,6 +6,8 @@
 # decides to invoke a tool, it returns one or more ToolCall objects describing
 # which function to call and with what arguments.
 
+require "json"
+
 module RubyPi
   module LLM
     # A tool call extracted from an LLM response. Contains the unique call ID,

data/lib/ruby_pi/tools/definition.rb

@@ -37,16 +37,32 @@ module RubyPi
       # @return [Hash] A JSON Schema hash describing the tool's parameters.
       attr_reader :parameters
 
+      # Tool names must satisfy the strictest provider constraint (Anthropic's
+      # ^[a-zA-Z0-9_-]{1,64}$). Without this guard, a name like "send.email"
+      # registers fine and then 400s on every API request with an opaque
+      # server-side validation error that doesn't point back to the tool.
+      NAME_FORMAT = /\A[a-zA-Z0-9_-]{1,64}\z/
+
       # Creates a new tool definition.
       #
-      # @param name [String, Symbol] Unique identifier for the tool.
+      # @param name [String, Symbol] Unique identifier for the tool. Must match
+      #   NAME_FORMAT (letters, digits, underscore, hyphen; max 64 chars).
       # @param description [String] What the tool does (shown to the LLM).
       # @param category [Symbol, nil] Optional grouping category.
       # @param parameters [Hash] JSON Schema hash for the tool's input parameters.
-      # @yield [Hash] Block that implements the tool logic. Receives a hash of arguments.
-      # @raise [ArgumentError] If name or description is missing, or no block given.
+      # @yield [Hash] Block that implements the tool logic. Receives a hash of
+      #   symbol-keyed arguments, or keyword arguments if the block declares
+      #   keyword parameters (see #call).
+      # @raise [ArgumentError] If name is missing or violates NAME_FORMAT,
+      #   description is missing, or no block given.
       def initialize(name:, description:, category: nil, parameters: {}, &block)
         raise ArgumentError, "Tool name is required" if name.nil? || name.to_s.strip.empty?
+        unless name.to_s.match?(NAME_FORMAT)
+          raise ArgumentError,
+                "Tool name #{name.to_s.inspect} is invalid — provider APIs require " \
+                "names matching #{NAME_FORMAT.inspect} (letters, digits, underscore, " \
+                "hyphen; 1-64 characters)"
+        end
         raise ArgumentError, "Tool description is required" if description.nil? || description.strip.empty?
         raise ArgumentError, "Tool implementation block is required" unless block_given?
 
@@ -55,14 +71,33 @@ module RubyPi
         @category = category&.to_sym
         @parameters = parameters
         @implementation = block
+        # On Ruby 3.x a positional Hash is never auto-splatted to keywords, so
+        # a block written `{ |content:, platform:| ... }` — the natural style
+        # given named schema parameters — would fail every call with
+        # "missing keyword". Detect keyword parameters once here and splat in
+        # #call accordingly.
+        @expects_keywords = block.parameters.any? { |type, _| %i[key keyreq keyrest].include?(type) }
       end
 
       # Invokes the tool with the given arguments.
       #
+      # Blocks may be written either style:
+      #   { |args| args[:content] }            # single positional Hash
+      #   { |content:, platform: "x"| ... }    # keyword parameters
+      #
+      # When the block declares keyword parameters, the arguments hash is
+      # splatted to keywords. Note that a keyword-style block without **rest
+      # raises ArgumentError on unexpected keys — strict by design, since the
+      # keys come from the LLM.
+      #
       # @param args [Hash] The arguments to pass to the tool implementation.
       # @return [Object] Whatever the implementation block returns.
       def call(args = {})
-        @implementation.call(args)
+        if @expects_keywords
+          @implementation.call(**args)
+        else
+          @implementation.call(args)
+        end
       end
 
       # Converts this tool definition to Google Gemini function declaration format.

data/lib/ruby_pi/tools/executor.rb

@@ -115,7 +115,12 @@ module RubyPi
         end
 
         # Collect results, respecting the configured timeout for each future.
-        futures.map do |future|
+        # Zip each future with its originating call so failure Results carry
+        # the real tool name — with several tools timing out in parallel,
+        # "unknown" Results are indistinguishable in logs and extension events.
+        calls.zip(futures).map do |call, future|
+          tool_name = (call[:name] || call["name"]).to_s
+
           # Issue #10: Wait for the future to complete, then check its state
           # explicitly. Future#value returns nil both on timeout AND when the
           # block legitimately returned nil, so we cannot use || to distinguish.
@@ -128,13 +133,16 @@ module RubyPi
             else
               # Future was rejected (raised an exception within the block).
               # This shouldn't normally happen since execute_single rescues
-              # internally, but handle it defensively.
+              # internally, but handle it defensively. The actual run time is
+              # unknown here (the future failed at some point before the wait
+              # elapsed), so report 0.0 rather than a misleading full-timeout
+              # duration for what may have been an instant failure.
               error = future.reason
               Result.new(
-                name: "unknown",
+                name: tool_name,
                 success: false,
                 error: "#{error.class}: #{error.message}",
-                duration_ms: @timeout * 1000.0
+                duration_ms: 0.0
               )
             end
           else
@@ -147,9 +155,9 @@ module RubyPi
             future.cancel if future.respond_to?(:cancel)
 
             Result.new(
-              name: "unknown",
+              name: tool_name,
               success: false,
-              error: "Tool execution timed out after #{@timeout}s",
+              error: "Tool '#{tool_name}' timed out after #{@timeout}s",
               duration_ms: @timeout * 1000.0
             )
           end

data/lib/ruby_pi/tools/schema.rb

@@ -13,6 +13,16 @@
 # flag consumed by `.object` to populate the top-level "required" array.
 # It is stripped from the property's own schema hash before inclusion.
 #
+# IMPORTANT: Schemas are LLM-facing hints, NOT runtime input validation.
+# Nothing in the execution pipeline validates the model's arguments against
+# the schema before invoking the tool block: `required`, `enum`, `minimum`,
+# and type declarations constrain what the model is *asked* to produce, but a
+# misbehaving model can still omit required fields, send extra keys, or pass
+# a String where an Integer is declared — no coercion is performed. Tool
+# blocks should treat their arguments as untrusted input and validate or
+# coerce what they depend on. (This is deliberate, per the anti-framework
+# philosophy: validation policy belongs to the tool, not the harness.)
+#
 # Usage:
 #   schema = RubyPi::Schema.object(
 #     name: RubyPi::Schema.string("User's name", required: true),

data/lib/ruby_pi/version.rb

@@ -7,5 +7,5 @@
 
 module RubyPi
   # The current version of the RubyPi gem, following Semantic Versioning.
-  VERSION = "0.1.6"
+  VERSION = "0.1.9"
 end

data/lib/ruby_pi.rb

@@ -82,6 +82,13 @@ module RubyPi
     end
   end
 
+  # Eagerly initialize the global configuration at load time. The lazy
+  # `@configuration ||= ...` in .configuration is not synchronized; two
+  # threads hitting it concurrently on first access could each construct a
+  # Configuration, with one silently discarded. Initializing here (requires
+  # run single-threaded) removes the race without adding a mutex to every read.
+  @configuration = Configuration.new
+
   # Namespace for large language model providers and related abstractions.
   module LLM
     class << self

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby-pi
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.9
 platform: ruby
 authors:
 - RubyPi Contributors
 bindir: bin
 cert_chain: []
-date: 2026-05-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -157,7 +171,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.16
 specification_version: 4
 summary: AI agent harness for Ruby — build LLM agents with tool calling, streaming,
   and a unified interface to OpenAI, Anthropic Claude, and Google Gemini.