open_router_enhanced 1.0.0

data/lib/open_router/schema.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+begin
+  require "json-schema"
+rescue LoadError
+  # json-schema gem not available
+end
+
+module OpenRouter
+  class SchemaValidationError < Error; end
+
+  class Schema
+    attr_reader :name, :strict, :schema
+
+    def initialize(name, schema_definition = {}, strict: true)
+      @name = name
+      @strict = strict
+      raise ArgumentError, "Schema definition must be a hash" unless schema_definition.is_a?(Hash)
+
+      @schema = schema_definition
+      validate_schema!
+    end
+
+    # Class method for defining schemas with a DSL
+    def self.define(name, strict: true, &block)
+      builder = SchemaBuilder.new
+      builder.instance_eval(&block) if block_given?
+      new(name, builder.to_h, strict:)
+    end
+
+    # Convert to the format expected by OpenRouter API
+    def to_h
+      # Apply OpenRouter-specific transformations
+      openrouter_schema = @schema.dup
+
+      # OpenRouter/Azure requires ALL properties to be in the required array
+      # even if they are logically optional. This is a deviation from JSON Schema spec
+      # but necessary for compatibility.
+      if openrouter_schema[:properties]&.any?
+        all_properties = openrouter_schema[:properties].keys.map(&:to_s)
+        openrouter_schema[:required] = all_properties
+      end
+
+      {
+        name: @name,
+        strict: @strict,
+        schema: openrouter_schema
+      }
+    end
+
+    # Get the pure JSON Schema (respects required flags) for testing/validation
+    def pure_schema
+      @schema
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Check if JSON schema validation is available
+    def validation_available?
+      !!defined?(JSON::Validator)
+    end
+
+    # Validate data against this schema
+    def validate(data)
+      return true unless defined?(JSON::Validator)
+
+      JSON::Validator.validate(@schema, data)
+    end
+
+    # Get validation errors for data
+    def validation_errors(data)
+      return [] unless defined?(JSON::Validator)
+
+      JSON::Validator.fully_validate(@schema, data)
+    end
+
+    # Generate format instructions for model prompting
+    def get_format_instructions(forced: false)
+      schema_json = to_h.to_json
+
+      if forced
+        <<~INSTRUCTIONS
+          You must format your output as a JSON value that conforms exactly to the following JSON Schema specification:
+
+          #{schema_json}
+
+          CRITICAL: Your entire response must be valid JSON that matches this schema. Do not include any text before or after the JSON. Return ONLY the JSON value itself - no other text, explanations, or formatting.
+
+          example format:
+          ```json
+          {"field1": "value1", "field2": "value2"}
+          ```
+
+          Important guidelines:
+          - Ensure all required fields match the schema exactly
+          - Use proper JSON formatting (no trailing commas)
+          - All string values must be properly quoted
+        INSTRUCTIONS
+      else
+        <<~INSTRUCTIONS
+          Please format your output as a JSON value that conforms to the following JSON Schema specification:
+
+          #{schema_json}
+
+          Your response should be valid JSON that matches this schema structure exactly.
+
+          example format:
+          ```json
+          {"field1": "value1", "field2": "value2"}
+          ```
+
+          Important guidelines:
+          - Ensure all required fields match the schema
+          - Use proper JSON formatting (no trailing commas)
+          - Return ONLY the JSON - no other text or explanations
+        INSTRUCTIONS
+      end
+    end
+
+    private
+
+    def validate_schema!
+      raise ArgumentError, "Schema name is required" if @name.nil? || @name.empty?
+      raise ArgumentError, "Schema must be a hash" unless @schema.is_a?(Hash)
+    end
+
+    # Internal class for building schemas with DSL
+    class SchemaBuilder
+      def initialize
+        @schema = {
+          type: "object",
+          properties: {},
+          required: []
+        }
+        @strict_mode = true
+        # Set additionalProperties to false by default in strict mode
+        @schema[:additionalProperties] = false
+      end
+
+      def strict(value = true)
+        @strict_mode = value
+        additional_properties(!value)
+      end
+
+      def additional_properties(allowed = true)
+        @schema[:additionalProperties] = allowed
+      end
+
+      def no_additional_properties
+        additional_properties(false)
+      end
+
+      def property(name, type, required: false, description: nil, **options)
+        prop_def = { type: type.to_s }
+        prop_def[:description] = description if description
+        prop_def.merge!(options)
+
+        @schema[:properties][name] = prop_def
+        mark_required(name) if required
+      end
+
+      def string(name, required: false, description: nil, **options)
+        property(name, :string, required:, description:, **options)
+      end
+
+      def integer(name, required: false, description: nil, **options)
+        property(name, :integer, required:, description:, **options)
+      end
+
+      def number(name, required: false, description: nil, **options)
+        property(name, :number, required:, description:, **options)
+      end
+
+      def boolean(name, required: false, description: nil, **options)
+        property(name, :boolean, required:, description:, **options)
+      end
+
+      def array(name, required: false, description: nil, items: nil, &block)
+        array_def = { type: "array" }
+        array_def[:description] = description if description
+
+        if items
+          array_def[:items] = items
+        elsif block_given?
+          items_builder = ItemsBuilder.new
+          items_builder.instance_eval(&block)
+          array_def[:items] = items_builder.to_h
+        end
+
+        @schema[:properties][name] = array_def
+        mark_required(name) if required
+      end
+
+      def object(name, required: false, description: nil, &block)
+        object_def = {
+          type: "object",
+          properties: {},
+          required: []
+        }
+        object_def[:description] = description if description
+
+        if block_given?
+          object_builder = SchemaBuilder.new
+          object_builder.instance_eval(&block)
+          nested_schema = object_builder.to_h
+          object_def[:properties] = nested_schema[:properties]
+          object_def[:required] = nested_schema[:required]
+          if nested_schema.key?(:additionalProperties)
+            object_def[:additionalProperties] =
+              nested_schema[:additionalProperties]
+          end
+        end
+
+        @schema[:properties][name] = object_def
+        mark_required(name) if required
+      end
+
+      def required(*field_names)
+        field_names.each { |name| mark_required(name) }
+      end
+
+      def to_h
+        @schema.dup
+      end
+
+      private
+
+      def mark_required(name)
+        # Convert to string to match OpenRouter API expectations
+        string_name = name.to_s
+        @schema[:required] << string_name unless @schema[:required].include?(string_name)
+      end
+    end
+
+    # Internal class for building array items
+    class ItemsBuilder
+      def initialize
+        @items = {}
+      end
+
+      def string(description: nil, **options)
+        @items = { type: "string" }
+        @items[:description] = description if description
+        @items.merge!(options)
+      end
+
+      def integer(description: nil, **options)
+        @items = { type: "integer" }
+        @items[:description] = description if description
+        @items.merge!(options)
+      end
+
+      def number(description: nil, **options)
+        @items = { type: "number" }
+        @items[:description] = description if description
+        @items.merge!(options)
+      end
+
+      def boolean(description: nil, **options)
+        @items = { type: "boolean" }
+        @items[:description] = description if description
+        @items.merge!(options)
+      end
+
+      def object(&block)
+        @items = { type: "object", properties: {}, required: [], additionalProperties: false }
+
+        return unless block_given?
+
+        object_builder = SchemaBuilder.new
+        object_builder.instance_eval(&block)
+        nested_schema = object_builder.to_h
+        @items[:properties] = nested_schema[:properties]
+        @items[:required] = nested_schema[:required]
+        return unless nested_schema.key?(:additionalProperties)
+
+        @items[:additionalProperties] =
+          nested_schema[:additionalProperties]
+      end
+
+      def to_h
+        @items
+      end
+    end
+  end
+end

data/lib/open_router/streaming_client.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Enhanced streaming client with better event handling and response reconstruction
+  class StreamingClient < Client
+    # Initialize streaming client with additional streaming-specific options
+    def initialize(*args, **kwargs, &block)
+      super(*args, **kwargs, &block)
+      @streaming_callbacks = {
+        on_chunk: [],
+        on_start: [],
+        on_finish: [],
+        on_tool_call_chunk: [],
+        on_error: []
+      }
+    end
+
+    # Register streaming-specific callbacks
+    #
+    # @param event [Symbol] The streaming event to register for
+    # @param block [Proc] The callback to execute
+    # @return [self] Returns self for method chaining
+    def on_stream(event, &block)
+      unless @streaming_callbacks.key?(event)
+        valid_events = @streaming_callbacks.keys.join(", ")
+        raise ArgumentError, "Invalid streaming event: #{event}. Valid events are: #{valid_events}"
+      end
+
+      @streaming_callbacks[event] << block
+      self
+    end
+
+    # Enhanced streaming completion with better event handling and response reconstruction
+    #
+    # @param messages [Array<Hash>] Array of message hashes
+    # @param model [String|Array] Model identifier or array of models for fallback
+    # @param accumulate_response [Boolean] Whether to accumulate and return complete response
+    # @param extras [Hash] Additional parameters for the completion request
+    # @return [Response, nil] Complete response if accumulate_response is true, nil otherwise
+    def stream_complete(messages, model: "openrouter/auto", accumulate_response: true, **extras)
+      response_accumulator = ResponseAccumulator.new if accumulate_response
+
+      # Set up streaming handler
+      stream_handler = build_stream_handler(response_accumulator)
+
+      # Trigger start callback
+      trigger_streaming_callbacks(:on_start, { model: model, messages: messages })
+
+      begin
+        # Execute the streaming request
+        complete(messages, model: model, stream: stream_handler, **extras)
+
+        # Return accumulated response if requested
+        if accumulate_response && response_accumulator
+          final_response = response_accumulator.build_response
+          trigger_streaming_callbacks(:on_finish, final_response)
+          final_response
+        else
+          trigger_streaming_callbacks(:on_finish, nil)
+          nil
+        end
+      rescue StandardError => e
+        trigger_streaming_callbacks(:on_error, e)
+        raise
+      end
+    end
+
+    # Stream with a simple block interface
+    #
+    # @param messages [Array<Hash>] Array of message hashes
+    # @param model [String|Array] Model identifier
+    # @param block [Proc] Block to call for each content chunk
+    # @param extras [Hash] Additional parameters
+    #
+    # @example
+    #   client.stream(messages, model: "openai/gpt-4o-mini") do |chunk|
+    #     print chunk
+    #   end
+    def stream(messages, model: "openrouter/auto", **extras, &block)
+      raise ArgumentError, "Block required for streaming" unless block_given?
+
+      stream_complete(
+        messages,
+        model: model,
+        accumulate_response: false,
+        **extras
+      ) do |chunk|
+        content = extract_content_from_chunk(chunk)
+        block.call(content) if content
+      end
+    end
+
+    private
+
+    def build_stream_handler(accumulator)
+      proc do |chunk|
+        # Trigger chunk callback
+        trigger_streaming_callbacks(:on_chunk, chunk)
+
+        # Accumulate if needed
+        accumulator&.add_chunk(chunk)
+
+        # Handle tool call chunks
+        trigger_streaming_callbacks(:on_tool_call_chunk, chunk) if chunk.dig("choices", 0, "delta", "tool_calls")
+
+        # Also trigger general stream callbacks for backward compatibility
+        trigger_callbacks(:on_stream_chunk, chunk)
+      rescue StandardError => e
+        trigger_streaming_callbacks(:on_error, e)
+      end
+    end
+
+    def trigger_streaming_callbacks(event, data)
+      return unless @streaming_callbacks[event]
+
+      @streaming_callbacks[event].each do |callback|
+        callback.call(data)
+      rescue StandardError => e
+        warn "[OpenRouter] Streaming callback error for #{event}: #{e.message}"
+      end
+    end
+
+    def extract_content_from_chunk(chunk)
+      chunk.dig("choices", 0, "delta", "content")
+    end
+  end
+
+  # Accumulates streaming chunks to reconstruct a complete response
+  class ResponseAccumulator
+    def initialize
+      @chunks = []
+      @content_parts = []
+      @tool_calls = {}
+      @first_chunk = nil
+      @last_chunk = nil
+    end
+
+    # Add a streaming chunk
+    def add_chunk(chunk)
+      @chunks << chunk
+      @first_chunk ||= chunk
+      @last_chunk = chunk
+
+      process_chunk(chunk)
+    end
+
+    # Build final response object
+    def build_response
+      return nil if @chunks.empty?
+
+      # Build the complete response structure
+      response_data = build_response_structure
+
+      Response.new(response_data)
+    end
+
+    private
+
+    def process_chunk(chunk)
+      delta = chunk.dig("choices", 0, "delta")
+      return unless delta
+
+      # Accumulate content
+      if (content = delta["content"])
+        @content_parts << content
+      end
+
+      # Accumulate tool calls
+      if (tool_calls = delta["tool_calls"])
+        tool_calls.each do |tc|
+          index = tc["index"]
+          @tool_calls[index] ||= {
+            "id" => tc["id"],
+            "type" => tc["type"],
+            "function" => { "name" => "", "arguments" => "" }
+          }
+
+          @tool_calls[index]["function"]["name"] = tc["function"]["name"] if tc.dig("function", "name")
+
+          @tool_calls[index]["function"]["arguments"] += tc["function"]["arguments"] if tc.dig("function", "arguments")
+        end
+      end
+    end
+
+    def build_response_structure
+      choice = {
+        "index" => 0,
+        "message" => {
+          "role" => "assistant",
+          "content" => @content_parts.join
+        },
+        "finish_reason" => @last_chunk.dig("choices", 0, "finish_reason")
+      }
+
+      # Add tool calls if present
+      choice["message"]["tool_calls"] = @tool_calls.values unless @tool_calls.empty?
+
+      {
+        "id" => @first_chunk["id"],
+        "object" => @first_chunk["object"],
+        "created" => @first_chunk["created"],
+        "model" => @first_chunk["model"],
+        "choices" => [choice],
+        "usage" => @last_chunk["usage"],
+        "provider" => @first_chunk["provider"],
+        "system_fingerprint" => @first_chunk["system_fingerprint"]
+      }.compact
+    end
+  end
+end

data/lib/open_router/tool.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  class Tool
+    attr_reader :type, :function
+
+    def initialize(definition = {})
+      if definition.is_a?(Hash) && definition.key?(:function)
+        @type = definition[:type] || "function"
+        @function = definition[:function]
+      elsif definition.is_a?(Hash)
+        @type = "function"
+        @function = definition
+      else
+        raise ArgumentError, "Tool definition must be a hash"
+      end
+
+      validate_definition!
+    end
+
+    # Class method for defining tools with a DSL
+    def self.define(&block)
+      builder = ToolBuilder.new
+      builder.instance_eval(&block) if block_given?
+      new(builder.to_h)
+    end
+
+    def to_h
+      {
+        type: @type,
+        function: @function
+      }
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    def name
+      @function[:name]
+    end
+
+    def description
+      @function[:description]
+    end
+
+    def parameters
+      @function[:parameters]
+    end
+
+    private
+
+    def validate_definition!
+      raise ArgumentError, "Function must have a name" unless @function[:name]
+      raise ArgumentError, "Function must have a description" unless @function[:description]
+
+      return unless @function[:parameters] && @function[:parameters][:type] != "object"
+
+      raise ArgumentError,
+            "Function parameters must be an object"
+    end
+
+    # Internal class for building tool definitions with DSL
+    class ToolBuilder
+      def initialize
+        @definition = {
+          name: nil,
+          description: nil,
+          parameters: {
+            type: "object",
+            properties: {},
+            required: []
+          }
+        }
+      end
+
+      def name(value)
+        @definition[:name] = value
+      end
+
+      def description(value)
+        @definition[:description] = value
+      end
+
+      def parameters(&block)
+        param_builder = ParametersBuilder.new(@definition[:parameters])
+        param_builder.instance_eval(&block) if block_given?
+      end
+
+      def to_h
+        @definition
+      end
+    end
+
+    # Internal class for building parameter schemas
+    class ParametersBuilder
+      def initialize(params_hash)
+        @params = params_hash
+      end
+
+      def string(name, required: false, description: nil, **options)
+        add_property(name, { type: "string", description: }.merge(options).compact)
+        mark_required(name) if required
+      end
+
+      def integer(name, required: false, description: nil, **options)
+        add_property(name, { type: "integer", description: }.merge(options).compact)
+        mark_required(name) if required
+      end
+
+      def number(name, required: false, description: nil, **options)
+        add_property(name, { type: "number", description: }.merge(options).compact)
+        mark_required(name) if required
+      end
+
+      def boolean(name, required: false, description: nil, **options)
+        add_property(name, { type: "boolean", description: }.merge(options).compact)
+        mark_required(name) if required
+      end
+
+      def array(name, required: false, description: nil, items: nil, &block)
+        array_def = { type: "array", description: }.compact
+
+        if items
+          array_def[:items] = items
+        elsif block_given?
+          items_builder = ItemsBuilder.new
+          items_builder.instance_eval(&block)
+          array_def[:items] = items_builder.to_h
+        end
+
+        add_property(name, array_def)
+        mark_required(name) if required
+      end
+
+      def object(name, required: false, description: nil, &block)
+        object_def = {
+          type: "object",
+          description:,
+          properties: {},
+          required: []
+        }.compact
+
+        if block_given?
+          object_builder = ParametersBuilder.new(object_def)
+          object_builder.instance_eval(&block)
+        end
+
+        add_property(name, object_def)
+        mark_required(name) if required
+      end
+
+      private
+
+      def add_property(name, definition)
+        processed_definition = definition.transform_values { |value| value.is_a?(Proc) ? value.call : value }
+        @params[:properties][name] = processed_definition
+      end
+
+      def mark_required(name)
+        @params[:required] << name unless @params[:required].include?(name)
+      end
+    end
+
+    # Internal class for building array items
+    class ItemsBuilder
+      def initialize
+        @items = {}
+      end
+
+      def string(description: nil, **options)
+        @items = { type: "string", description: }.merge(options).compact
+      end
+
+      def integer(description: nil, **options)
+        @items = { type: "integer", description: }.merge(options).compact
+      end
+
+      def number(description: nil, **options)
+        @items = { type: "number", description: }.merge(options).compact
+      end
+
+      def boolean(description: nil, **options)
+        @items = { type: "boolean", description: }.merge(options).compact
+      end
+
+      def object(&block)
+        @items = {
+          type: "object",
+          properties: {},
+          required: [],
+          additionalProperties: false
+        }
+
+        return unless block_given?
+
+        nested = Tool::ParametersBuilder.new(@items)
+        nested.instance_eval(&block)
+      end
+
+      def items(schema = nil, &block)
+        # This method allows for `array { items { object { ... }}}` or `items(hash)`
+        if block_given?
+          # Block defines what each item in the array looks like
+          nested_builder = ItemsBuilder.new
+          nested_builder.instance_eval(&block)
+          @items = nested_builder.to_h
+        elsif schema.is_a?(Hash)
+          # Direct hash schema assignment
+          @items = schema
+        else
+          raise ArgumentError, "items must be called with either a hash or a block"
+        end
+      end
+
+      def to_h
+        @items
+      end
+    end
+  end
+end