dspy 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44cf35be07e90187237ccdc79533d0ca76dbe2cb1040f0e841bff69afd7e71fc
-  data.tar.gz: 443a4d5dafe1fc7c90335e2b6294a4b1e1dd77b77cb24c19c7f8237f1824b2d0
+  metadata.gz: 78e01258a3b9b5a1bccddad913a1d0aa45ecb145a65adb3e691986cadbea6e23
+  data.tar.gz: 9a778ea689150002e0766357dd4aa4af526be81979378b9996ba9067c2cdbd42
 SHA512:
-  metadata.gz: 6e2e2e6098773c599190e0ab5e43ecd883e04359268557f28b0350219b98995c8fbe6633db2a5d1a34be1d250ae10ce05cd4aaaebefd6c13f5e855fcf587b5ef
-  data.tar.gz: b14760bb9cf7075991fdfc274bab60e1d55a4547a8b0da2b78c37bb76c69c4963a899f8ab26f26612210957f6184999b769adc590f90bd60714f992ab1c20230
+  metadata.gz: 7ba1376b844e5c5e61215b961142a70f82d758db41e061bf2e7404f4ffdbae867197b0c38254a92b25892beb51922fb3c3b963ab2474494c9d490b83814bba5d
+  data.tar.gz: 4a543e0b954469f316f003f36c5a55b97b0794ef1cbf395180ac5197acf5d4091bfe3ea87e342473c190d96adf5761baff59532502a20778edea23a83a9e5253

data/README.md

@@ -14,6 +14,10 @@ Traditional prompting is like writing code with string concatenation: it works u
 the programming approach pioneered by [dspy.ai](https://dspy.ai/): instead of crafting fragile prompts, you define modular 
 signatures and let the framework handle the messy details.
 
+DSPy.rb is an idiomatic Ruby port of Stanford's [DSPy framework](https://github.com/stanfordnlp/dspy). While implementing 
+the core concepts of signatures, predictors, and optimization from the original Python library, DSPy.rb embraces Ruby 
+conventions and adds Ruby-specific innovations like CodeAct agents and enhanced production instrumentation.
+
 The result? LLM applications that actually scale and don't break when you sneeze.
 
 ## Your First DSPy Program
@@ -210,7 +214,7 @@ and ecosystem integration.
 
 ### Ecosystem Expansion  
 - 🚧 **Model Context Protocol (MCP)** - Integration with MCP ecosystem
-- 🚧 **Additional Provider Support** - Google Gemini, Azure OpenAI, local models beyond Ollama
+- 🚧 **Additional Provider Support** - Azure OpenAI, local models beyond Ollama
 - 🚧 **Tool Ecosystem** - Expanded tool integrations for ReAct agents
 
 ### Community & Adoption

data/lib/dspy/evaluate.rb

@@ -49,7 +49,7 @@ module DSPy
       def to_h
         {
           example: @example,
-          prediction: @prediction,
+          prediction: @prediction.respond_to?(:to_h) ? @prediction.to_h : @prediction,
           trace: @trace,
           metrics: @metrics,
           passed: @passed

data/lib/dspy/lm/strategies/enhanced_prompting_strategy.rb

@@ -114,24 +114,55 @@ module DSPy
 
           example = {}
           schema[:properties].each do |field_name, field_schema|
-            example[field_name.to_s] = case field_schema[:type]
-            when "string"
-              field_schema[:description] || "example string"
-            when "integer"
-              42
-            when "number"
-              3.14
-            when "boolean"
-              true
-            when "array"
+            example[field_name.to_s] = generate_example_value(field_schema)
+          end
+          example
+        end
+
+        sig { params(field_schema: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
+        def generate_example_value(field_schema)
+          case field_schema[:type]
+          when "string"
+            field_schema[:description] || "example string"
+          when "integer"
+            42
+          when "number"
+            3.14
+          when "boolean"
+            true
+          when "array"
+            if field_schema[:items]
+              [generate_example_value(field_schema[:items])]
+            else
               ["example item"]
-            when "object"
+            end
+          when "object"
+            if field_schema[:properties]
+              # Generate proper nested object example
+              nested_example = {}
+              field_schema[:properties].each do |prop_name, prop_schema|
+                nested_example[prop_name.to_s] = generate_example_value(prop_schema)
+              end
+              nested_example
+            else
               { "nested" => "object" }
+            end
+          when Array
+            # Handle union types like ["object", "null"]
+            if field_schema[:type].include?("object") && field_schema[:properties]
+              nested_example = {}
+              field_schema[:properties].each do |prop_name, prop_schema|
+                nested_example[prop_name.to_s] = generate_example_value(prop_schema)
+              end
+              nested_example
+            elsif field_schema[:type].include?("string")
+              "example string"
             else
               "example value"
             end
+          else
+            "example value"
           end
-          example
         end
 
         sig { params(content: String).returns(T::Boolean) }

data/lib/dspy/lm/vision_models.rb

@@ -27,6 +27,7 @@ module DSPy
       ].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',
@@ -34,17 +35,11 @@ module DSPy
         'gemini-2.5-flash-lite',
         # Gemini 2.0 series (2024-2025)
         'gemini-2.0-flash',
-        'gemini-2.0-flash-experimental',
-        'gemini-2.0-flash-lite', 
-        'gemini-2.0-pro-experimental',
+        'gemini-2.0-flash-lite',
         # Gemini 1.5 series
         'gemini-1.5-pro',
         'gemini-1.5-flash',
-        'gemini-1.5-pro-latest',
-        'gemini-1.5-flash-latest',
-        # Legacy models
-        'gemini-pro-vision',
-        'gemini-1.0-pro-vision'
+        'gemini-1.5-flash-8b'
       ].freeze
       
       def self.supports_vision?(provider, model)

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

@@ -195,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
@@ -231,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/signature.rb

@@ -188,6 +188,11 @@ module DSPy
           return { type: "boolean" }
         end
 
+        # Handle type aliases by resolving to their underlying type
+        if type.is_a?(T::Private::Types::TypeAlias)
+          return type_to_json_schema(type.aliased_type)
+        end
+
         # Handle raw class types first
         if type.is_a?(Class)
           if type < T::Enum
@@ -257,17 +262,103 @@ 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.is_a?(T::Types::FixedHash)
+          # Handle fixed hashes (from type aliases like { "key" => Type })
+          properties = {}
+          required = []
+          
+          type.types.each do |key, value_type|
+            properties[key] = type_to_json_schema(value_type)
+            required << key
+          end
+          
+          {
+            type: "object",
+            properties: properties,
+            required: required,
+            additionalProperties: false
+          }
+        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/teleprompt/mipro_v2.rb

@@ -203,6 +203,9 @@ module DSPy
         sig { returns(T::Hash[Symbol, T.untyped]) }
         attr_reader :proposal_statistics
 
+        sig { returns(T.nilable(DSPy::Evaluate::BatchEvaluationResult)) }
+        attr_reader :best_evaluation_result
+
         sig do
           params(
             optimized_program: T.untyped,
@@ -214,10 +217,11 @@ module DSPy
             proposal_statistics: T::Hash[Symbol, T.untyped],
             best_score_name: T.nilable(String),
             best_score_value: T.nilable(Float),
-            metadata: T::Hash[Symbol, T.untyped]
+            metadata: T::Hash[Symbol, T.untyped],
+            best_evaluation_result: T.nilable(DSPy::Evaluate::BatchEvaluationResult)
           ).void
         end
-        def initialize(optimized_program:, scores:, history:, evaluated_candidates:, optimization_trace:, bootstrap_statistics:, proposal_statistics:, best_score_name: nil, best_score_value: nil, metadata: {})
+        def initialize(optimized_program:, scores:, history:, evaluated_candidates:, optimization_trace:, bootstrap_statistics:, proposal_statistics:, best_score_name: nil, best_score_value: nil, metadata: {}, best_evaluation_result: nil)
           super(
             optimized_program: optimized_program,
             scores: scores,
@@ -230,6 +234,7 @@ module DSPy
           @optimization_trace = optimization_trace.freeze
           @bootstrap_statistics = bootstrap_statistics.freeze
           @proposal_statistics = proposal_statistics.freeze
+          @best_evaluation_result = best_evaluation_result&.freeze
         end
 
         sig { returns(T::Hash[Symbol, T.untyped]) }
@@ -238,7 +243,8 @@ module DSPy
             evaluated_candidates: @evaluated_candidates.map(&:to_h),
             optimization_trace: @optimization_trace,
             bootstrap_statistics: @bootstrap_statistics,
-            proposal_statistics: @proposal_statistics
+            proposal_statistics: @proposal_statistics,
+            best_evaluation_result: @best_evaluation_result&.to_h
           })
         end
       end
@@ -399,6 +405,7 @@ module DSPy
         best_score = 0.0
         best_candidate = nil
         best_program = nil
+        best_evaluation_result = nil
         
         @mipro_config.num_trials.times do |trial_idx|
           trials_completed = trial_idx + 1
@@ -415,7 +422,7 @@ module DSPy
 
           begin
             # Evaluate candidate
-            score, modified_program = evaluate_candidate(program, candidate, evaluation_set)
+            score, modified_program, evaluation_result = evaluate_candidate(program, candidate, evaluation_set)
             
             # Update optimization state
             update_optimization_state(optimization_state, candidate, score)
@@ -426,6 +433,7 @@ module DSPy
               best_score = score
               best_candidate = candidate
               best_program = modified_program
+              best_evaluation_result = evaluation_result
             end
 
             emit_event('trial_complete', {
@@ -456,6 +464,7 @@ module DSPy
           best_score: best_score,
           best_candidate: best_candidate,
           best_program: best_program,
+          best_evaluation_result: best_evaluation_result,
           trials_completed: trials_completed,
           optimization_state: optimization_state,
           evaluated_candidates: @evaluated_candidates
@@ -626,7 +635,7 @@ module DSPy
           program: T.untyped,
           candidate: CandidateConfig,
           evaluation_set: T::Array[DSPy::Example]
-        ).returns([Float, T.untyped])
+        ).returns([Float, T.untyped, DSPy::Evaluate::BatchEvaluationResult])
       end
       def evaluate_candidate(program, candidate, evaluation_set)
         # Apply candidate configuration to program
@@ -638,7 +647,7 @@ module DSPy
         # Store evaluation details
         @evaluated_candidates << candidate
         
-        [evaluation_result.pass_rate, modified_program]
+        [evaluation_result.pass_rate, modified_program, evaluation_result]
       end
 
       # Apply candidate configuration to program
@@ -724,6 +733,7 @@ module DSPy
         best_candidate = optimization_result[:best_candidate]
         best_program = optimization_result[:best_program]
         best_score = optimization_result[:best_score]
+        best_evaluation_result = optimization_result[:best_evaluation_result]
         
         scores = { pass_rate: best_score }
         
@@ -753,7 +763,8 @@ module DSPy
           evaluated_candidates: @evaluated_candidates,
           optimization_trace: serialize_optimization_trace(optimization_result[:optimization_state]),
           bootstrap_statistics: bootstrap_result.statistics,
-          proposal_statistics: proposal_result.analysis
+          proposal_statistics: proposal_result.analysis,
+          best_evaluation_result: best_evaluation_result
         )
       end
 

data/lib/dspy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DSPy
-  VERSION = "0.20.0"
+  VERSION = "0.21.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
 bindir: bin
 cert_chain: []
-date: 2025-08-26 00:00:00.000000000 Z
+date: 2025-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable