dspy 0.2.0 → 0.3.0

data/lib/dspy/schema_adapters.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'sorbet-schema'
+
+module DSPy
+  # Schema adapters for integrating sorbet-schema with T::Struct
+  module SchemaAdapters
+    # Handles sorbet-schema integration for serialization/deserialization
+    class SorbetSchemaAdapter
+      extend T::Sig
+      
+      # Serialize a hash to a T::Struct using sorbet-schema
+      #
+      # @param struct_class [Class] T::Struct class 
+      # @param hash_data [Hash] Data to serialize
+      # @return [T::Struct] Validated struct instance
+      sig { params(struct_class: T.class_of(T::Struct), hash_data: T::Hash[T.untyped, T.untyped]).returns(T::Struct) }
+      def self.from_hash(struct_class, hash_data)
+        # TODO: Implement using sorbet-schema
+        # For now, fall back to direct struct creation
+        struct_class.new(**hash_data.transform_keys(&:to_sym))
+      end
+      
+      # Deserialize a T::Struct to a hash using sorbet-schema
+      #
+      # @param struct_instance [T::Struct] Struct instance to serialize
+      # @return [Hash] Serialized hash
+      sig { params(struct_instance: T::Struct).returns(T::Hash[T.untyped, T.untyped]) }
+      def self.to_hash(struct_instance)
+        # TODO: Implement using sorbet-schema
+        # For now, fall back to simple serialization
+        result = {}
+        struct_instance.class.props.each do |name, _prop_info|
+          result[name] = struct_instance.send(name)
+        end
+        result
+      end
+      
+      # Validate data against a T::Struct schema using sorbet-schema
+      #
+      # @param struct_class [Class] T::Struct class
+      # @param hash_data [Hash] Data to validate
+      # @return [Array] [success_boolean, result_or_errors]
+      sig { params(struct_class: T.class_of(T::Struct), hash_data: T::Hash[T.untyped, T.untyped]).returns([T::Boolean, T.untyped]) }
+      def self.validate(struct_class, hash_data)
+        begin
+          result = from_hash(struct_class, hash_data)
+          [true, result]
+        rescue => e
+          [false, [e.message]]
+        end
+      end
+    end
+  end
+end

data/lib/dspy/signature.rb

@@ -1,25 +1,297 @@
 # frozen_string_literal: true
 
+require 'sorbet-runtime'
+require_relative 'schema_adapters'
+
 module DSPy
   class Signature
+    extend T::Sig
+
+    # Container for field type and description
+    class FieldDescriptor
+      extend T::Sig
+
+      sig { returns(T.untyped) }
+      attr_reader :type
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :description
+
+      sig { returns(T::Boolean) }
+      attr_reader :has_default
+
+      sig { params(type: T.untyped, description: T.nilable(String), has_default: T::Boolean).void }
+      def initialize(type, description = nil, has_default = false)
+        @type = type
+        @description = description
+        @has_default = has_default
+      end
+    end
+
+    # DSL helper for building struct classes with field descriptions
+    class StructBuilder
+      extend T::Sig
+
+      sig { returns(T::Hash[Symbol, FieldDescriptor]) }
+      attr_reader :field_descriptors
+
+      sig { void }
+      def initialize
+        @field_descriptors = {}
+      end
+
+      sig { params(name: Symbol, type: T.untyped, kwargs: T.untyped).void }
+      def const(name, type, **kwargs)
+        description = kwargs[:description]
+        has_default = kwargs.key?(:default)
+        @field_descriptors[name] = FieldDescriptor.new(type, description, has_default)
+        # Store default for future use if needed
+      end
+
+      sig { returns(T.class_of(T::Struct)) }
+      def build_struct_class
+        descriptors = @field_descriptors
+        Class.new(T::Struct) do
+          extend T::Sig
+          descriptors.each do |name, descriptor|
+            const name, descriptor.type
+          end
+        end
+      end
+    end
+
     class << self
-      attr_reader :input_schema
-      attr_accessor :output_schema
+      extend T::Sig
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :desc
+
+      sig { returns(T.nilable(T.class_of(T::Struct))) }
+      attr_reader :input_struct_class
+
+      sig { returns(T.nilable(T.class_of(T::Struct))) }
+      attr_reader :output_struct_class
+
+      sig { returns(T::Hash[Symbol, FieldDescriptor]) }
+      attr_reader :input_field_descriptors
+
+      sig { returns(T::Hash[Symbol, FieldDescriptor]) }
+      attr_reader :output_field_descriptors
+
+      sig { params(desc: T.nilable(String)).returns(T.nilable(String)) }
+      def description(desc = nil)
+        if desc.nil?
+          @desc
+        else
+          @desc = desc
+        end
+      end
+
+      sig { params(block: T.proc.void).void }
+      def input(&block)
+        builder = StructBuilder.new
 
-      def description(text = nil)
-        if text
-          @description = text
+        if block.arity > 0
+          block.call(builder)
         else
-          @description
+          # Preferred format
+          builder.instance_eval(&block)
         end
+
+        @input_field_descriptors = builder.field_descriptors
+        @input_struct_class = builder.build_struct_class
       end
 
-      def input(&)
-        @input_schema= Dry::Schema::JSON(&)
+      sig { params(block: T.proc.void).void }
+      def output(&block)
+        builder = StructBuilder.new
+
+        if block.arity > 0
+          block.call(builder)
+        else
+          # Preferred format
+          builder.instance_eval(&block)
+        end
+
+        @output_field_descriptors = builder.field_descriptors
+        @output_struct_class = builder.build_struct_class
       end
 
-      def output(&)
-        @output_schema = Dry::Schema::JSON(&)
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def input_json_schema
+        return {} unless @input_struct_class
+
+        properties = {}
+        required = []
+
+        @input_field_descriptors&.each do |name, descriptor|
+          schema = type_to_json_schema(descriptor.type)
+          schema[:description] = descriptor.description if descriptor.description
+          properties[name] = schema
+          required << name.to_s unless descriptor.has_default
+        end
+
+        {
+          "$schema": "http://json-schema.org/draft-06/schema#",
+          type: "object",
+          properties: properties,
+          required: required
+        }
+      end
+
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def output_json_schema
+        return {} unless @output_struct_class
+
+        properties = {}
+        required = []
+
+        @output_field_descriptors&.each do |name, descriptor|
+          schema = type_to_json_schema(descriptor.type)
+          schema[:description] = descriptor.description if descriptor.description
+          properties[name] = schema
+          required << name.to_s unless descriptor.has_default
+        end
+
+        {
+          "$schema": "http://json-schema.org/draft-06/schema#",
+          type: "object",
+          properties: properties,
+          required: required
+        }
+      end
+
+      private
+
+      sig { params(type: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+      def type_to_json_schema(type)
+        # Handle T::Boolean type alias first
+        if type == T::Boolean
+          return { type: "boolean" }
+        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
+            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: 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 = type_to_json_schema(type.keys)
+          value_schema = 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::Union)
+          # For optional types (T.nilable), just use the non-nil type
+          non_nil_types = type.types.reject { |t| t == T::Utils.coerce(NilClass) }
+          if non_nil_types.size == 1
+            type_to_json_schema(non_nil_types.first)
+          elsif non_nil_types.size > 1
+            # Handle complex unions with oneOf for better JSON schema compliance
+            {
+              oneOf: non_nil_types.map { |t| type_to_json_schema(t) },
+              description: "Union of multiple types"
+            }
+          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
+
+      private
+
+      # Generate JSON schema for custom T::Struct classes
+      sig { params(struct_class: T.class_of(T::Struct)).returns(T::Hash[Symbol, T.untyped]) }
+      def generate_struct_schema(struct_class)
+        return { type: "string", description: "Struct (schema introspection not available)" } unless struct_class.respond_to?(:props)
+
+        properties = {}
+        required = []
+
+        struct_class.props.each do |prop_name, prop_info|
+          prop_type = prop_info[:type_object] || prop_info[:type]
+          properties[prop_name] = 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
     end
   end

data/lib/dspy/subscribers/logger_subscriber.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module DSPy
+  module Subscribers
+    # Logger subscriber that provides detailed logging based on instrumentation events
+    # Subscribes to DSPy events and logs relevant information for debugging and monitoring
+    class LoggerSubscriber
+      extend T::Sig
+
+      sig { params(logger: T.nilable(Logger)).void }
+      def initialize(logger: nil)
+        @logger = T.let(logger || DSPy.config.logger, Logger)
+        setup_event_subscriptions
+      end
+
+      private
+
+      sig { void }
+      def setup_event_subscriptions
+        # Subscribe to DSPy instrumentation events
+        DSPy::Instrumentation.subscribe('dspy.lm.request') do |event|
+          log_lm_request(event)
+        end
+
+        DSPy::Instrumentation.subscribe('dspy.predict') do |event|
+          log_prediction(event)
+        end
+
+        DSPy::Instrumentation.subscribe('dspy.chain_of_thought') do |event|
+          log_chain_of_thought(event)
+        end
+
+        DSPy::Instrumentation.subscribe('dspy.react') do |event|
+          log_react(event)
+        end
+
+        DSPy::Instrumentation.subscribe('dspy.react.iteration_complete') do |event|
+          log_react_iteration_complete(event)
+        end
+
+        DSPy::Instrumentation.subscribe('dspy.react.tool_call') do |event|
+          log_react_tool_call(event)
+        end
+      end
+
+      # Callback methods for different event types
+      sig { params(event: T.untyped).void }
+      def on_lm_request(event)
+        log_lm_request(event)
+      end
+
+      sig { params(event: T.untyped).void }
+      def on_predict(event)
+        log_prediction(event)
+      end
+
+      sig { params(event: T.untyped).void }
+      def on_chain_of_thought(event)
+        log_chain_of_thought(event)
+      end
+
+      sig { params(event: T.untyped).void }
+      def on_react(event)
+        log_react(event)
+      end
+
+      sig { params(event: T.untyped).void }
+      def on_react_iteration_complete(event)
+        log_react_iteration_complete(event)
+      end
+
+      sig { params(event: T.untyped).void }
+      def on_react_tool_call(event)
+        log_react_tool_call(event)
+      end
+
+      # Event logging methods
+      sig { params(event: T.untyped).void }
+      def log_lm_request(event)
+        payload = event.payload
+        provider = payload[:provider]
+        model = payload[:gen_ai_request_model] || payload[:model]
+        duration = payload[:duration_ms]&.round(2)
+        status = payload[:status]
+        tokens = if payload[:tokens_total]
+                   " (#{payload[:tokens_total]} tokens)"
+                 else
+                   ""
+                 end
+
+        status_emoji = status == 'success' ? '✅' : '❌'
+        @logger.info("#{status_emoji} LM Request [#{provider}/#{model}] - #{status} (#{duration}ms)#{tokens}")
+        
+        if status == 'error' && payload[:error_message]
+          @logger.error("  Error: #{payload[:error_message]}")
+        end
+      end
+
+      sig { params(event: T.untyped).void }
+      def log_prediction(event)
+        payload = event.payload
+        signature = payload[:signature_class]
+        duration = payload[:duration_ms]&.round(2)
+        status = payload[:status]
+        input_size = payload[:input_size]
+
+        status_emoji = status == 'success' ? '🔮' : '❌'
+        @logger.info("#{status_emoji} Prediction [#{signature}] - #{status} (#{duration}ms)")
+        @logger.info("  Input size: #{input_size} chars") if input_size
+        
+        if status == 'error' && payload[:error_message]
+          @logger.error("  Error: #{payload[:error_message]}")
+        end
+      end
+
+      sig { params(event: T.untyped).void }
+      def log_chain_of_thought(event)
+        payload = event.payload
+        signature = payload[:signature_class]
+        duration = payload[:duration_ms]&.round(2)
+        status = payload[:status]
+        reasoning_steps = payload[:reasoning_steps]
+        reasoning_length = payload[:reasoning_length]
+
+        status_emoji = status == 'success' ? '🧠' : '❌'
+        @logger.info("#{status_emoji} Chain of Thought [#{signature}] - #{status} (#{duration}ms)")
+        @logger.info("  Reasoning steps: #{reasoning_steps}") if reasoning_steps
+        @logger.info("  Reasoning length: #{reasoning_length} chars") if reasoning_length
+        
+        if status == 'error' && payload[:error_message]
+          @logger.error("  Error: #{payload[:error_message]}")
+        end
+      end
+
+      sig { params(event: T.untyped).void }
+      def log_react(event)
+        payload = event.payload
+        signature = payload[:signature_class]
+        duration = payload[:duration_ms]&.round(2)
+        status = payload[:status]
+        iteration_count = payload[:iteration_count]
+        tools_used = payload[:tools_used]
+        final_answer = payload[:final_answer]
+
+        status_emoji = case status
+                       when 'success' then '🤖'
+                       when 'max_iterations' then '⏰'
+                       else '❌'
+                       end
+        
+        @logger.info("#{status_emoji} ReAct Agent [#{signature}] - #{status} (#{duration}ms)")
+        @logger.info("  Iterations: #{iteration_count}") if iteration_count
+        @logger.info("  Tools used: #{tools_used.join(', ')}") if tools_used&.any?
+        @logger.info("  Final answer: #{final_answer}") if final_answer
+        
+        if status == 'error' && payload[:error_message]
+          @logger.error("  Error: #{payload[:error_message]}")
+        end
+      end
+
+      sig { params(event: T.untyped).void }
+      def log_react_iteration_complete(event)
+        payload = event.payload
+        iteration = payload[:iteration]
+        thought = payload[:thought]
+        action = payload[:action]
+        duration = payload[:duration_ms]&.round(2)
+        status = payload[:status]
+
+        status_emoji = status == 'success' ? '🔄' : '❌'
+        @logger.info("#{status_emoji} ReAct Iteration #{iteration} - #{status} (#{duration}ms)")
+        @logger.info("  Thought: #{thought.truncate(100)}") if thought
+        @logger.info("  Action: #{action}") if action
+        
+        if status == 'error' && payload[:error_message]
+          @logger.error("  Error: #{payload[:error_message]}")
+        end
+      end
+
+      sig { params(event: T.untyped).void }
+      def log_react_tool_call(event)
+        payload = event.payload
+        iteration = payload[:iteration]
+        tool_name = payload[:tool_name]
+        duration = payload[:duration_ms]&.round(2)
+        status = payload[:status]
+
+        status_emoji = status == 'success' ? '🔧' : '❌'
+        @logger.info("#{status_emoji} Tool Call [#{tool_name}] (Iteration #{iteration}) - #{status} (#{duration}ms)")
+        
+        if status == 'error' && payload[:error_message]
+          @logger.error("  Error: #{payload[:error_message]}")
+        end
+      end
+    end
+  end
+end