dspy 0.28.0 → 0.28.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df0e7cf901df85567e1553a3d7df8659a71f254fa5671803ea98f0573de0c39a
-  data.tar.gz: b2d5d37cb05678f97143a1463410d92848ba10178bd50d60ee384827e9efe9b1
+  metadata.gz: f1cc0ac1e2e1dc27f6255b11ca70ff0ad0eb37b5ae50ff38b97ae7d35b7b69b8
+  data.tar.gz: 2399987757b4f037080632e646714e785328fbe3c1fd39138fe750336cdd7710
 SHA512:
-  metadata.gz: 0d870f2d338fcdce0540143decd3674e94a9c24e5fad796536772e6c8064af75dcafc36533bf39a0a1eeefac30777de1d6541a3ab57eb2568a007260d7a5d7a3
-  data.tar.gz: 13f92278a81ca870f90b662fa40972e41aa6203d27a8792d3d03c13b97d971d7684a0f661dfb86bf03ef5c58e4a8f2f57c2ac48414ed9b8f8e5f0bce7628f231
+  metadata.gz: ea48762186d3de89a005e8eac27f57ca90b294c4ab096ec1c7985d06396216d719ca3a2144406d1f43af472a560670e502329a785d33b8923b5c9c4c0f83dfd1
+  data.tar.gz: 98fee1468f2692a0f7cc87622722f945dbc344fb299e71935ef592bc1d59e68e48e1390208981b6263998627dacb38dc325727cc191f81e1db79fff57c1537a4

data/lib/dspy/callbacks.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module DSPy
+  # Provides Rails-style callback hooks for DSPy modules
+  #
+  # @example Define callbacks in base class
+  #   class DSPy::Module
+  #     include DSPy::Callbacks
+  #
+  #     create_before_callback :forward
+  #     create_after_callback :forward
+  #     create_around_callback :forward
+  #   end
+  #
+  # @example Use callbacks in subclasses
+  #   class MyAgent < DSPy::Module
+  #     before :setup_context
+  #     after :log_metrics
+  #     around :manage_memory
+  #
+  #     private
+  #
+  #     def setup_context
+  #       @start_time = Time.now
+  #     end
+  #
+  #     def log_metrics
+  #       puts "Duration: #{Time.now - @start_time}"
+  #     end
+  #
+  #     def manage_memory
+  #       load_context
+  #       yield
+  #       save_context
+  #     end
+  #   end
+  module Callbacks
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Creates a before callback hook for the specified method
+      #
+      # @param method_name [Symbol] the method to add callback support to
+      def create_before_callback(method_name)
+        mark_method_has_callbacks(method_name)
+        ensure_callback_method_defined(:before, method_name)
+        wrap_method_with_callbacks(method_name)
+      end
+
+      # Creates an after callback hook for the specified method
+      #
+      # @param method_name [Symbol] the method to add callback support to
+      def create_after_callback(method_name)
+        mark_method_has_callbacks(method_name)
+        ensure_callback_method_defined(:after, method_name)
+        wrap_method_with_callbacks(method_name)
+      end
+
+      # Creates an around callback hook for the specified method
+      #
+      # @param method_name [Symbol] the method to add callback support to
+      def create_around_callback(method_name)
+        mark_method_has_callbacks(method_name)
+        ensure_callback_method_defined(:around, method_name)
+        wrap_method_with_callbacks(method_name)
+      end
+
+      private
+
+      # Ensures the callback registration method exists
+      def ensure_callback_method_defined(type, target_method_name)
+        return if singleton_class.method_defined?(type)
+
+        define_singleton_method(type) do |callback_method|
+          register_callback(type, target_method_name, callback_method)
+        end
+      end
+
+      # Registers a callback for execution
+      def register_callback(type, method_name, callback_method)
+        own_callbacks_for(method_name)[type] ||= []
+        own_callbacks_for(method_name)[type] << callback_method
+      end
+
+      # Returns own callbacks (not including parent)
+      def own_callbacks_for(method_name)
+        @callbacks ||= {}
+        @callbacks[method_name] ||= {}
+      end
+
+      # Marks that a method has callback support (even if no callbacks registered yet)
+      def mark_method_has_callbacks(method_name)
+        own_callbacks_for(method_name)
+      end
+
+      # Returns the callback registry for a method
+      # Includes callbacks from parent classes
+      def callbacks_for(method_name)
+        own_callbacks = own_callbacks_for(method_name)
+
+        # Merge parent callbacks if this is a subclass
+        if superclass.respond_to?(:callbacks_for, true)
+          parent_callbacks = superclass.send(:callbacks_for, method_name)
+
+          # Merge each callback type, with own callbacks coming after parent callbacks
+          merged_callbacks = {}
+          [:before, :after, :around].each do |type|
+            parent_list = parent_callbacks[type] || []
+            own_list = own_callbacks[type] || []
+            merged_callbacks[type] = parent_list + own_list if parent_list.any? || own_list.any?
+          end
+
+          merged_callbacks
+        else
+          own_callbacks
+        end
+      end
+
+      # Wraps a method with callback execution logic
+      def wrap_method_with_callbacks(method_name)
+        return if method_wrapped?(method_name)
+
+        # Defer wrapping if method doesn't exist yet
+        return unless method_defined?(method_name)
+
+        # Mark as wrapped BEFORE define_method to prevent infinite recursion
+        mark_method_wrapped(method_name)
+
+        original_method = instance_method(method_name)
+
+        define_method(method_name) do |*args, **kwargs, &block|
+          # Execute before callbacks
+          run_callbacks(:before, method_name)
+
+          # Execute around callbacks or original method
+          result = if self.class.send(:has_around_callbacks?, method_name)
+            execute_with_around_callbacks(method_name, original_method, *args, **kwargs, &block)
+          else
+            original_method.bind(self).call(*args, **kwargs, &block)
+          end
+
+          # Execute after callbacks
+          run_callbacks(:after, method_name)
+
+          result
+        end
+      end
+
+      # Checks if method has around callbacks
+      def has_around_callbacks?(method_name)
+        callbacks_for(method_name)[:around]&.any?
+      end
+
+      # Hook into method_added to wrap methods when they're defined
+      def method_added(method_name)
+        super
+
+        # Check if this method or any parent has callback support (even if no callbacks registered yet)
+        has_callback_support = method_has_callback_support?(method_name)
+
+        return unless has_callback_support
+        return if method_wrapped?(method_name)
+
+        wrap_method_with_callbacks(method_name)
+      end
+
+      # Checks if a method has callback support in this class or parents
+      def method_has_callback_support?(method_name)
+        # Check own callbacks registry
+        return true if @callbacks&.key?(method_name)
+
+        # Check parent class
+        if superclass.respond_to?(:method_has_callback_support?, true)
+          superclass.send(:method_has_callback_support?, method_name)
+        else
+          false
+        end
+      end
+
+      # Marks a method as wrapped
+      def mark_method_wrapped(method_name)
+        @wrapped_methods ||= []
+        @wrapped_methods << method_name
+      end
+
+      # Checks if method is already wrapped
+      def method_wrapped?(method_name)
+        @wrapped_methods&.include?(method_name)
+      end
+    end
+
+    private
+
+    # Executes callbacks of a specific type
+    def run_callbacks(type, method_name)
+      callbacks = self.class.send(:callbacks_for, method_name)[type]
+      return unless callbacks
+
+      callbacks.each do |callback_method|
+        send(callback_method)
+      end
+    end
+
+    # Executes method with around callbacks
+    def execute_with_around_callbacks(method_name, original_method, *args, **kwargs, &block)
+      callbacks = self.class.send(:callbacks_for, method_name)[:around]
+
+      # Build callback chain from innermost (original method) to outermost
+      chain = callbacks.reverse.inject(
+        -> { original_method.bind(self).call(*args, **kwargs, &block) }
+      ) do |inner, callback_method|
+        -> { send(callback_method) { inner.call } }
+      end
+
+      chain.call
+    end
+  end
+end

data/lib/dspy/chain_of_thought.rb

@@ -46,7 +46,8 @@ module DSPy
         input_schema: @signature_class.input_json_schema,
         output_schema: @signature_class.output_json_schema,
         few_shot_examples: new_prompt.few_shot_examples,
-        signature_class_name: @signature_class.name
+        signature_class_name: @signature_class.name,
+        schema_format: new_prompt.schema_format
       )
       
       instance.instance_variable_set(:@prompt, enhanced_prompt)

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/json_strategy.rb

@@ -102,11 +102,6 @@ module DSPy
           type: "tool",
           name: "json_output"
         }
-
-        # Update last user message
-        if messages.any? && messages.last[:role] == "user"
-          messages.last[:content] += "\n\nPlease use the json_output tool to provide your response."
-        end
       end
 
       # Gemini preparation

data/lib/dspy/lm.rb

@@ -26,19 +26,21 @@ 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
     extend T::Sig
-    attr_reader :model_id, :api_key, :model, :provider, :adapter
+    attr_reader :model_id, :api_key, :model, :provider, :adapter, :schema_format
 
-    def initialize(model_id, api_key: nil, **options)
+    def initialize(model_id, api_key: nil, schema_format: :json, **options)
       @model_id = model_id
       @api_key = api_key
-      
+      @schema_format = schema_format
+
       # Parse provider and model from model_id
       @provider, @model = parse_model_id(model_id)
-      
+
       # Create appropriate adapter with options
       @adapter = AdapterFactory.create(model_id, api_key: api_key, **options)
     end
@@ -176,26 +178,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

data/lib/dspy/module.rb

@@ -3,16 +3,23 @@
 require 'sorbet-runtime'
 require 'dry-configurable'
 require_relative 'context'
+require_relative 'callbacks'
 
 module DSPy
   class Module
     extend T::Sig
     extend T::Generic
     include Dry::Configurable
+    include DSPy::Callbacks
 
     # Per-instance LM configuration
     setting :lm, default: nil
 
+    # Define callback hooks for forward method
+    create_before_callback :forward
+    create_after_callback :forward
+    create_around_callback :forward
+
     # The main forward method that users will call is generic and type parameterized
     sig do
       type_parameters(:I, :O)
@@ -72,5 +79,31 @@ module DSPy
     def lm
       config.lm || DSPy.current_lm
     end
+
+    # Save the module state to a JSON file
+    # Lightweight serialization for intermediate optimization trials
+    #
+    # @param path [String] Path to save the module state (JSON format)
+    sig { params(path: String).void }
+    def save(path)
+      require 'json'
+      require 'fileutils'
+
+      # Ensure parent directory exists
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+
+      # Serialize module to JSON
+      File.write(path, JSON.pretty_generate(to_h))
+    end
+
+    # Default serialization method - subclasses can override
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      {
+        class_name: self.class.name,
+        state: {}
+      }
+    end
   end
 end

data/lib/dspy/predict.rb

@@ -53,11 +53,18 @@ module DSPy
     sig { returns(Prompt) }
     attr_reader :prompt
 
+    # Mutable demos attribute for MIPROv2 compatibility
+    sig { returns(T.nilable(T::Array[FewShotExample])) }
+    attr_accessor :demos
+
     sig { params(signature_class: T.class_of(Signature)).void }
     def initialize(signature_class)
       super()
       @signature_class = signature_class
+
+      # Prompt will read schema_format from config automatically
       @prompt = Prompt.from_signature(signature_class)
+      @demos = nil
     end
 
     # Reconstruct program from serialized hash