ruby_llm_swarm 1.9.1

data/lib/ruby_llm/stream_accumulator.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Assembles streaming responses from LLMs into complete messages.
+  class StreamAccumulator
+    attr_reader :content, :model_id, :tool_calls
+
+    def initialize
+      @content = +''
+      @tool_calls = {}
+      @input_tokens = nil
+      @output_tokens = nil
+      @cached_tokens = nil
+      @cache_creation_tokens = nil
+      @latest_tool_call_id = nil
+    end
+
+    def add(chunk)
+      RubyLLM.logger.debug chunk.inspect if RubyLLM.config.log_stream_debug
+      @model_id ||= chunk.model_id
+
+      if chunk.tool_call?
+        accumulate_tool_calls chunk.tool_calls
+      else
+        @content << (chunk.content || '')
+      end
+
+      count_tokens chunk
+      RubyLLM.logger.debug inspect if RubyLLM.config.log_stream_debug
+    end
+
+    def to_message(response)
+      Message.new(
+        role: :assistant,
+        content: content.empty? ? nil : content,
+        model_id: model_id,
+        tool_calls: tool_calls_from_stream,
+        input_tokens: @input_tokens,
+        output_tokens: @output_tokens,
+        cached_tokens: @cached_tokens,
+        cache_creation_tokens: @cache_creation_tokens,
+        raw: response
+      )
+    end
+
+    private
+
+    def tool_calls_from_stream
+      tool_calls.transform_values do |tc|
+        arguments = if tc.arguments.is_a?(String) && !tc.arguments.empty?
+                      JSON.parse(tc.arguments)
+                    elsif tc.arguments.is_a?(String)
+                      {}
+                    else
+                      tc.arguments
+                    end
+
+        ToolCall.new(
+          id: tc.id,
+          name: tc.name,
+          arguments: arguments
+        )
+      end
+    end
+
+    def accumulate_tool_calls(new_tool_calls)
+      RubyLLM.logger.debug "Accumulating tool calls: #{new_tool_calls}" if RubyLLM.config.log_stream_debug
+      new_tool_calls.each_value do |tool_call|
+        if tool_call.id
+          tool_call_id = tool_call.id.empty? ? SecureRandom.uuid : tool_call.id
+          tool_call_arguments = tool_call.arguments.empty? ? +'' : tool_call.arguments
+          @tool_calls[tool_call.id] = ToolCall.new(
+            id: tool_call_id,
+            name: tool_call.name,
+            arguments: tool_call_arguments
+          )
+          @latest_tool_call_id = tool_call.id
+        else
+          existing = @tool_calls[@latest_tool_call_id]
+          existing.arguments << tool_call.arguments if existing
+        end
+      end
+    end
+
+    def find_tool_call(tool_call_id)
+      if tool_call_id.nil?
+        @tool_calls[@latest_tool_call]
+      else
+        @latest_tool_call_id = tool_call_id
+        @tool_calls[tool_call_id]
+      end
+    end
+
+    def count_tokens(chunk)
+      @input_tokens = chunk.input_tokens if chunk.input_tokens
+      @output_tokens = chunk.output_tokens if chunk.output_tokens
+      @cached_tokens = chunk.cached_tokens if chunk.cached_tokens
+      @cache_creation_tokens = chunk.cache_creation_tokens if chunk.cache_creation_tokens
+    end
+  end
+end

data/lib/ruby_llm/streaming.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Handles streaming responses from AI providers.
+  module Streaming
+    module_function
+
+    def stream_response(connection, payload, additional_headers = {}, &block)
+      accumulator = StreamAccumulator.new
+
+      response = connection.post stream_url, payload do |req|
+        req.headers = additional_headers.merge(req.headers) unless additional_headers.empty?
+        if faraday_1?
+          req.options[:on_data] = handle_stream do |chunk|
+            accumulator.add chunk
+            block.call chunk
+          end
+        else
+          req.options.on_data = handle_stream do |chunk|
+            accumulator.add chunk
+            block.call chunk
+          end
+        end
+      end
+
+      message = accumulator.to_message(response)
+      RubyLLM.logger.debug "Stream completed: #{message.content}"
+      message
+    end
+
+    def handle_stream(&block)
+      to_json_stream do |data|
+        block.call(build_chunk(data)) if data
+      end
+    end
+
+    private
+
+    def faraday_1?
+      Faraday::VERSION.start_with?('1')
+    end
+
+    def to_json_stream(&)
+      buffer = +''
+      parser = EventStreamParser::Parser.new
+
+      create_stream_processor(parser, buffer, &)
+    end
+
+    def create_stream_processor(parser, buffer, &)
+      if faraday_1?
+        legacy_stream_processor(parser, &)
+      else
+        stream_processor(parser, buffer, &)
+      end
+    end
+
+    def process_stream_chunk(chunk, parser, env, &)
+      RubyLLM.logger.debug "Received chunk: #{chunk}" if RubyLLM.config.log_stream_debug
+
+      if error_chunk?(chunk)
+        handle_error_chunk(chunk, env)
+      else
+        yield handle_sse(chunk, parser, env, &)
+      end
+    end
+
+    def legacy_stream_processor(parser, &block)
+      proc do |chunk, _size|
+        process_stream_chunk(chunk, parser, nil, &block)
+      end
+    end
+
+    def stream_processor(parser, buffer, &block)
+      proc do |chunk, _bytes, env|
+        if env&.status == 200
+          process_stream_chunk(chunk, parser, env, &block)
+        else
+          handle_failed_response(chunk, buffer, env)
+        end
+      end
+    end
+
+    def error_chunk?(chunk)
+      chunk.start_with?('event: error')
+    end
+
+    def handle_error_chunk(chunk, env)
+      error_data = chunk.split("\n")[1].delete_prefix('data: ')
+      status, _message = parse_streaming_error(error_data)
+      parsed_data = JSON.parse(error_data)
+
+      error_response = if faraday_1?
+                         Struct.new(:body, :status).new(parsed_data, status)
+                       else
+                         env.merge(body: parsed_data, status: status)
+                       end
+
+      ErrorMiddleware.parse_error(provider: self, response: error_response)
+    rescue JSON::ParserError => e
+      RubyLLM.logger.debug "Failed to parse error chunk: #{e.message}"
+    end
+
+    def handle_failed_response(chunk, buffer, env)
+      buffer << chunk
+      error_data = JSON.parse(buffer)
+      error_response = env.merge(body: error_data)
+      ErrorMiddleware.parse_error(provider: self, response: error_response)
+    rescue JSON::ParserError
+      RubyLLM.logger.debug "Accumulating error chunk: #{chunk}"
+    end
+
+    def handle_sse(chunk, parser, env, &block)
+      parser.feed(chunk) do |type, data|
+        case type.to_sym
+        when :error
+          handle_error_event(data, env)
+        else
+          yield handle_data(data, &block) unless data == '[DONE]'
+        end
+      end
+    end
+
+    def handle_data(data)
+      JSON.parse(data)
+    rescue JSON::ParserError => e
+      RubyLLM.logger.debug "Failed to parse data chunk: #{e.message}"
+    end
+
+    def handle_error_event(data, env)
+      status, _message = parse_streaming_error(data)
+      parsed_data = JSON.parse(data)
+
+      error_response = if faraday_1?
+                         Struct.new(:body, :status).new(parsed_data, status)
+                       else
+                         env.merge(body: parsed_data, status: status)
+                       end
+
+      ErrorMiddleware.parse_error(provider: self, response: error_response)
+    rescue JSON::ParserError => e
+      RubyLLM.logger.debug "Failed to parse error event: #{e.message}"
+    end
+
+    def parse_streaming_error(data)
+      error_data = JSON.parse(data)
+      [500, error_data['message'] || 'Unknown streaming error']
+    rescue JSON::ParserError => e
+      RubyLLM.logger.debug "Failed to parse streaming error: #{e.message}"
+      [500, "Failed to parse error: #{data}"]
+    end
+  end
+end

data/lib/ruby_llm/tool.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'ruby_llm/schema'
+
+module RubyLLM
+  # Parameter definition for Tool methods.
+  class Parameter
+    attr_reader :name, :type, :description, :required
+
+    def initialize(name, type: 'string', desc: nil, required: true)
+      @name = name
+      @type = type
+      @description = desc
+      @required = required
+    end
+  end
+
+  # Base class for creating tools that AI models can use
+  class Tool
+    # Stops conversation continuation after tool execution
+    class Halt
+      attr_reader :content
+
+      def initialize(content)
+        @content = content
+      end
+
+      def to_s
+        @content.to_s
+      end
+    end
+
+    class << self
+      attr_reader :params_schema_definition
+
+      def description(text = nil)
+        return @description unless text
+
+        @description = text
+      end
+
+      def param(name, **options)
+        parameters[name] = Parameter.new(name, **options)
+      end
+
+      def parameters
+        @parameters ||= {}
+      end
+
+      def params(schema = nil, &block)
+        @params_schema_definition = SchemaDefinition.new(schema:, block:)
+        self
+      end
+
+      def with_params(**params)
+        @provider_params = params
+        self
+      end
+
+      def provider_params
+        @provider_params ||= {}
+      end
+    end
+
+    def name
+      klass_name = self.class.name
+      normalized = klass_name.to_s.dup.force_encoding('UTF-8').unicode_normalize(:nfkd)
+      normalized.encode('ASCII', replace: '')
+                .gsub(/[^a-zA-Z0-9_-]/, '-')
+                .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                .downcase
+                .delete_suffix('_tool')
+    end
+
+    def description
+      self.class.description
+    end
+
+    def parameters
+      self.class.parameters
+    end
+
+    def provider_params
+      self.class.provider_params
+    end
+
+    def params_schema
+      return @params_schema if defined?(@params_schema)
+
+      @params_schema = begin
+        definition = self.class.params_schema_definition
+        if definition&.present?
+          definition.json_schema
+        elsif parameters.any?
+          SchemaDefinition.from_parameters(parameters)&.json_schema
+        end
+      end
+    end
+
+    def call(args)
+      RubyLLM.logger.debug "Tool #{name} called with: #{args.inspect}"
+      result = execute(**args.transform_keys(&:to_sym))
+      RubyLLM.logger.debug "Tool #{name} returned: #{result.inspect}"
+      result
+    end
+
+    def execute(...)
+      raise NotImplementedError, 'Subclasses must implement #execute'
+    end
+
+    protected
+
+    def halt(message)
+      Halt.new(message)
+    end
+
+    # Wraps schema handling for tool parameters, supporting JSON Schema hashes,
+    # RubyLLM::Schema instances/classes, and DSL blocks.
+    class SchemaDefinition
+      def self.from_parameters(parameters)
+        return nil if parameters.nil? || parameters.empty?
+
+        properties = parameters.to_h do |name, param|
+          schema = {
+            type: map_type(param.type),
+            description: param.description
+          }.compact
+
+          schema[:items] = default_items_schema if schema[:type] == 'array'
+
+          [name.to_s, schema]
+        end
+
+        required = parameters.select { |_, param| param.required }.keys.map(&:to_s)
+
+        json_schema = {
+          type: 'object',
+          properties: properties,
+          required: required,
+          additionalProperties: false,
+          strict: true
+        }
+
+        new(schema: json_schema)
+      end
+
+      def self.map_type(type)
+        case type.to_s
+        when 'integer', 'int' then 'integer'
+        when 'number', 'float', 'double' then 'number'
+        when 'boolean' then 'boolean'
+        when 'array' then 'array'
+        when 'object' then 'object'
+        else
+          'string'
+        end
+      end
+
+      def self.default_items_schema
+        { type: 'string' }
+      end
+
+      def initialize(schema: nil, block: nil)
+        @schema = schema
+        @block = block
+      end
+
+      def present?
+        @schema || @block
+      end
+
+      def json_schema
+        @json_schema ||= RubyLLM::Utils.deep_stringify_keys(resolve_schema)
+      end
+
+      private
+
+      def resolve_schema
+        return resolve_direct_schema(@schema) if @schema
+        return build_from_block(&@block) if @block
+
+        nil
+      end
+
+      def resolve_direct_schema(schema)
+        return extract_schema(schema.to_json_schema) if schema.respond_to?(:to_json_schema)
+        return RubyLLM::Utils.deep_dup(schema) if schema.is_a?(Hash)
+        if schema.is_a?(Class) && schema.instance_methods.include?(:to_json_schema)
+          return extract_schema(schema.new.to_json_schema)
+        end
+
+        nil
+      end
+
+      def build_from_block(&)
+        schema_class = RubyLLM::Schema.create(&)
+        extract_schema(schema_class.new.to_json_schema)
+      end
+
+      def extract_schema(schema_hash)
+        return nil unless schema_hash.is_a?(Hash)
+
+        schema = schema_hash[:schema] || schema_hash['schema'] || schema_hash
+        RubyLLM::Utils.deep_dup(schema)
+      end
+    end
+  end
+end

data/lib/ruby_llm/tool_call.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Represents a function call from an AI model to a Tool.
+  class ToolCall
+    attr_reader :id, :name, :arguments
+
+    def initialize(id:, name:, arguments: {})
+      @id = id
+      @name = name
+      @arguments = arguments
+    end
+
+    def to_h
+      {
+        id: @id,
+        name: @name,
+        arguments: @arguments
+      }
+    end
+  end
+end

data/lib/ruby_llm/tool_executors.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Built-in tool executors for concurrent tool execution.
+  # These are registered automatically when RubyLLM is loaded.
+  module ToolExecutors
+    class << self
+      # Registers the built-in executors.
+      # Called automatically when RubyLLM is loaded.
+      def register_defaults
+        register_threads_executor
+        register_async_executor
+      end
+
+      private
+
+      # Thread-based executor using Ruby's native threads.
+      # Uses only stdlib - no external dependencies.
+      # Good for broad compatibility and CPU-bound operations.
+      def register_threads_executor
+        RubyLLM.register_tool_executor(:threads) do |tool_calls, max_concurrency:, &execute|
+          results = {}
+          mutex = Mutex.new
+          semaphore = max_concurrency ? Thread::SizedQueue.new(max_concurrency) : nil
+
+          # Fill semaphore with permits
+          max_concurrency&.times { semaphore << :permit }
+
+          threads = tool_calls.map do |tool_call|
+            Thread.new do
+              # Acquire permit (blocks if none available)
+              permit = semaphore&.pop
+
+              begin
+                result = execute.call(tool_call)
+                mutex.synchronize { results[tool_call.id] = result }
+              rescue StandardError => e
+                # Store error as result so LLM sees it
+                error_result = "Error: #{e.class}: #{e.message}"
+                mutex.synchronize { results[tool_call.id] = error_result }
+                RubyLLM.logger.warn "[RubyLLM] Tool #{tool_call.id} failed: #{e.message}"
+              ensure
+                # Release permit
+                semaphore&.push(permit) if permit
+              end
+            end
+          end
+
+          threads.each(&:join)
+          results
+        end
+      end
+
+      # Async-based executor using the async gem.
+      # Uses lightweight fibers for I/O-bound operations.
+      # Requires the async gem to be installed.
+      def register_async_executor
+        RubyLLM.register_tool_executor(:async) do |tool_calls, max_concurrency:, &execute|
+          AsyncExecutor.execute(tool_calls, max_concurrency: max_concurrency, &execute)
+        end
+      end
+    end
+
+    # Internal implementation for async executor.
+    # Separated to keep block size manageable.
+    module AsyncExecutor
+      class << self
+        def execute(tool_calls, max_concurrency:, &block)
+          load_async_gem
+          run_with_sync { execute_tools(tool_calls, max_concurrency, &block) }
+        end
+
+        private
+
+        def load_async_gem
+          require 'async'
+          require 'async/barrier'
+          require 'async/semaphore'
+        rescue LoadError => e
+          raise LoadError,
+                'The async gem is required for :async tool executor. ' \
+                "Add `gem 'async'` to your Gemfile. Original error: #{e.message}"
+        end
+
+        def run_with_sync(&)
+          # Use Kernel#Sync if available (async 2.x), otherwise Async{}.wait
+          if defined?(Sync)
+            Sync(&)
+          else
+            Async(&).wait
+          end
+        end
+
+        def execute_tools(tool_calls, max_concurrency)
+          semaphore = max_concurrency ? Async::Semaphore.new(max_concurrency) : nil
+          barrier = Async::Barrier.new
+          results = {}
+
+          tool_calls.each do |tool_call|
+            barrier.async do
+              results[tool_call.id] = execute_single_tool(tool_call, semaphore) { yield tool_call }
+            rescue StandardError => e
+              results[tool_call.id] = "Error: #{e.class}: #{e.message}"
+              RubyLLM.logger.warn "[RubyLLM] Tool #{tool_call.id} failed: #{e.message}"
+            end
+          end
+
+          barrier.wait
+          results
+        end
+
+        def execute_single_tool(_tool_call, semaphore, &)
+          if semaphore
+            semaphore.acquire(&)
+          else
+            yield
+          end
+        end
+      end
+    end
+  end
+end
+
+# Register built-in executors when this file is loaded
+RubyLLM::ToolExecutors.register_defaults

data/lib/ruby_llm/transcription.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Represents a transcription of audio content.
+  class Transcription
+    attr_reader :text, :model, :language, :duration, :segments, :input_tokens, :output_tokens
+
+    def initialize(text:, model:, **attributes)
+      @text = text
+      @model = model
+      @language = attributes[:language]
+      @duration = attributes[:duration]
+      @segments = attributes[:segments]
+      @input_tokens = attributes[:input_tokens]
+      @output_tokens = attributes[:output_tokens]
+    end
+
+    def self.transcribe(audio_file, **kwargs)
+      model = kwargs.delete(:model)
+      language = kwargs.delete(:language)
+      provider = kwargs.delete(:provider)
+      assume_model_exists = kwargs.delete(:assume_model_exists) { false }
+      context = kwargs.delete(:context)
+      options = kwargs
+
+      config = context&.config || RubyLLM.config
+      model ||= config.default_transcription_model
+      model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
+                                                       config: config)
+      model_id = model.id
+
+      provider_instance.transcribe(audio_file, model: model_id, language:, **options)
+    end
+  end
+end