dspy 0.30.1 → 0.31.0

data/lib/dspy/lm/adapters/ollama_adapter.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-require 'openai'
-
-module DSPy
-  class LM
-    class OllamaAdapter < OpenAIAdapter
-      DEFAULT_BASE_URL = 'http://localhost:11434/v1'
-      
-      def initialize(model:, api_key: nil, base_url: nil, structured_outputs: true)
-        # Ollama doesn't require API key for local instances
-        # But may need it for remote/protected instances
-        api_key ||= 'ollama' # OpenAI client requires non-empty key
-        base_url ||= DEFAULT_BASE_URL
-        
-        # Store base_url before calling super
-        @base_url = base_url
-        
-        # Don't call parent's initialize, do it manually to control client creation
-        @model = model
-        @api_key = api_key
-        @structured_outputs_enabled = structured_outputs
-        validate_configuration!
-        
-        # Create client with custom base URL
-        @client = OpenAI::Client.new(
-          api_key: @api_key,
-          base_url: @base_url
-        )
-      end
-      
-      def chat(messages:, signature: nil, response_format: nil, &block)
-        # For Ollama, we need to be more lenient with structured outputs
-        # as it may not fully support OpenAI's response_format spec
-        begin
-          super
-        rescue => e
-          # If structured output fails, retry with enhanced prompting
-          if @structured_outputs_enabled && signature && e.message.include?('response_format')
-            DSPy.logger.debug("Ollama structured output failed, falling back to enhanced prompting")
-            @structured_outputs_enabled = false
-            retry
-          else
-            raise
-          end
-        end
-      end
-      
-      private
-      
-      def validate_configuration!
-        super
-        # Additional Ollama-specific validation could go here
-      end
-      
-      def validate_api_key!(api_key, provider)
-        # For Ollama, API key is optional for local instances
-        # Only validate if it looks like a remote URL
-        if @base_url && !@base_url.include?('localhost') && !@base_url.include?('127.0.0.1')
-          super
-        end
-      end
-      
-      
-      # Ollama may have different model support for structured outputs
-      def supports_structured_outputs?
-        # For now, assume all Ollama models support basic JSON mode
-        # but may not support full OpenAI structured output spec
-        true
-      end
-    end
-  end
-end

data/lib/dspy/lm/adapters/openai/schema_converter.rb

@@ -1,359 +0,0 @@
-# frozen_string_literal: true
-
-require "sorbet-runtime"
-
-module DSPy
-  class LM
-    module Adapters
-      module OpenAI
-        # Converts DSPy signatures to OpenAI structured output format
-        class SchemaConverter
-          extend T::Sig
-
-          # Models that support structured outputs as of July 2025
-          STRUCTURED_OUTPUT_MODELS = T.let([
-            "gpt-4o-mini",
-            "gpt-4o-2024-08-06",
-            "gpt-4o",
-            "gpt-4-turbo",
-            "gpt-4-turbo-2024-04-09"
-          ].freeze, T::Array[String])
-
-          sig { params(signature_class: T.class_of(DSPy::Signature), name: T.nilable(String), strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
-          def self.to_openai_format(signature_class, name: nil, strict: true)
-            # Get the output JSON schema from the signature class
-            output_schema = signature_class.output_json_schema
-            
-            # Convert oneOf to anyOf where safe, or raise error for unsupported cases
-            output_schema = convert_oneof_to_anyof_if_safe(output_schema)
-            
-            # Build the complete schema with OpenAI-specific modifications
-            dspy_schema = {
-              "$schema": "http://json-schema.org/draft-06/schema#",
-              type: "object",
-              properties: output_schema[:properties] || {},
-              required: openai_required_fields(signature_class, output_schema)
-            }
-
-            # Generate a schema name if not provided
-            schema_name = name || generate_schema_name(signature_class)
-
-            # Remove the $schema field as OpenAI doesn't use it
-            openai_schema = dspy_schema.except(:$schema)
-
-            # Add additionalProperties: false for strict mode and fix nested struct schemas
-            if strict
-              openai_schema = add_additional_properties_recursively(openai_schema)
-              openai_schema = fix_nested_struct_required_fields(openai_schema)
-            end
-
-            # Wrap in OpenAI's required format
-            {
-              type: "json_schema",
-              json_schema: {
-                name: schema_name,
-                strict: strict,
-                schema: openai_schema
-              }
-            }
-          end
-
-          # Convert oneOf to anyOf if safe (discriminated unions), otherwise raise error
-          sig { params(schema: T.untyped).returns(T.untyped) }
-          def self.convert_oneof_to_anyof_if_safe(schema)
-            return schema unless schema.is_a?(Hash)
-            
-            result = schema.dup
-            
-            # Check if this schema has oneOf that we can safely convert
-            if result[:oneOf]
-              if all_have_discriminators?(result[:oneOf])
-                # Safe to convert - discriminators ensure mutual exclusivity
-                result[:anyOf] = result.delete(:oneOf).map { |s| convert_oneof_to_anyof_if_safe(s) }
-              else
-                # Unsafe conversion - raise error
-                raise DSPy::UnsupportedSchemaError.new(
-                  "OpenAI structured outputs do not support oneOf schemas without discriminator fields. " \
-                  "The schema contains union types that cannot be safely converted to anyOf. " \
-                  "Please use enhanced_prompting strategy instead or add discriminator fields to union types."
-                )
-              end
-            end
-            
-            # Recursively process nested schemas
-            if result[:properties].is_a?(Hash)
-              result[:properties] = result[:properties].transform_values { |v| convert_oneof_to_anyof_if_safe(v) }
-            end
-            
-            if result[:items].is_a?(Hash)
-              result[:items] = convert_oneof_to_anyof_if_safe(result[:items])
-            end
-            
-            # Process arrays of schema items
-            if result[:items].is_a?(Array)
-              result[:items] = result[:items].map { |item| 
-                item.is_a?(Hash) ? convert_oneof_to_anyof_if_safe(item) : item 
-              }
-            end
-            
-            # Process anyOf arrays (in case there are nested oneOf within anyOf)
-            if result[:anyOf].is_a?(Array)
-              result[:anyOf] = result[:anyOf].map { |item| 
-                item.is_a?(Hash) ? convert_oneof_to_anyof_if_safe(item) : item 
-              }
-            end
-            
-            result
-          end
-          
-          # Check if all schemas in a oneOf array have discriminator fields (const properties)
-          sig { params(schemas: T::Array[T.untyped]).returns(T::Boolean) }
-          def self.all_have_discriminators?(schemas)
-            schemas.all? do |schema|
-              next false unless schema.is_a?(Hash)
-              next false unless schema[:properties].is_a?(Hash)
-              
-              # Check if any property has a const value (our discriminator pattern)
-              schema[:properties].any? { |_, prop| prop.is_a?(Hash) && prop[:const] }
-            end
-          end
-
-          sig { params(model: String).returns(T::Boolean) }
-          def self.supports_structured_outputs?(model)
-            # Extract base model name without provider prefix
-            base_model = model.sub(/^openai\//, "")
-            
-            # Check if it's a supported model or a newer version
-            STRUCTURED_OUTPUT_MODELS.any? { |supported| base_model.start_with?(supported) }
-          end
-
-          sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Array[String]) }
-          def self.validate_compatibility(schema)
-            issues = []
-
-            # Check for deeply nested objects (OpenAI has depth limits)
-            depth = calculate_depth(schema)
-            if depth > 5
-              issues << "Schema depth (#{depth}) exceeds recommended limit of 5 levels"
-            end
-
-            # Check for unsupported JSON Schema features
-            if contains_pattern_properties?(schema)
-              issues << "Pattern properties are not supported in OpenAI structured outputs"
-            end
-
-            if contains_conditional_schemas?(schema)
-              issues << "Conditional schemas (if/then/else) are not supported"
-            end
-
-            issues
-          end
-
-          private
-
-          # OpenAI structured outputs requires ALL properties to be in the required array
-          # For T.nilable fields without defaults, we warn the user and mark as required
-          sig { params(signature_class: T.class_of(DSPy::Signature), output_schema: T::Hash[Symbol, T.untyped]).returns(T::Array[String]) }
-          def self.openai_required_fields(signature_class, output_schema)
-            all_properties = output_schema[:properties]&.keys || []
-            original_required = output_schema[:required] || []
-            
-            # For OpenAI structured outputs, we need ALL properties to be required
-            # but warn about T.nilable fields without defaults
-            field_descriptors = signature_class.instance_variable_get(:@output_field_descriptors) || {}
-            
-            all_properties.each do |property_name|
-              descriptor = field_descriptors[property_name.to_sym]
-              
-              # If field is not originally required and doesn't have a default
-              if !original_required.include?(property_name.to_s) && descriptor && !descriptor.has_default
-                DSPy.logger.warn(
-                  "OpenAI structured outputs: T.nilable field '#{property_name}' without default will be marked as required. " \
-                  "Consider adding a default value or using a different provider for optional fields."
-                )
-              end
-            end
-            
-            # Return all properties as required (OpenAI requirement)
-            all_properties.map(&:to_s)
-          end
-
-          # Fix nested struct schemas to include all properties in required array (OpenAI requirement)
-          sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
-          def self.fix_nested_struct_required_fields(schema)
-            return schema unless schema.is_a?(Hash)
-            
-            result = schema.dup
-            
-            # If this is an object with properties, make all properties required
-            if result[:type] == "object" && result[:properties].is_a?(Hash)
-              all_property_names = result[:properties].keys.map(&:to_s)
-              result[:required] = all_property_names unless result[:required] == all_property_names
-            end
-            
-            # Process nested objects recursively
-            if result[:properties].is_a?(Hash)
-              result[:properties] = result[:properties].transform_values do |prop|
-                if prop.is_a?(Hash)
-                  processed = fix_nested_struct_required_fields(prop)
-                  # Handle arrays with object items
-                  if processed[:type] == "array" && processed[:items].is_a?(Hash)
-                    processed[:items] = fix_nested_struct_required_fields(processed[:items])
-                  end
-                  processed
-                else
-                  prop
-                end
-              end
-            end
-            
-            result
-          end
-
-          sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
-          def self.add_additional_properties_recursively(schema)
-            return schema unless schema.is_a?(Hash)
-            
-            result = schema.dup
-            
-            # Add additionalProperties: false if this is an object
-            if result[:type] == "object"
-              result[:additionalProperties] = false
-            end
-            
-            # Process properties recursively
-            if result[:properties].is_a?(Hash)
-              result[:properties] = result[:properties].transform_values do |prop|
-                if prop.is_a?(Hash)
-                  processed = add_additional_properties_recursively(prop)
-                  # Special handling for arrays - ensure their items have additionalProperties if they're objects
-                  if processed[:type] == "array" && processed[:items].is_a?(Hash)
-                    processed[:items] = add_additional_properties_recursively(processed[:items])
-                  end
-                  processed
-                else
-                  prop
-                end
-              end
-            end
-            
-            # Process array items
-            if result[:items].is_a?(Hash)
-              processed_items = add_additional_properties_recursively(result[:items])
-              # OpenAI requires additionalProperties on all objects, even in array items
-              if processed_items.is_a?(Hash) && processed_items[:type] == "object" && !processed_items.key?(:additionalProperties)
-                processed_items[:additionalProperties] = false
-              end
-              result[:items] = processed_items
-            elsif result[:items].is_a?(Array)
-              # Handle tuple validation
-              result[:items] = result[:items].map do |item|
-                processed = item.is_a?(Hash) ? add_additional_properties_recursively(item) : item
-                if processed.is_a?(Hash) && processed[:type] == "object" && !processed.key?(:additionalProperties)
-                  processed[:additionalProperties] = false
-                end
-                processed
-              end
-            end
-            
-            # Process anyOf/allOf (oneOf should be converted to anyOf by this point)
-            [:anyOf, :allOf].each do |key|
-              if result[key].is_a?(Array)
-                result[key] = result[key].map do |sub_schema|
-                  sub_schema.is_a?(Hash) ? add_additional_properties_recursively(sub_schema) : sub_schema
-                end
-              end
-            end
-            
-            result
-          end
-
-          sig { params(signature_class: T.class_of(DSPy::Signature)).returns(String) }
-          def self.generate_schema_name(signature_class)
-            # Use the signature class name
-            class_name = signature_class.name&.split("::")&.last
-            if class_name
-              class_name.gsub(/[^a-zA-Z0-9_]/, "_").downcase
-            else
-              # Fallback to a generic name
-              "dspy_output_#{Time.now.to_i}"
-            end
-          end
-
-          sig { params(schema: T::Hash[Symbol, T.untyped], current_depth: Integer).returns(Integer) }
-          def self.calculate_depth(schema, current_depth = 0)
-            return current_depth unless schema.is_a?(Hash)
-
-            max_depth = current_depth
-
-            # Check properties
-            if schema[:properties].is_a?(Hash)
-              schema[:properties].each_value do |prop|
-                if prop.is_a?(Hash)
-                  prop_depth = calculate_depth(prop, current_depth + 1)
-                  max_depth = [max_depth, prop_depth].max
-                end
-              end
-            end
-
-            # Check array items
-            if schema[:items].is_a?(Hash)
-              items_depth = calculate_depth(schema[:items], current_depth + 1)
-              max_depth = [max_depth, items_depth].max
-            end
-
-            # Check anyOf/allOf (oneOf should be converted to anyOf by this point)
-            [:anyOf, :allOf].each do |key|
-              if schema[key].is_a?(Array)
-                schema[key].each do |sub_schema|
-                  if sub_schema.is_a?(Hash)
-                    sub_depth = calculate_depth(sub_schema, current_depth + 1)
-                    max_depth = [max_depth, sub_depth].max
-                  end
-                end
-              end
-            end
-
-            max_depth
-          end
-
-          sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Boolean) }
-          def self.contains_pattern_properties?(schema)
-            return true if schema[:patternProperties]
-
-            # Recursively check nested schemas (oneOf should be converted to anyOf by this point)
-            [:properties, :items, :anyOf, :allOf].each do |key|
-              value = schema[key]
-              case value
-              when Hash
-                return true if contains_pattern_properties?(value)
-              when Array
-                return true if value.any? { |v| v.is_a?(Hash) && contains_pattern_properties?(v) }
-              end
-            end
-
-            false
-          end
-
-          sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Boolean) }
-          def self.contains_conditional_schemas?(schema)
-            return true if schema[:if] || schema[:then] || schema[:else]
-
-            # Recursively check nested schemas (oneOf should be converted to anyOf by this point) 
-            [:properties, :items, :anyOf, :allOf].each do |key|
-              value = schema[key]
-              case value
-              when Hash
-                return true if contains_conditional_schemas?(value)
-              when Array
-                return true if value.any? { |v| v.is_a?(Hash) && contains_conditional_schemas?(v) }
-              end
-            end
-
-            false
-          end
-        end
-      end
-    end
-  end
-end

data/lib/dspy/lm/adapters/openai_adapter.rb

@@ -1,188 +0,0 @@
-# frozen_string_literal: true
-
-require 'openai'
-require_relative 'openai/schema_converter'
-require_relative '../vision_models'
-
-module DSPy
-  class LM
-    class OpenAIAdapter < Adapter
-      def initialize(model:, api_key:, structured_outputs: false)
-        super(model: model, api_key: api_key)
-        validate_api_key!(api_key, 'openai')
-        @client = OpenAI::Client.new(api_key: api_key)
-        @structured_outputs_enabled = structured_outputs
-      end
-
-      def chat(messages:, signature: nil, response_format: nil, &block)
-        normalized_messages = normalize_messages(messages)
-
-        # Validate vision support if images are present
-        if contains_images?(normalized_messages)
-          VisionModels.validate_vision_support!('openai', model)
-          # Convert messages to OpenAI format with proper image handling
-          normalized_messages = format_multimodal_messages(normalized_messages)
-        end
-
-        # Handle O1 model restrictions - convert system messages to user messages
-        if o1_model?(model)
-          normalized_messages = handle_o1_messages(normalized_messages)
-        end
-
-        request_params = default_request_params.merge(
-          messages: normalized_messages
-        )
-
-        # Add temperature based on model capabilities  
-        unless o1_model?(model)
-          temperature = case model
-          when /^gpt-5/, /^gpt-4o/
-            1.0 # GPT-5 and GPT-4o models only support default temperature of 1.0
-          else
-            0.0 # Near-deterministic for other models (0.0 no longer universally supported)
-          end
-          request_params[:temperature] = temperature
-        end
-
-        # Add response format if provided by strategy
-        if response_format
-          request_params[:response_format] = response_format
-        elsif @structured_outputs_enabled && signature && supports_structured_outputs?
-          # Legacy behavior for backward compatibility
-          response_format = DSPy::LM::Adapters::OpenAI::SchemaConverter.to_openai_format(signature)
-          request_params[:response_format] = response_format
-        end
-
-        # Add streaming if block provided
-        if block_given?
-          request_params[:stream] = proc do |chunk, _bytesize|
-            block.call(chunk) if chunk.dig("choices", 0, "delta", "content")
-          end
-        end
-
-        begin
-          response = @client.chat.completions.create(**request_params)
-
-          if response.respond_to?(:error) && response.error
-            raise AdapterError, "OpenAI API error: #{response.error}"
-          end
-
-          choice = response.choices.first
-          message = choice.message
-          content = message.content
-          usage = response.usage
-
-          # Handle structured output refusals
-          if message.respond_to?(:refusal) && message.refusal
-            raise AdapterError, "OpenAI refused to generate output: #{message.refusal}"
-          end
-
-          # Convert usage data to typed struct
-          usage_struct = UsageFactory.create('openai', usage)
-
-          # Create typed metadata
-          metadata = ResponseMetadataFactory.create('openai', {
-            model: model,
-            response_id: response.id,
-            created: response.created,
-            structured_output: @structured_outputs_enabled && signature && supports_structured_outputs?,
-            system_fingerprint: response.system_fingerprint,
-            finish_reason: choice.finish_reason
-          })
-
-          Response.new(
-            content: content,
-            usage: usage_struct,
-            metadata: metadata
-          )
-        rescue => e
-          # Check for specific error types and messages
-          error_msg = e.message.to_s
-
-          # Try to parse error body if it looks like JSON
-          error_body = if error_msg.start_with?('{')
-                         JSON.parse(error_msg) rescue nil
-                       elsif e.respond_to?(:response) && e.response
-                         e.response[:body] rescue nil
-                       end
-
-          # Check for specific image-related errors
-          if error_msg.include?('image_parse_error') || error_msg.include?('unsupported image')
-            raise AdapterError, "Image processing failed: #{error_msg}. Ensure your image is a valid PNG, JPEG, GIF, or WebP format and under 5MB."
-          elsif error_msg.include?('rate') && error_msg.include?('limit')
-            raise AdapterError, "OpenAI rate limit exceeded: #{error_msg}. Please wait and try again."
-          elsif error_msg.include?('authentication') || error_msg.include?('API key') || error_msg.include?('Unauthorized')
-            raise AdapterError, "OpenAI authentication failed: #{error_msg}. Check your API key."
-          elsif error_body && error_body.dig('error', 'message')
-            raise AdapterError, "OpenAI API error: #{error_body.dig('error', 'message')}"
-          else
-            # Generic error handling
-            raise AdapterError, "OpenAI adapter error: #{e.message}"
-          end
-        end
-      end
-
-      protected
-
-      # Allow subclasses to override request params (add headers, etc)
-      def default_request_params
-        {
-          model: model
-        }
-      end
-
-      private
-
-      def supports_structured_outputs?
-        DSPy::LM::Adapters::OpenAI::SchemaConverter.supports_structured_outputs?(model)
-      end
-
-      def format_multimodal_messages(messages)
-        messages.map do |msg|
-          if msg[:content].is_a?(Array)
-            # Convert multimodal content to OpenAI format
-            formatted_content = msg[:content].map do |item|
-              case item[:type]
-              when 'text'
-                { type: 'text', text: item[:text] }
-              when 'image'
-                # Validate image compatibility before formatting
-                item[:image].validate_for_provider!('openai')
-                item[:image].to_openai_format
-              else
-                item
-              end
-            end
-
-            {
-              role: msg[:role],
-              content: formatted_content
-            }
-          else
-            msg
-          end
-        end
-      end
-
-      # Check if model is an O1 reasoning model (includes O1, O3, O4 series)
-      def o1_model?(model_name)
-        model_name.match?(/^o[134](-.*)?$/)
-      end
-
-      # Handle O1 model message restrictions
-      def handle_o1_messages(messages)
-        messages.map do |msg|
-          # Convert system messages to user messages for O1 models
-          if msg[:role] == 'system'
-            {
-              role: 'user',
-              content: "Instructions: #{msg[:content]}"
-            }
-          else
-            msg
-          end
-        end
-      end
-    end
-  end
-end

data/lib/dspy/lm/adapters/openrouter_adapter.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-require 'openai'
-
-module DSPy
-  class LM
-    class OpenrouterAdapter < OpenAIAdapter
-      BASE_URL = 'https://openrouter.ai/api/v1'
-
-      def initialize(model:, api_key: nil, structured_outputs: true, http_referrer: nil, x_title: nil)
-        # Don't call parent's initialize, do it manually to control client creation
-        @model = model
-        @api_key = api_key
-        @structured_outputs_enabled = structured_outputs
-
-        @http_referrer = http_referrer
-        @x_title = x_title
-
-        validate_configuration!
-
-        # Create client with custom base URL
-        @client = OpenAI::Client.new(
-          api_key: @api_key,
-          base_url: BASE_URL
-        )
-      end
-
-      def chat(messages:, signature: nil, response_format: nil, &block)
-        # For OpenRouter, we need to be more lenient with structured outputs
-        # as the model behind it may not fully support OpenAI's response_format spec
-        begin
-          super
-        rescue => e
-          # If structured output fails, retry with enhanced prompting
-          if @structured_outputs_enabled && signature && e.message.include?('response_format')
-            DSPy.logger.debug("OpenRouter structured output failed, falling back to enhanced prompting")
-            @structured_outputs_enabled = false
-            retry
-          else
-            raise
-          end
-        end
-      end
-
-      protected
-
-      # Add any OpenRouter-specific headers to all requests
-      def default_request_params
-        headers = {
-          'X-Title' => @x_title,
-          'HTTP-Referer' => @http_referrer
-        }.compact
-
-        upstream_params = super
-        upstream_params.merge!(request_options: { extra_headers: headers }) if headers.any?
-        upstream_params
-      end
-
-      private
-
-      def supports_structured_outputs?
-        # Different models behind OpenRouter may have different capabilities
-        # For now, we rely on whatever was passed to the constructor
-        @structured_outputs_enabled
-      end
-    end
-  end
-end