dspy 0.19.1 → 0.20.1

data/lib/dspy/lm/vision_models.rb

@@ -26,12 +26,30 @@ module DSPy
         'claude-3-5-haiku-20241022'
       ].freeze
       
+      # Gemini vision-capable models (all Gemini models support vision)
+      # Based on official Google AI API documentation (March 2025)
+      GEMINI_VISION_MODELS = [
+        # Gemini 2.5 series (2025)
+        'gemini-2.5-pro',
+        'gemini-2.5-flash',
+        'gemini-2.5-flash-lite',
+        # Gemini 2.0 series (2024-2025)
+        'gemini-2.0-flash',
+        'gemini-2.0-flash-lite',
+        # Gemini 1.5 series
+        'gemini-1.5-pro',
+        'gemini-1.5-flash',
+        'gemini-1.5-flash-8b'
+      ].freeze
+      
       def self.supports_vision?(provider, model)
         case provider.to_s.downcase
         when 'openai'
           OPENAI_VISION_MODELS.any? { |m| model.include?(m) }
         when 'anthropic'
           ANTHROPIC_VISION_MODELS.any? { |m| model.include?(m) }
+        when 'gemini'
+          GEMINI_VISION_MODELS.any? { |m| model.include?(m) }
         else
           false
         end
@@ -49,6 +67,8 @@ module DSPy
           OPENAI_VISION_MODELS
         when 'anthropic'
           ANTHROPIC_VISION_MODELS
+        when 'gemini'
+          GEMINI_VISION_MODELS
         else
           []
         end

data/lib/dspy/lm.rb

@@ -14,6 +14,7 @@ require_relative 'lm/adapter_factory'
 require_relative 'lm/adapters/openai_adapter'
 require_relative 'lm/adapters/anthropic_adapter'
 require_relative 'lm/adapters/ollama_adapter'
+require_relative 'lm/adapters/gemini_adapter'
 
 # Load strategy system
 require_relative 'lm/strategy_selector'
@@ -232,10 +233,10 @@ module DSPy
           usage = result.usage
           DSPy.log('span.attributes',
             span_id: DSPy::Context.current[:span_stack].last,
-            'gen_ai.response.model' => result.respond_to?(:model) ? result.model : nil,
-            'gen_ai.usage.prompt_tokens' => usage.respond_to?(:input_tokens) ? usage.input_tokens : nil,
-            'gen_ai.usage.completion_tokens' => usage.respond_to?(:output_tokens) ? usage.output_tokens : nil,
-            'gen_ai.usage.total_tokens' => usage.respond_to?(:total_tokens) ? usage.total_tokens : nil
+            'gen_ai.response.model' => result.metadata.model,
+            'gen_ai.usage.prompt_tokens' => usage.input_tokens,
+            'gen_ai.usage.completion_tokens' => usage.output_tokens,
+            'gen_ai.usage.total_tokens' => usage.total_tokens
           )
         end
         

data/lib/dspy/mixins/struct_builder.rb

@@ -80,7 +80,8 @@ module DSPy
       def extract_type_from_prop(prop)
         case prop
         when Hash
-          prop[:type]
+          # Prefer type_object for nilable types, fallback to type
+          prop[:type_object] || prop[:type]
         when Array
           # Handle [Type, description] format
           prop.first
@@ -94,7 +95,18 @@ module DSPy
       def extract_options_from_prop(prop)
         case prop
         when Hash
-          prop.except(:type, :type_object, :accessor_key, :sensitivity, :redaction)
+          # Preserve important flags like fully_optional for nilable types
+          extracted = prop.except(:type, :type_object, :accessor_key, :sensitivity, :redaction, :setter_proc, :value_validate_proc, :serialized_form, :need_nil_read_check, :immutable, :pii, :extra)
+          
+          # Handle default values properly
+          if prop[:default]
+            extracted[:default] = prop[:default]
+          elsif prop[:fully_optional]
+            # For fully optional fields (nilable), set default to nil
+            extracted[:default] = nil
+          end
+          
+          extracted
         else
           {}
         end

data/lib/dspy/module.rb

@@ -49,10 +49,10 @@ module DSPy
       forward_untyped(**input_values)
     end
 
-    # Get the configured LM for this instance, falling back to global
+    # Get the configured LM for this instance, checking fiber-local context first
     sig { returns(T.untyped) }
     def lm
-      config.lm || DSPy.config.lm
+      config.lm || DSPy.current_lm
     end
   end
 end

data/lib/dspy/predict.rb

@@ -59,6 +59,42 @@ module DSPy
       @prompt = Prompt.from_signature(signature_class)
     end
 
+    # Reconstruct program from serialized hash
+    sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.attached_class) }
+    def self.from_h(data)
+      state = data[:state]
+      raise ArgumentError, "Missing state in serialized data" unless state
+
+      signature_class_name = state[:signature_class]
+      signature_class = Object.const_get(signature_class_name)
+      program = new(signature_class)
+      
+      # Restore instruction if available
+      if state[:instruction]
+        program = program.with_instruction(state[:instruction])
+      end
+      
+      # Restore examples if available
+      few_shot_examples = state[:few_shot_examples]
+      if few_shot_examples && !few_shot_examples.empty?
+        # Convert hash examples back to FewShotExample objects
+        examples = few_shot_examples.map do |ex|
+          if ex.is_a?(Hash)
+            DSPy::FewShotExample.new(
+              input: ex[:input],
+              output: ex[:output],
+              reasoning: ex[:reasoning]
+            )
+          else
+            ex
+          end
+        end
+        program = program.with_examples(examples)
+      end
+      
+      program
+    end
+
     # Backward compatibility methods - delegate to prompt object
     sig { returns(String) }
     def system_signature
@@ -159,7 +195,11 @@ module DSPy
       begin
         combined_struct = create_combined_struct_class
         all_attributes = input_values.merge(output_attributes)
-        combined_struct.new(**all_attributes)
+        
+        # Preprocess nilable attributes before struct instantiation
+        processed_attributes = preprocess_nilable_attributes(all_attributes, combined_struct)
+        
+        combined_struct.new(**processed_attributes)
       rescue ArgumentError => e
         raise PredictionInvalidError.new({ output: e.message })
       rescue TypeError => e
@@ -195,5 +235,36 @@ module DSPy
       
       output_attributes
     end
+
+    # Preprocesses attributes to handle nilable fields properly before struct instantiation
+    sig { params(attributes: T::Hash[Symbol, T.untyped], struct_class: T.class_of(T::Struct)).returns(T::Hash[Symbol, T.untyped]) }
+    def preprocess_nilable_attributes(attributes, struct_class)
+      processed = attributes.dup
+      struct_props = struct_class.props
+
+      # Process each attribute based on its type in the struct
+      processed.each do |key, value|
+        prop_info = struct_props[key]
+        next unless prop_info
+
+        prop_type = prop_info[:type_object] || prop_info[:type]
+        next unless prop_type
+
+        # For nilable fields with nil values, ensure proper handling
+        if value.nil? && is_nilable_type?(prop_type)
+          # For nilable fields, nil is valid - keep it as is
+          next
+        elsif value.nil? && prop_info[:fully_optional]
+          # For fully optional fields, nil is valid - keep it as is
+          next
+        elsif value.nil? && prop_info[:default]
+          # Use default value if available
+          default_value = prop_info[:default]
+          processed[key] = default_value.is_a?(Proc) ? default_value.call : default_value
+        end
+      end
+
+      processed
+    end
   end
 end

data/lib/dspy/prediction.rb

@@ -123,7 +123,8 @@ module DSPy
             end
           elsif is_enum_type?(prop_type) && value.is_a?(String)
             # Convert string to enum
-            converted[key] = prop_type.raw_type.deserialize(value)
+            enum_class = extract_enum_class(prop_type)
+            converted[key] = enum_class.deserialize(value)
           elsif value.is_a?(Hash) && needs_struct_conversion?(prop_type)
             # Regular struct field that needs conversion
             converted[key] = convert_to_struct(value, prop_type)
@@ -188,18 +189,61 @@ module DSPy
     sig { params(type: T.untyped).returns(T::Boolean) }
     def is_enum_type?(type)
       return false if type.nil?
-      return false unless type.is_a?(T::Types::Simple)
       
-      begin
-        raw_type = type.raw_type
-        return false unless raw_type.is_a?(Class)
-        result = raw_type < T::Enum
-        return result == true # Force conversion to boolean
-      rescue StandardError
+      case type
+      when T::Types::Simple
+        # Handle regular enum types
+        begin
+          raw_type = type.raw_type
+          return false unless raw_type.is_a?(Class)
+          result = raw_type < T::Enum
+          return result == true # Force conversion to boolean
+        rescue StandardError
+          return false
+        end
+      when T::Private::Types::SimplePairUnion, T::Types::Union
+        # Handle T.nilable enum types
+        # Find the non-nil type and check if it's an enum
+        non_nil_types = if type.respond_to?(:types)
+          type.types.reject { |t| t.respond_to?(:raw_type) && t.raw_type == NilClass }
+        else
+          []
+        end
+        
+        # For nilable types, we expect exactly one non-nil type
+        return false unless non_nil_types.size == 1
+        
+        non_nil_type = non_nil_types.first
+        return is_enum_type?(non_nil_type) # Recursively check
+      else
         return false
       end
     end
 
+    sig { params(type: T.untyped).returns(T.untyped) }
+    def extract_enum_class(type)
+      case type
+      when T::Types::Simple
+        # Regular enum type
+        type.raw_type
+      when T::Private::Types::SimplePairUnion, T::Types::Union
+        # Nilable enum type - find the non-nil type
+        non_nil_types = if type.respond_to?(:types)
+          type.types.reject { |t| t.respond_to?(:raw_type) && t.raw_type == NilClass }
+        else
+          []
+        end
+        
+        if non_nil_types.size == 1
+          extract_enum_class(non_nil_types.first)
+        else
+          raise ArgumentError, "Unable to extract enum class from complex union type: #{type.inspect}"
+        end
+      else
+        raise ArgumentError, "Not an enum type: #{type.inspect}"
+      end
+    end
+
     sig { params(union_type: T::Types::Union, discriminator_type: T.untyped).returns(T::Hash[String, T.untyped]) }
     def build_type_mapping_from_union(union_type, discriminator_type)
       mapping = {}
@@ -303,7 +347,12 @@ module DSPy
     def needs_struct_conversion?(type)
       case type
       when T::Types::Simple
-        type.raw_type < T::Struct
+        # Use !! to convert nil result of < comparison to false
+        begin
+          !!(type.raw_type < T::Struct)
+        rescue
+          false
+        end
       when T::Types::Union
         # Check if any type in the union is a struct
         type.types.any? { |t| needs_struct_conversion?(t) }
@@ -352,7 +401,7 @@ module DSPy
         end
         begin
           struct_class.new(**converted_hash)
-        rescue => e
+        rescue
           # Return original value if conversion fails
           value
         end

data/lib/dspy/propose/grounded_proposer.rb

@@ -172,15 +172,35 @@ module DSPy
       sig { params(struct_class: T.class_of(T::Struct)).returns(T::Array[T::Hash[Symbol, T.untyped]]) }
       def extract_field_info(struct_class)
         struct_class.props.map do |name, prop_info|
-          {
+          field_info = {
             name: name,
             type: prop_info[:type].to_s,
             description: prop_info[:description] || "",
             required: !prop_info[:rules]&.any? { |rule| rule.is_a?(T::Props::NilableRules) }
           }
+          
+          # Extract enum values if this is an enum type
+          if enum_values = extract_enum_values(prop_info[:type])
+            field_info[:enum_values] = enum_values
+            field_info[:is_enum] = true
+          end
+          
+          field_info
+        end
+      end
+
+      # Extract enum values from a type if it's an enum
+      sig { params(type: T.untyped).returns(T.nilable(T::Array[String])) }
+      def extract_enum_values(type)
+        # Handle T::Enum types
+        if type.is_a?(Class) && type < T::Enum
+          type.values.map(&:serialize)
+        else
+          nil
         end
       end
 
+
       # Analyze patterns in training examples
       sig { params(examples: T::Array[T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
       def analyze_example_patterns(examples)
@@ -364,8 +384,12 @@ module DSPy
         context_parts << "Task: #{signature_class.description}" if @config.use_task_description
         
         if @config.use_input_output_analysis
-          context_parts << "Input fields: #{analysis[:input_fields].map { |f| "#{f[:name]} (#{f[:type]})" }.join(', ')}"
-          context_parts << "Output fields: #{analysis[:output_fields].map { |f| "#{f[:name]} (#{f[:type]})" }.join(', ')}"
+          # Build detailed field descriptions including enum values
+          input_descriptions = analysis[:input_fields].map { |f| format_field_description(f) }
+          output_descriptions = analysis[:output_fields].map { |f| format_field_description(f) }
+          
+          context_parts << "Input fields: #{input_descriptions.join(', ')}"
+          context_parts << "Output fields: #{output_descriptions.join(', ')}"
         end
         
         if analysis[:common_themes] && analysis[:common_themes].any?
@@ -379,6 +403,17 @@ module DSPy
         context_parts.join("\n")
       end
 
+      # Format field description with enum values if applicable
+      sig { params(field: T::Hash[Symbol, T.untyped]).returns(String) }
+      def format_field_description(field)
+        base = "#{field[:name]} (#{field[:type]})"
+        if field[:is_enum] && field[:enum_values] && !field[:enum_values].empty?
+          "#{base} [values: #{field[:enum_values].join(', ')}]"
+        else
+          base
+        end
+      end
+
       # Build requirements text for instruction generation
       sig { params(analysis: T::Hash[Symbol, T.untyped]).returns(String) }
       def build_requirements_text(analysis)

data/lib/dspy/re_act.rb

@@ -112,8 +112,16 @@ module DSPy
         # Use the enhanced output struct with ReAct fields
         @output_struct_class = enhanced_output_struct
 
+        # Store original signature name
+        @original_signature_name = signature_class.name
+
         class << self
-          attr_reader :input_struct_class, :output_struct_class
+          attr_reader :input_struct_class, :output_struct_class, :original_signature_name
+          
+          # Override name to return the original signature name
+          def name
+            @original_signature_name || super
+          end
         end
       end
 
@@ -123,9 +131,6 @@ module DSPy
 
     sig { params(kwargs: T.untyped).returns(T.untyped).override }
     def forward(**kwargs)
-      lm = config.lm || DSPy.config.lm
-      available_tools = @tools.keys
-
       # Validate input
       input_struct = @original_signature_class.input_struct_class.new(**kwargs)
 

data/lib/dspy/signature.rb

@@ -257,17 +257,87 @@ module DSPy
             # Add a more explicit description of the expected structure
             description: "A mapping where keys are #{key_schema[:type]}s and values are #{value_schema[:description] || value_schema[:type]}s"
           }
+        elsif type.class.name == "T::Private::Types::SimplePairUnion"
+          # Handle T.nilable types (T::Private::Types::SimplePairUnion)
+          # This is the actual implementation of T.nilable(SomeType)
+          has_nil = type.respond_to?(:types) && type.types.any? do |t| 
+            (t.respond_to?(:raw_type) && t.raw_type == NilClass) ||
+            (t.respond_to?(:name) && t.name == "NilClass")
+          end
+          
+          if has_nil
+            # Find the non-nil type
+            non_nil_type = type.types.find do |t|
+              !(t.respond_to?(:raw_type) && t.raw_type == NilClass) &&
+              !(t.respond_to?(:name) && t.name == "NilClass")
+            end
+            
+            if non_nil_type
+              base_schema = type_to_json_schema(non_nil_type)
+              if base_schema[:type].is_a?(String)
+                # Convert single type to array with null
+                { type: [base_schema[:type], "null"] }.merge(base_schema.except(:type))
+              else
+                # For complex schemas, use anyOf to allow null
+                { anyOf: [base_schema, { type: "null" }] }
+              end
+            else
+              { type: "string" } # Fallback
+            end
+          else
+            # Not nilable SimplePairUnion - this is a regular T.any() union
+            # Generate oneOf schema for all types
+            if type.respond_to?(:types) && type.types.length > 1
+              {
+                oneOf: type.types.map { |t| type_to_json_schema(t) },
+                description: "Union of multiple types"
+              }
+            else
+              # Single type or fallback
+              first_type = type.respond_to?(:types) ? type.types.first : type
+              type_to_json_schema(first_type)
+            end
+          end
         elsif type.is_a?(T::Types::Union)
-          # For optional types (T.nilable), just use the non-nil type
+          # Check if this is a nilable type (contains NilClass)
+          is_nilable = type.types.any? { |t| t == T::Utils.coerce(NilClass) }
           non_nil_types = type.types.reject { |t| t == T::Utils.coerce(NilClass) }
-          if non_nil_types.size == 1
+          
+          # Special case: check if we have TrueClass + FalseClass (T.nilable(T::Boolean))
+          if non_nil_types.size == 2 && is_nilable
+            true_class_type = non_nil_types.find { |t| t.respond_to?(:raw_type) && t.raw_type == TrueClass }
+            false_class_type = non_nil_types.find { |t| t.respond_to?(:raw_type) && t.raw_type == FalseClass }
+            
+            if true_class_type && false_class_type
+              # This is T.nilable(T::Boolean) - treat as nilable boolean
+              return { type: ["boolean", "null"] }
+            end
+          end
+          
+          if non_nil_types.size == 1 && is_nilable
+            # This is T.nilable(SomeType) - generate proper schema with null allowed
+            base_schema = type_to_json_schema(non_nil_types.first)
+            if base_schema[:type].is_a?(String)
+              # Convert single type to array with null
+              { type: [base_schema[:type], "null"] }.merge(base_schema.except(:type))
+            else
+              # For complex schemas, use anyOf to allow null
+              { anyOf: [base_schema, { type: "null" }] }
+            end
+          elsif non_nil_types.size == 1
+            # Non-nilable single type union (shouldn't happen in practice)
             type_to_json_schema(non_nil_types.first)
           elsif non_nil_types.size > 1
             # Handle complex unions with oneOf for better JSON schema compliance
-            {
+            base_schema = {
               oneOf: non_nil_types.map { |t| type_to_json_schema(t) },
               description: "Union of multiple types"
             }
+            if is_nilable
+              # Add null as an option for complex nilable unions
+              base_schema[:oneOf] << { type: "null" }
+            end
+            base_schema
           else
             { type: "string" }  # Fallback for complex unions
           end

data/lib/dspy/storage/program_storage.rb

@@ -90,18 +90,39 @@ module DSPy
 
         sig { params(program: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
         def serialize_program(program)
-          # Basic serialization - can be enhanced for specific program types
-          {
-            class_name: program.class.name,
-            state: extract_program_state(program)
-          }
+          # Basic serialization
+          if program.is_a?(Hash)
+            # Already serialized - return as-is to preserve state
+            program
+          else
+            # Real program object - serialize it
+            {
+              class_name: program.class.name,
+              state: extract_program_state(program)
+            }
+          end
         end
 
-        sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
+        sig { params(data: T.untyped).returns(T.untyped) }
         def self.deserialize_program(data)
-          # Basic deserialization - would need enhancement for complex programs
-          # For now, return the serialized state
-          data
+          # Ensure data is a Hash
+          unless data.is_a?(Hash)
+            raise ArgumentError, "Expected Hash for program data, got #{data.class.name}"
+          end
+          
+          # Get class name from the serialized data
+          class_name = data[:class_name]
+          raise ArgumentError, "Missing class_name in serialized data" unless class_name
+          
+          # Get the class constant
+          program_class = Object.const_get(class_name)
+          
+          # Use the class's from_h method
+          unless program_class.respond_to?(:from_h)
+            raise ArgumentError, "Class #{class_name} does not support deserialization (missing from_h method)"
+          end
+          
+          program_class.from_h(data)
         end
 
         sig { params(program: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
@@ -310,6 +331,20 @@ module DSPy
           { programs: [], summary: { total_programs: 0, avg_score: 0.0 } }
         end
         
+        # Extract signature class name from program object
+        unless saved_program.program.respond_to?(:signature_class)
+          raise ArgumentError, "Program #{saved_program.program.class.name} does not respond to signature_class method"
+        end
+        
+        signature_class_name = saved_program.program.signature_class.name
+        
+        if signature_class_name.nil? || signature_class_name.empty?
+          raise(
+            "Program #{saved_program.program.class.name} has a signature class that does not provide a name.\n" \
+            "Ensure the signature class responds to #name or that signature_class_name is stored in program state."
+          )
+        end
+        
         # Add or update program entry
         program_entry = {
           program_id: saved_program.program_id,
@@ -317,7 +352,7 @@ module DSPy
           best_score: saved_program.optimization_result[:best_score_value],
           score_name: saved_program.optimization_result[:best_score_name],
           optimizer: saved_program.optimization_result[:metadata]&.dig(:optimizer),
-          signature_class: saved_program.metadata[:signature_class],
+          signature_class: signature_class_name,
           metadata: saved_program.metadata
         }