dspy 0.27.1 → 0.27.2

data/lib/dspy/tools/toolset.rb

@@ -2,6 +2,8 @@
 
 require 'sorbet-runtime'
 require 'json'
+require_relative '../type_system/sorbet_json_schema'
+require_relative '../mixins/type_coercion'
 
 module DSPy
   module Tools
@@ -69,10 +71,8 @@ module DSPy
           sig_info.kwarg_types.each do |param_name, param_type|
             next if param_name == :block
 
-            properties[param_name] = {
-              type: sorbet_type_to_json_schema(param_type)[:type],
-              description: "Parameter #{param_name}"
-            }
+            schema = DSPy::TypeSystem::SorbetJsonSchema.type_to_json_schema(param_type)
+            properties[param_name] = schema.merge({ description: "Parameter #{param_name}" })
 
             # Check if parameter is required
             if sig_info.req_kwarg_names.include?(param_name)
@@ -89,61 +89,12 @@ module DSPy
           }
         end
 
-        private
-
-        # Convert Sorbet types to JSON Schema types (extracted from Base)
-        sig { params(sorbet_type: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
-        def sorbet_type_to_json_schema(sorbet_type)
-          # Check for boolean types first (SimplePairUnion of TrueClass | FalseClass)
-          if sorbet_type.respond_to?(:types) && sorbet_type.types.length == 2
-            raw_types = sorbet_type.types.map do |t|
-              t.is_a?(T::Types::Simple) ? t.raw_type : t
-            end
-            
-            if raw_types.include?(TrueClass) && raw_types.include?(FalseClass)
-              return { type: :boolean }
-            end
-          end
-          
-          if sorbet_type.is_a?(T::Types::Simple)
-            raw_type = sorbet_type.raw_type
-
-            case raw_type
-            when String
-              { type: :string }
-            when Integer
-              { type: :integer }
-            when Float, Numeric
-              { type: :number }
-            when TrueClass, FalseClass, T::Boolean
-              { type: :boolean }
-            else
-              { type: :string, description: "#{raw_type} (converted to string)" }
-            end
-          elsif sorbet_type.is_a?(T::Types::Union)
-            # Handle nilable types
-            non_nil_types = sorbet_type.types.reject { |t| t == T::Utils.coerce(NilClass) }
-            if non_nil_types.length == 1
-              result = sorbet_type_to_json_schema(non_nil_types.first)
-              result[:description] = "#{result[:description] || ''} (optional)".strip
-              result
-            else
-              { type: :string, description: "Union type (converted to string)" }
-            end
-          elsif sorbet_type.is_a?(T::Types::TypedArray)
-            {
-              type: :array,
-              items: sorbet_type_to_json_schema(sorbet_type.type)
-            }
-          else
-            { type: :string, description: "#{sorbet_type} (converted to string)" }
-          end
-        end
       end
 
       # Inner class that wraps a method as a tool, compatible with DSPy::Tools::Base interface
       class ToolProxy < Base
         extend T::Sig
+        include DSPy::Mixins::TypeCoercion
 
         sig { params(instance: Toolset, method_name: Symbol, tool_name: String, description: String).void }
         def initialize(instance, method_name, tool_name, description)
@@ -203,12 +154,34 @@ module DSPy
 
             # Convert string keys to symbols and validate types
             kwargs = {}
-            schema[:properties].each do |param_name, param_schema|
-              key = param_name.to_s
-              if args.key?(key)
-                kwargs[param_name] = convert_argument_type(args[key], param_schema)
-              elsif schema[:required].include?(key)
-                return "Error: Missing required parameter: #{key}"
+            
+            # Get method signature for type information
+            method_obj = @instance.class.instance_method(@method_name)
+            sig_info = T::Utils.signature_for_method(method_obj)
+            
+            if sig_info
+              # Handle kwargs using type signature information
+              sig_info.kwarg_types.each do |param_name, param_type|
+                next if param_name == :block
+                
+                key = param_name.to_s
+                if args.key?(key)
+                  kwargs[param_name] = coerce_value_to_type(args[key], param_type)
+                elsif schema[:required].include?(key)
+                  return "Error: Missing required parameter: #{key}"
+                end
+              end
+              
+              # Handle positional args if any
+              sig_info.arg_types.each do |param_name, param_type|
+                next if param_name == :block
+                
+                key = param_name.to_s
+                if args.key?(key)
+                  kwargs[param_name] = coerce_value_to_type(args[key], param_type)
+                elsif schema[:required].include?(key)
+                  return "Error: Missing required parameter: #{key}"
+                end
               end
             end
 

data/lib/dspy/type_system/sorbet_json_schema.rb

@@ -0,0 +1,263 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module DSPy
+  module TypeSystem
+    # Unified module for converting Sorbet types to JSON Schema
+    # Extracted from Signature class to ensure consistency across Tools, Toolsets, and Signatures
+    module SorbetJsonSchema
+      extend T::Sig
+      extend T::Helpers
+
+      # Convert a Sorbet type to JSON Schema format
+      sig { params(type: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+      def self.type_to_json_schema(type)
+        # Handle T::Boolean type alias first
+        if type == T::Boolean
+          return { type: "boolean" }
+        end
+
+        # Handle type aliases by resolving to their underlying type
+        if type.is_a?(T::Private::Types::TypeAlias)
+          return self.type_to_json_schema(type.aliased_type)
+        end
+
+        # Handle raw class types first
+        if type.is_a?(Class)
+          if type < T::Enum
+            # Get all enum values
+            values = type.values.map(&:serialize)
+            { type: "string", enum: values }
+          elsif type == String
+            { type: "string" }
+          elsif type == Integer
+            { type: "integer" }
+          elsif type == Float
+            { type: "number" }
+          elsif type == Numeric
+            { type: "number" }
+          elsif [TrueClass, FalseClass].include?(type)
+            { type: "boolean" }
+          elsif type < T::Struct
+            # Handle custom T::Struct classes by generating nested object schema
+            self.generate_struct_schema(type)
+          else
+            { type: "string" }  # Default fallback
+          end
+        elsif type.is_a?(T::Types::Simple)
+          case type.raw_type.to_s
+          when "String"
+            { type: "string" }
+          when "Integer"
+            { type: "integer" }
+          when "Float"
+            { type: "number" }
+          when "Numeric"
+            { type: "number" }
+          when "TrueClass", "FalseClass"
+            { type: "boolean" }
+          when "T::Boolean"
+            { type: "boolean" }
+          else
+            # Check if it's an enum
+            if type.raw_type < T::Enum
+              # Get all enum values
+              values = type.raw_type.values.map(&:serialize)
+              { type: "string", enum: values }
+            elsif type.raw_type < T::Struct
+              # Handle custom T::Struct classes
+              generate_struct_schema(type.raw_type)
+            else
+              { type: "string" }  # Default fallback
+            end
+          end
+        elsif type.is_a?(T::Types::TypedArray)
+          # Handle arrays properly with nested item type
+          {
+            type: "array",
+            items: self.type_to_json_schema(type.type)
+          }
+        elsif type.is_a?(T::Types::TypedHash)
+          # Handle hashes as objects with additionalProperties
+          # TypedHash has keys and values methods to access its key and value types
+          key_schema = self.type_to_json_schema(type.keys)
+          value_schema = self.type_to_json_schema(type.values)
+          
+          # Create a more descriptive schema for nested structures
+          {
+            type: "object",
+            propertyNames: key_schema,  # Describe key constraints
+            additionalProperties: value_schema,
+            # 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] = self.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 = self.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| self.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
+              self.type_to_json_schema(first_type)
+            end
+          end
+        elsif type.is_a?(T::Types::Union)
+          # 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) }
+          
+          # 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 = self.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)
+            self.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| self.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
+        elsif type.is_a?(T::Types::ClassOf)
+          # Handle T.class_of() types
+          {
+            type: "string",
+            description: "Class name (T.class_of type)"
+          }
+        else
+          { type: "string" }  # Default fallback
+        end
+      end
+
+      # Generate JSON schema for custom T::Struct classes
+      sig { params(struct_class: T.class_of(T::Struct)).returns(T::Hash[Symbol, T.untyped]) }
+      def self.generate_struct_schema(struct_class)
+        return { type: "string", description: "Struct (schema introspection not available)" } unless struct_class.respond_to?(:props)
+
+        properties = {}
+        required = []
+
+        # Check if struct already has a _type field
+        if struct_class.props.key?(:_type)
+          raise DSPy::ValidationError, "_type field conflict: #{struct_class.name} already has a _type field defined. " \
+                                       "DSPy uses _type for automatic type detection in union types."
+        end
+
+        # Add automatic _type field for type detection
+        properties[:_type] = {
+          type: "string",
+          const: struct_class.name.split('::').last  # Use the simple class name
+        }
+        required << "_type"
+
+        struct_class.props.each do |prop_name, prop_info|
+          prop_type = prop_info[:type_object] || prop_info[:type]
+          properties[prop_name] = self.type_to_json_schema(prop_type)
+          
+          # A field is required if it's not fully optional
+          # fully_optional is true for nilable prop fields
+          # immutable const fields are required unless nilable
+          unless prop_info[:fully_optional]
+            required << prop_name.to_s
+          end
+        end
+
+        {
+          type: "object",
+          properties: properties,
+          required: required,
+          description: "#{struct_class.name} struct"
+        }
+      end
+
+      private
+
+      # Extensions to Hash for Rails-like except method if not available
+      # This ensures compatibility with the original code
+      unless Hash.method_defined?(:except)
+        Hash.class_eval do
+          def except(*keys)
+            dup.tap do |hash|
+              keys.each { |key| hash.delete(key) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dspy/version.rb

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

data/lib/dspy.rb

@@ -8,6 +8,7 @@ require_relative 'dspy/version'
 require_relative 'dspy/errors'
 require_relative 'dspy/type_serializer'
 require_relative 'dspy/observability'
+require_relative 'dspy/observability/observation_type'
 require_relative 'dspy/context'
 require_relative 'dspy/events'
 require_relative 'dspy/events/types'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.27.1
+  version: 0.27.2
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
 bindir: bin
 cert_chain: []
-date: 2025-09-14 00:00:00.000000000 Z
+date: 2025-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -212,7 +212,6 @@ files:
 - lib/dspy/lm/adapters/ollama_adapter.rb
 - lib/dspy/lm/adapters/openai/schema_converter.rb
 - lib/dspy/lm/adapters/openai_adapter.rb
-- lib/dspy/lm/cache_manager.rb
 - lib/dspy/lm/errors.rb
 - lib/dspy/lm/message.rb
 - lib/dspy/lm/message_builder.rb
@@ -241,6 +240,7 @@ files:
 - lib/dspy/module.rb
 - lib/dspy/observability.rb
 - lib/dspy/observability/async_span_processor.rb
+- lib/dspy/observability/observation_type.rb
 - lib/dspy/optimizers/gaussian_process.rb
 - lib/dspy/predict.rb
 - lib/dspy/prediction.rb
@@ -262,10 +262,12 @@ files:
 - lib/dspy/teleprompt/utils.rb
 - lib/dspy/tools.rb
 - lib/dspy/tools/base.rb
+- lib/dspy/tools/github_cli_toolset.rb
 - lib/dspy/tools/memory_toolset.rb
 - lib/dspy/tools/text_processing_toolset.rb
 - lib/dspy/tools/toolset.rb
 - lib/dspy/type_serializer.rb
+- lib/dspy/type_system/sorbet_json_schema.rb
 - lib/dspy/utils/serialization.rb
 - lib/dspy/version.rb
 homepage: https://github.com/vicentereig/dspy.rb

data/lib/dspy/lm/cache_manager.rb

@@ -1,151 +0,0 @@
-# frozen_string_literal: true
-
-require "sorbet-runtime"
-
-module DSPy
-  class LM
-    # Manages caching for schemas and capability detection
-    class CacheManager
-      extend T::Sig
-      
-      # Cache entry with TTL
-      class CacheEntry < T::Struct
-        extend T::Sig
-        
-        const :value, T.untyped
-        const :expires_at, Time
-        
-        sig { returns(T::Boolean) }
-        def expired?
-          Time.now > expires_at
-        end
-      end
-      
-      DEFAULT_TTL = 3600 # 1 hour
-      
-      sig { void }
-      def initialize
-        @schema_cache = {}
-        @capability_cache = {}
-        @mutex = Mutex.new
-      end
-      
-      # Cache a schema for a signature class
-      sig { params(signature_class: T.class_of(DSPy::Signature), provider: String, schema: T.untyped, cache_params: T::Hash[Symbol, T.untyped]).void }
-      def cache_schema(signature_class, provider, schema, cache_params = {})
-        key = schema_key(signature_class, provider, cache_params)
-        
-        @mutex.synchronize do
-          @schema_cache[key] = CacheEntry.new(
-            value: schema,
-            expires_at: Time.now + DEFAULT_TTL
-          )
-        end
-        
-        DSPy.logger.debug("Cached schema for #{signature_class.name} (#{provider})")
-      end
-      
-      # Get cached schema if available
-      sig { params(signature_class: T.class_of(DSPy::Signature), provider: String, cache_params: T::Hash[Symbol, T.untyped]).returns(T.nilable(T.untyped)) }
-      def get_schema(signature_class, provider, cache_params = {})
-        key = schema_key(signature_class, provider, cache_params)
-        
-        @mutex.synchronize do
-          entry = @schema_cache[key]
-          
-          if entry.nil?
-            nil
-          elsif entry.expired?
-            @schema_cache.delete(key)
-            nil
-          else
-            entry.value
-          end
-        end
-      end
-      
-      # Cache capability detection result
-      sig { params(model: String, capability: String, result: T::Boolean).void }
-      def cache_capability(model, capability, result)
-        key = capability_key(model, capability)
-        
-        @mutex.synchronize do
-          @capability_cache[key] = CacheEntry.new(
-            value: result,
-            expires_at: Time.now + DEFAULT_TTL * 24 # Capabilities change less frequently
-          )
-        end
-        
-        DSPy.logger.debug("Cached capability #{capability} for #{model}: #{result}")
-      end
-      
-      # Get cached capability if available
-      sig { params(model: String, capability: String).returns(T.nilable(T::Boolean)) }
-      def get_capability(model, capability)
-        key = capability_key(model, capability)
-        
-        @mutex.synchronize do
-          entry = @capability_cache[key]
-          
-          if entry.nil?
-            nil
-          elsif entry.expired?
-            @capability_cache.delete(key)
-            nil
-          else
-            entry.value
-          end
-        end
-      end
-      
-      # Clear all caches
-      sig { void }
-      def clear!
-        @mutex.synchronize do
-          @schema_cache.clear
-          @capability_cache.clear
-        end
-        
-        DSPy.logger.debug("Cleared all caches")
-      end
-      
-      # Get cache statistics
-      sig { returns(T::Hash[Symbol, Integer]) }
-      def stats
-        @mutex.synchronize do
-          {
-            schema_entries: @schema_cache.size,
-            capability_entries: @capability_cache.size,
-            total_entries: @schema_cache.size + @capability_cache.size
-          }
-        end
-      end
-      
-      private
-      
-      sig { params(signature_class: T.class_of(DSPy::Signature), provider: String, cache_params: T::Hash[Symbol, T.untyped]).returns(String) }
-      def schema_key(signature_class, provider, cache_params = {})
-        params_str = cache_params.sort.map { |k, v| "#{k}:#{v}" }.join(":")
-        base_key = "schema:#{provider}:#{signature_class.name}"
-        params_str.empty? ? base_key : "#{base_key}:#{params_str}"
-      end
-      
-      sig { params(model: String, capability: String).returns(String) }
-      def capability_key(model, capability)
-        "capability:#{model}:#{capability}"
-      end
-    end
-    
-    # Global cache instance
-    @cache_manager = T.let(nil, T.nilable(CacheManager))
-    
-    class << self
-      extend T::Sig
-      
-      sig { returns(CacheManager) }
-      def cache_manager
-        @cache_manager ||= CacheManager.new
-      end
-    end
-  end
-end