dspy 0.27.6 → 0.28.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ccadc1d2803420cbc9389d9f4312b6b6e616e133d4e35f36454135292fd8e837
-  data.tar.gz: e174d2cd9418a0294890e1ca6d3599681ba26c2a09c081f3b2b6652e6ce8c88d
+  metadata.gz: 8b377060443eeb9c3c5d975e76750d6c519d1b93cf6f20dc6ad20bcda08d1ca4
+  data.tar.gz: 4580845b3fd9991b531c8c2bd809595cbd3328da57a23e58307cdbe52e3822bc
 SHA512:
-  metadata.gz: fa7eefd5f7d5555ce057f0e204b6aa5bac1188e2633c202abdf9decc75eee75ae5a232550c368dcba081fe32cc54e0d9aa8db6d565b280c260bd0b8beacff4d9
-  data.tar.gz: 5b16c7fe7ebbe678e16235e0b0b857d3b017deb7a7eea1e6e032b4b839fbde33b4bae86fd3e50d2b6f49c114303231f60441d43d931c8f0cda3c9f5e72d786ab
+  metadata.gz: 444a5e08364b2e996bf49d230cb9a94a1930e26d2ea796cd0104ea4888b45ade4099cec502b92c08752631adff47b1d9d1897da9209e9faabbb28fb6761935b0
+  data.tar.gz: c1b3a83482c861923304c463d6f0b1c9042fbc31da920526ec18ed0f5148b4408a9023d312eded9263ca2d706e4779b78526e28dc50a17458cbbac9afa56b024

data/README.md

@@ -59,22 +59,41 @@ puts result.sentiment    # => #<Sentiment::Positive>
 puts result.confidence   # => 0.85
 ```
 
-### Alternative Providers
+### Access to 200+ Models Across 5 Providers
 
-DSPy.rb supports multiple providers with native structured outputs:
+DSPy.rb provides unified access to major LLM providers with provider-specific optimizations:
 
 ```ruby
-# Google Gemini with native structured outputs
+# OpenAI (GPT-4, GPT-4o, GPT-4o-mini, GPT-5, etc.)
 DSPy.configure do |c|
-  c.lm = DSPy::LM.new('gemini/gemini-1.5-flash',
-                      api_key: ENV['GEMINI_API_KEY'], 
-                      structured_outputs: true)  # Supports gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash-exp
+  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
+                      api_key: ENV['OPENAI_API_KEY'],
+                      structured_outputs: true)  # Native JSON mode
+end
+
+# Google Gemini (Gemini 1.5 Pro, Flash, Gemini 2.0, etc.)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('gemini/gemini-2.5-flash',
+                      api_key: ENV['GEMINI_API_KEY'],
+                      structured_outputs: true)  # Native structured outputs
+end
+
+# Anthropic Claude (Claude 3.5, Claude 4, etc.)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-5-20250929',
+                      api_key: ENV['ANTHROPIC_API_KEY'],
+                      structured_outputs: true)  # Tool-based extraction (default)
+end
+
+# Ollama - Run any local model (Llama, Mistral, Gemma, etc.)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('ollama/llama3.2')  # Free, runs locally, no API key needed
 end
 
-# Anthropic Claude with tool-based extraction
+# OpenRouter - Access to 200+ models from multiple providers
 DSPy.configure do |c|
-  c.lm = DSPy::LM.new('anthropic/claude-3-sonnet-20241022',
-                      api_key: ENV['ANTHROPIC_API_KEY'])  # Automatic strategy selection
+  c.lm = DSPy::LM.new('openrouter/deepseek/deepseek-chat-v3.1:free',
+                      api_key: ENV['OPENROUTER_API_KEY'])
 end
 ```
 

data/lib/dspy/lm/adapter_factory.rb

@@ -13,7 +13,7 @@ module DSPy
         'openrouter' => 'OpenrouterAdapter'
       }.freeze
 
-      PROVIDERS_WITH_EXTRA_OPTIONS = %w[openai ollama gemini openrouter].freeze
+      PROVIDERS_WITH_EXTRA_OPTIONS = %w[openai anthropic ollama gemini openrouter].freeze
 
       class << self
         # Creates an adapter instance based on model_id

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

@@ -6,10 +6,11 @@ require_relative '../vision_models'
 module DSPy
   class LM
     class AnthropicAdapter < Adapter
-      def initialize(model:, api_key:)
-        super
+      def initialize(model:, api_key:, structured_outputs: true)
+        super(model: model, api_key: api_key)
         validate_api_key!(api_key, 'anthropic')
         @client = Anthropic::Client.new(api_key: api_key)
+        @structured_outputs_enabled = structured_outputs
       end
 
       def chat(messages:, signature: nil, **extra_params, &block)

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

@@ -11,29 +11,32 @@ module DSPy
           extend T::Sig
 
           # Models that support structured outputs (JSON + Schema)
-          # Based on official Google documentation (Sept 2025)
+          # Based on official Google documentation: https://ai.google.dev/gemini-api/docs/models/gemini
+          # Last updated: Oct 2025
+          # Note: Gemini 1.5 series deprecated Oct 2025
           STRUCTURED_OUTPUT_MODELS = T.let([
-            # Gemini 1.5 series
-            "gemini-1.5-pro",
-            "gemini-1.5-pro-preview-0514",
-            "gemini-1.5-pro-preview-0409", 
-            "gemini-1.5-flash",             # ✅ Now supports structured outputs
-            "gemini-1.5-flash-8b",
             # Gemini 2.0 series
             "gemini-2.0-flash",
-            "gemini-2.0-flash-001",
-            # Gemini 2.5 series
+            "gemini-2.0-flash-lite",
+            # Gemini 2.5 series (current)
             "gemini-2.5-pro",
-            "gemini-2.5-flash", 
-            "gemini-2.5-flash-lite"
+            "gemini-2.5-flash",
+            "gemini-2.5-flash-lite",
+            "gemini-2.5-flash-image"
           ].freeze, T::Array[String])
 
-          # Models that do not support structured outputs (legacy only)
+          # Models that do not support structured outputs or are deprecated
           UNSUPPORTED_MODELS = T.let([
-            # Legacy Gemini 1.0 series only
-            "gemini-pro",                   
+            # Legacy Gemini 1.0 series
+            "gemini-pro",
             "gemini-1.0-pro-002",
-            "gemini-1.0-pro"
+            "gemini-1.0-pro",
+            # Deprecated Gemini 1.5 series (removed Oct 2025)
+            "gemini-1.5-pro",
+            "gemini-1.5-pro-preview-0514",
+            "gemini-1.5-pro-preview-0409",
+            "gemini-1.5-flash",
+            "gemini-1.5-flash-8b"
           ].freeze, T::Array[String])
 
           sig { params(signature_class: T.class_of(DSPy::Signature)).returns(T::Hash[Symbol, T.untyped]) }
@@ -111,7 +114,13 @@ module DSPy
             case property_schema[:type]
             when "string"
               result = { type: "string" }
-              result[:enum] = property_schema[:enum] if property_schema[:enum]
+              # Gemini responseJsonSchema doesn't support const, so convert to single-value enum
+              # See: https://ai.google.dev/api/generate-content#FIELDS.response_json_schema
+              if property_schema[:const]
+                result[:enum] = [property_schema[:const]]
+              elsif property_schema[:enum]
+                result[:enum] = property_schema[:enum]
+              end
               result
             when "integer"
               { type: "integer" }

data/lib/dspy/lm/chat_strategy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module DSPy
+  class LM
+    # Simple chat strategy that passes messages through without JSON extraction
+    class ChatStrategy
+      extend T::Sig
+
+      sig { params(adapter: T.untyped).void }
+      def initialize(adapter)
+        @adapter = adapter
+      end
+
+      # No modifications to messages for simple chat
+      sig { params(messages: T::Array[T::Hash[Symbol, T.untyped]], request_params: T::Hash[Symbol, T.untyped]).void }
+      def prepare_request(messages, request_params)
+        # Pass through unchanged
+      end
+
+      # No JSON extraction for chat
+      sig { params(response: DSPy::LM::Response).returns(NilClass) }
+      def extract_json(response)
+        nil
+      end
+
+      sig { returns(String) }
+      def name
+        'chat'
+      end
+
+      private
+
+      attr_reader :adapter
+    end
+  end
+end

data/lib/dspy/lm/json_strategy.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require_relative "adapters/openai/schema_converter"
+require_relative "adapters/gemini/schema_converter"
+
+module DSPy
+  class LM
+    # JSON extraction strategy with provider-specific handling
+    class JSONStrategy
+      extend T::Sig
+
+      sig { params(adapter: T.untyped, signature_class: T.class_of(DSPy::Signature)).void }
+      def initialize(adapter, signature_class)
+        @adapter = adapter
+        @signature_class = signature_class
+      end
+
+      # Prepare request with provider-specific JSON extraction parameters
+      sig { params(messages: T::Array[T::Hash[Symbol, T.untyped]], request_params: T::Hash[Symbol, T.untyped]).void }
+      def prepare_request(messages, request_params)
+        adapter_class_name = adapter.class.name
+
+        if adapter_class_name.include?('OpenAIAdapter') || adapter_class_name.include?('OllamaAdapter')
+          prepare_openai_request(request_params)
+        elsif adapter_class_name.include?('AnthropicAdapter')
+          prepare_anthropic_request(messages, request_params)
+        elsif adapter_class_name.include?('GeminiAdapter')
+          prepare_gemini_request(request_params)
+        end
+        # Unknown provider - no special handling
+      end
+
+      # Extract JSON from response based on provider
+      sig { params(response: DSPy::LM::Response).returns(T.nilable(String)) }
+      def extract_json(response)
+        adapter_class_name = adapter.class.name
+
+        if adapter_class_name.include?('OpenAIAdapter') || adapter_class_name.include?('OllamaAdapter')
+          # OpenAI/Ollama: try to extract JSON from various formats
+          extract_json_from_content(response.content)
+        elsif adapter_class_name.include?('AnthropicAdapter')
+          # Anthropic: try tool use first if structured_outputs enabled, else use content extraction
+          structured_outputs_enabled = adapter.instance_variable_get(:@structured_outputs_enabled)
+          structured_outputs_enabled = true if structured_outputs_enabled.nil?  # Default to true
+
+          if structured_outputs_enabled
+            extracted = extract_anthropic_tool_json(response)
+            extracted || extract_json_from_content(response.content)
+          else
+            # Skip tool extraction, use enhanced prompting extraction
+            extract_json_from_content(response.content)
+          end
+        elsif adapter_class_name.include?('GeminiAdapter')
+          # Gemini: try to extract JSON from various formats
+          extract_json_from_content(response.content)
+        else
+          # Unknown provider: try to extract JSON
+          extract_json_from_content(response.content)
+        end
+      end
+
+      sig { returns(String) }
+      def name
+        'json'
+      end
+
+      private
+
+      attr_reader :adapter, :signature_class
+
+      # OpenAI/Ollama preparation
+      sig { params(request_params: T::Hash[Symbol, T.untyped]).void }
+      def prepare_openai_request(request_params)
+        # Check if structured outputs are supported
+        if adapter.instance_variable_get(:@structured_outputs_enabled) &&
+           DSPy::LM::Adapters::OpenAI::SchemaConverter.supports_structured_outputs?(adapter.model)
+          response_format = DSPy::LM::Adapters::OpenAI::SchemaConverter.to_openai_format(signature_class)
+          request_params[:response_format] = response_format
+        end
+      end
+
+      # Anthropic preparation
+      sig { params(messages: T::Array[T::Hash[Symbol, T.untyped]], request_params: T::Hash[Symbol, T.untyped]).void }
+      def prepare_anthropic_request(messages, request_params)
+        # Only use tool-based extraction if structured_outputs is enabled (default: true)
+        structured_outputs_enabled = adapter.instance_variable_get(:@structured_outputs_enabled)
+
+        # Default to true if not set (backward compatibility)
+        structured_outputs_enabled = true if structured_outputs_enabled.nil?
+
+        return unless structured_outputs_enabled
+
+        # Convert signature to tool schema
+        tool_schema = convert_to_anthropic_tool_schema
+
+        # Add tool definition
+        request_params[:tools] = [tool_schema]
+
+        # Force tool use
+        request_params[:tool_choice] = {
+          type: "tool",
+          name: "json_output"
+        }
+      end
+
+      # Gemini preparation
+      sig { params(request_params: T::Hash[Symbol, T.untyped]).void }
+      def prepare_gemini_request(request_params)
+        # Check if structured outputs are supported
+        if adapter.instance_variable_get(:@structured_outputs_enabled) &&
+           DSPy::LM::Adapters::Gemini::SchemaConverter.supports_structured_outputs?(adapter.model)
+          schema = DSPy::LM::Adapters::Gemini::SchemaConverter.to_gemini_format(signature_class)
+
+          request_params[:generation_config] = {
+            response_mime_type: "application/json",
+            response_json_schema: schema
+          }
+        end
+      end
+
+      # Convert signature to Anthropic tool schema
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def convert_to_anthropic_tool_schema
+        output_fields = signature_class.output_field_descriptors
+
+        {
+          name: "json_output",
+          description: "Output the result in the required JSON format",
+          input_schema: {
+            type: "object",
+            properties: build_properties_from_fields(output_fields),
+            required: output_fields.keys.map(&:to_s)
+          }
+        }
+      end
+
+      # Build JSON schema properties from output fields
+      sig { params(fields: T::Hash[Symbol, T.untyped]).returns(T::Hash[String, T.untyped]) }
+      def build_properties_from_fields(fields)
+        properties = {}
+        fields.each do |field_name, descriptor|
+          properties[field_name.to_s] = DSPy::TypeSystem::SorbetJsonSchema.type_to_json_schema(descriptor.type)
+        end
+        properties
+      end
+
+      # Extract JSON from Anthropic tool use response
+      sig { params(response: DSPy::LM::Response).returns(T.nilable(String)) }
+      def extract_anthropic_tool_json(response)
+        # Check for tool calls in metadata
+        if response.metadata.respond_to?(:tool_calls) && response.metadata.tool_calls
+          tool_calls = response.metadata.tool_calls
+          if tool_calls.is_a?(Array) && !tool_calls.empty?
+            first_call = tool_calls.first
+            if first_call[:name] == "json_output" && first_call[:input]
+              return JSON.generate(first_call[:input])
+            end
+          end
+        end
+
+        nil
+      end
+
+      # Extract JSON from content that may contain markdown or plain JSON
+      sig { params(content: String).returns(String) }
+      def extract_json_from_content(content)
+        return content if content.nil? || content.empty?
+
+        # Try 1: Check for ```json code block (with or without preceding text)
+        if content.include?('```json')
+          json_match = content.match(/```json\s*\n(.*?)\n```/m)
+          return json_match[1].strip if json_match
+        end
+
+        # Try 2: Check for generic ``` code block
+        if content.include?('```')
+          code_match = content.match(/```\s*\n(.*?)\n```/m)
+          if code_match
+            potential_json = code_match[1].strip
+            # Verify it's JSON
+            begin
+              JSON.parse(potential_json)
+              return potential_json
+            rescue JSON::ParserError
+              # Not valid JSON, continue
+            end
+          end
+        end
+
+        # Try 3: Try parsing entire content as JSON
+        begin
+          JSON.parse(content)
+          return content
+        rescue JSON::ParserError
+          # Not pure JSON, try extracting
+        end
+
+        # Try 4: Look for JSON object pattern in text (greedy match for nested objects)
+        json_pattern = /\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\}/m
+        json_match = content.match(json_pattern)
+        if json_match
+          potential_json = json_match[0]
+          begin
+            JSON.parse(potential_json)
+            return potential_json
+          rescue JSON::ParserError
+            # Not valid JSON
+          end
+        end
+
+        # Return content as-is if no JSON found
+        content
+      end
+    end
+  end
+end

data/lib/dspy/lm.rb

@@ -20,12 +20,13 @@ require_relative 'lm/adapters/gemini_adapter'
 require_relative 'lm/adapters/openrouter_adapter'
 
 # Load strategy system
-require_relative 'lm/strategy_selector'
-require_relative 'lm/retry_handler'
+require_relative 'lm/chat_strategy'
+require_relative 'lm/json_strategy'
 
 # Load message builder and message types
 require_relative 'lm/message'
 require_relative 'lm/message_builder'
+require_relative 'structured_outputs_prompt'
 
 module DSPy
   class LM
@@ -64,7 +65,10 @@ module DSPy
         response = instrument_lm_request(messages, signature_class.name) do
           chat_with_strategy(messages, signature_class, &block)
         end
-        
+
+        # Emit the standard lm.tokens event (consistent with raw_chat)
+        emit_token_usage(response, signature_class.name)
+
         # Parse response (no longer needs separate instrumentation)
         parsed_result = parse_response(response, input_values, signature_class)
         
@@ -96,21 +100,15 @@ module DSPy
     private
 
     def chat_with_strategy(messages, signature_class, &block)
-      # Select the best strategy for JSON extraction
-      strategy_selector = StrategySelector.new(adapter, signature_class)
-      initial_strategy = strategy_selector.select
-      
-      if DSPy.config.structured_outputs.retry_enabled && signature_class
-        # Use retry handler for JSON responses
-        retry_handler = RetryHandler.new(adapter, signature_class)
-        
-        retry_handler.with_retry(initial_strategy) do |strategy|
-          execute_chat_with_strategy(messages, signature_class, strategy, &block)
-        end
+      # Choose strategy based on whether we need JSON extraction
+      strategy = if signature_class
+        JSONStrategy.new(adapter, signature_class)
       else
-        # No retry logic, just execute once
-        execute_chat_with_strategy(messages, signature_class, initial_strategy, &block)
+        ChatStrategy.new(adapter)
       end
+
+      # Execute with the selected strategy (no retry, no fallback)
+      execute_chat_with_strategy(messages, signature_class, strategy, &block)
     end
 
     def execute_chat_with_strategy(messages, signature_class, strategy, &block)
@@ -179,26 +177,53 @@ module DSPy
 
     def build_messages(inference_module, input_values)
       messages = []
-      
+
+      # Determine if structured outputs will be used and wrap prompt if so
+      base_prompt = inference_module.prompt
+      prompt = if will_use_structured_outputs?(inference_module.signature_class)
+        StructuredOutputsPrompt.new(**base_prompt.to_h)
+      else
+        base_prompt
+      end
+
       # Add system message
-      system_prompt = inference_module.system_signature
+      system_prompt = prompt.render_system_prompt
       if system_prompt
         messages << Message.new(
           role: Message::Role::System,
           content: system_prompt
         )
       end
-      
+
       # Add user message
-      user_prompt = inference_module.user_signature(input_values)
+      user_prompt = prompt.render_user_prompt(input_values)
       messages << Message.new(
         role: Message::Role::User,
         content: user_prompt
       )
-      
+
       messages
     end
 
+    def will_use_structured_outputs?(signature_class)
+      return false unless signature_class
+
+      adapter_class_name = adapter.class.name
+
+      if adapter_class_name.include?('OpenAIAdapter') || adapter_class_name.include?('OllamaAdapter')
+        adapter.instance_variable_get(:@structured_outputs_enabled) &&
+          DSPy::LM::Adapters::OpenAI::SchemaConverter.supports_structured_outputs?(adapter.model)
+      elsif adapter_class_name.include?('GeminiAdapter')
+        adapter.instance_variable_get(:@structured_outputs_enabled) &&
+          DSPy::LM::Adapters::Gemini::SchemaConverter.supports_structured_outputs?(adapter.model)
+      elsif adapter_class_name.include?('AnthropicAdapter')
+        structured_outputs_enabled = adapter.instance_variable_get(:@structured_outputs_enabled)
+        structured_outputs_enabled.nil? ? true : structured_outputs_enabled
+      else
+        false
+      end
+    end
+
     def parse_response(response, input_values, signature_class)
       # Try to parse the response as JSON
       content = response.content

data/lib/dspy/mixins/type_coercion.rb

@@ -208,26 +208,26 @@ module DSPy
       sig { params(value: T.untyped, union_type: T.untyped).returns(T.untyped) }
       def coerce_union_value(value, union_type)
         return value unless value.is_a?(Hash)
-        
+
         # Check for _type discriminator field
         type_name = value[:_type] || value["_type"]
         return value unless type_name
-        
+
         # Find matching struct type in the union
         union_type.types.each do |type|
           next if type == T::Utils.coerce(NilClass)
-          
+
           if type.is_a?(T::Types::Simple) && type.raw_type < T::Struct
             struct_name = type.raw_type.name.split('::').last
             if struct_name == type_name
               # Convert string keys to symbols and remove _type
               symbolized_hash = value.transform_keys(&:to_sym)
               symbolized_hash.delete(:_type)
-              
+
               # Coerce struct field values based on their types
               struct_class = type.raw_type
               struct_props = struct_class.props
-              
+
               # ONLY include fields that exist in the struct
               coerced_hash = {}
               struct_props.each_key do |key|
@@ -236,13 +236,13 @@ module DSPy
                   coerced_hash[key] = coerce_value_to_type(symbolized_hash[key], prop_type)
                 end
               end
-              
+
               # Create the struct instance with coerced values
               return struct_class.new(**coerced_hash)
             end
           end
         end
-        
+
         # If no matching type found, return original value
         value
       rescue ArgumentError => e