dspy 0.28.0 → 0.28.2

data/lib/dspy/prompt.rb

@@ -22,21 +22,39 @@ module DSPy
     sig { returns(T.nilable(String)) }
     attr_reader :signature_class_name
 
+    # Returns the effective schema format
+    # Precedence: instance variable (if not :json default) > config.lm > :json
+    sig { returns(Symbol) }
+    def schema_format
+      # If @schema_format was explicitly set to something other than :json, respect it
+      return @schema_format if @schema_format && @schema_format != :json
+
+      # Otherwise, read from config if available
+      DSPy.config.lm&.schema_format || @schema_format || :json
+    end
+
+    sig { returns(T.nilable(T.class_of(Signature))) }
+    attr_reader :signature_class
+
     sig do
       params(
         instruction: String,
         input_schema: T::Hash[Symbol, T.untyped],
         output_schema: T::Hash[Symbol, T.untyped],
         few_shot_examples: T::Array[FewShotExample],
-        signature_class_name: T.nilable(String)
+        signature_class_name: T.nilable(String),
+        schema_format: Symbol,
+        signature_class: T.nilable(T.class_of(Signature))
       ).void
     end
-    def initialize(instruction:, input_schema:, output_schema:, few_shot_examples: [], signature_class_name: nil)
+    def initialize(instruction:, input_schema:, output_schema:, few_shot_examples: [], signature_class_name: nil, schema_format: :json, signature_class: nil)
       @instruction = instruction
       @few_shot_examples = few_shot_examples.freeze
       @input_schema = input_schema.freeze
       @output_schema = output_schema.freeze
       @signature_class_name = signature_class_name
+      @schema_format = schema_format
+      @signature_class = signature_class
     end
 
     # Immutable update methods for optimization
@@ -47,7 +65,9 @@ module DSPy
         input_schema: @input_schema,
         output_schema: @output_schema,
         few_shot_examples: @few_shot_examples,
-        signature_class_name: @signature_class_name
+        signature_class_name: @signature_class_name,
+        schema_format: @schema_format,
+        signature_class: @signature_class
       )
     end
 
@@ -58,7 +78,9 @@ module DSPy
         input_schema: @input_schema,
         output_schema: @output_schema,
         few_shot_examples: new_examples,
-        signature_class_name: @signature_class_name
+        signature_class_name: @signature_class_name,
+        schema_format: @schema_format,
+        signature_class: @signature_class
       )
     end
 
@@ -72,16 +94,29 @@ module DSPy
     sig { returns(String) }
     def render_system_prompt
       sections = []
-      
-      sections << "Your input schema fields are:"
-      sections << "```json"
-      sections << JSON.pretty_generate(@input_schema)
-      sections << "```"
-      
-      sections << "Your output schema fields are:"
-      sections << "```json"
-      sections << JSON.pretty_generate(@output_schema)
-      sections << "```"
+
+      case schema_format
+      when :baml
+        sections << "Your input schema fields are:"
+        sections << "```baml"
+        sections << render_baml_schema(@input_schema, :input)
+        sections << "```"
+
+        sections << "Your output schema fields are:"
+        sections << "```baml"
+        sections << render_baml_schema(@output_schema, :output)
+        sections << "```"
+      else  # :json (default)
+        sections << "Your input schema fields are:"
+        sections << "```json"
+        sections << JSON.pretty_generate(@input_schema)
+        sections << "```"
+
+        sections << "Your output schema fields are:"
+        sections << "```json"
+        sections << JSON.pretty_generate(@output_schema)
+        sections << "```"
+      end
       
       sections << ""
       sections << "All interactions will be structured in the following way, with the appropriate values filled in."
@@ -148,32 +183,36 @@ module DSPy
         few_shot_examples: @few_shot_examples.map(&:to_h),
         input_schema: @input_schema,
         output_schema: @output_schema,
-        signature_class_name: @signature_class_name
+        signature_class_name: @signature_class_name,
+        schema_format: @schema_format
       }
     end
 
     sig { params(hash: T::Hash[Symbol, T.untyped]).returns(Prompt) }
     def self.from_h(hash)
       examples = (hash[:few_shot_examples] || []).map { |ex| FewShotExample.from_h(ex) }
-      
+
       new(
         instruction: hash[:instruction] || "",
         input_schema: hash[:input_schema] || {},
         output_schema: hash[:output_schema] || {},
         few_shot_examples: examples,
-        signature_class_name: hash[:signature_class_name]
+        signature_class_name: hash[:signature_class_name],
+        schema_format: hash[:schema_format] || :json
       )
     end
 
     # Create prompt from signature class
-    sig { params(signature_class: T.class_of(Signature)).returns(Prompt) }
-    def self.from_signature(signature_class)
+    sig { params(signature_class: T.class_of(Signature), schema_format: Symbol).returns(Prompt) }
+    def self.from_signature(signature_class, schema_format: :json)
       new(
         instruction: signature_class.description || "Complete this task.",
         input_schema: signature_class.input_json_schema,
         output_schema: signature_class.output_json_schema,
         few_shot_examples: [],
-        signature_class_name: signature_class.name
+        signature_class_name: signature_class.name,
+        schema_format: schema_format,
+        signature_class: signature_class
       )
     end
 
@@ -221,6 +260,37 @@ module DSPy
 
     private
 
+    # Render BAML schema for input or output
+    sig { params(schema: T::Hash[Symbol, T.untyped], type: Symbol).returns(String) }
+    def render_baml_schema(schema, type)
+      # If we have a signature_class, use sorbet-baml's to_baml method with custom name
+      if @signature_class
+        begin
+          require 'sorbet_baml'
+
+          struct_class = type == :input ? @signature_class.input_struct_class : @signature_class.output_struct_class
+          if struct_class
+            # Generate a proper class name from signature class name
+            base_name = @signature_class_name || @signature_class.name || "Schema"
+            class_name = type == :input ? "#{base_name}Input" : "#{base_name}Output"
+
+            # Get raw BAML and replace the ugly class name
+            raw_baml = struct_class.to_baml
+            # Replace the class definition line with a proper name
+            return raw_baml.sub(/^class #<Class:0x[0-9a-f]+>/, "class #{class_name}")
+          end
+        rescue LoadError
+          # Fall back to manual BAML generation if sorbet_baml is not available
+        end
+      end
+
+      # Fallback: generate BAML manually from schema
+      # This is a simple implementation that handles basic types
+      # For production use, sorbet-baml should be available
+      "# BAML schema generation requires sorbet-baml gem\n" \
+      "# Please install: gem install sorbet-baml"
+    end
+
     # Recursively serialize complex objects for JSON representation
     sig { params(obj: T.untyped).returns(T.untyped) }
     def serialize_for_json(obj)

data/lib/dspy/propose/dataset_summary_generator.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require_relative '../signature'
+require_relative '../predict'
+
+module DSPy
+  module Propose
+    # Dataset Summary Generator for creating concise dataset descriptions
+    # Used by GroundedProposer for data-aware instruction generation
+    module DatasetSummaryGenerator
+      extend T::Sig
+
+      # Signature for summarizing observations into a brief summary
+      class ObservationSummarizer < DSPy::Signature
+        description "Given a series of observations I have made about my dataset, please summarize them into a brief 2-3 sentence summary which highlights only the most important details."
+
+        input do
+          const :observations, String, description: "Observations I have made about my dataset"
+        end
+
+        output do
+          const :summary, String, description: "Two to Three sentence summary of only the most significant highlights of my observations"
+        end
+      end
+
+      # Signature for generating initial dataset observations
+      class DatasetDescriptor < DSPy::Signature
+        description "Given several examples from a dataset please write observations about trends that hold for most or all of the samples. " \
+                   "Some areas you may consider in your observations: topics, content, syntax, conciceness, etc. " \
+                   "It will be useful to make an educated guess as to the nature of the task this dataset will enable. Don't be afraid to be creative"
+
+        input do
+          const :examples, String, description: "Sample data points from the dataset"
+        end
+
+        output do
+          const :observations, String, description: "Somethings that holds true for most or all of the data you observed"
+        end
+      end
+
+      # Signature for refining observations with prior context
+      class DatasetDescriptorWithPriorObservations < DSPy::Signature
+        description "Given several examples from a dataset please write observations about trends that hold for most or all of the samples. " \
+                   "I will also provide you with a few observations I have already made.  Please add your own observations or if you feel the observations are comprehensive say 'COMPLETE' " \
+                   "Some areas you may consider in your observations: topics, content, syntax, conciceness, etc. " \
+                   "It will be useful to make an educated guess as to the nature of the task this dataset will enable. Don't be afraid to be creative"
+
+        input do
+          const :examples, String, description: "Sample data points from the dataset"
+          const :prior_observations, String, description: "Some prior observations I made about the data"
+        end
+
+        output do
+          const :observations, String, description: "Somethings that holds true for most or all of the data you observed or COMPLETE if you have nothing to add"
+        end
+      end
+
+      # Helper function to ensure consistent ordering of input keys in string representations
+      # This helps with caching and consistent LLM prompts
+      sig { params(unordered_repr: String).returns(String) }
+      def self.order_input_keys_in_string(unordered_repr)
+        # Regex pattern to match the input keys structure
+        pattern = /input_keys=\{([^}]+)\}/
+
+        # Function to reorder keys
+        unordered_repr.gsub(pattern) do |match|
+          keys_str = Regexp.last_match(1)
+          # Split the keys, strip extra spaces, and sort them
+          keys = keys_str.split(',').map(&:strip).sort
+          # Format the sorted keys back into the expected structure
+          "input_keys={#{keys.join(', ')}}"
+        end
+      end
+
+      # Strip common prefixes from LLM outputs (e.g., "Answer:", "Output:")
+      sig { params(text: String).returns(String) }
+      def self.strip_prefix(text)
+        # Pattern matches up to 4 words followed by a colon
+        pattern = /^[\*\s]*(([\w'\-]+\s+){0,4}[\w'\-]+):\s*/
+        modified_text = text.gsub(pattern, '')
+        modified_text.strip.gsub(/^["']|["']$/, '')
+      end
+
+      # Generate a concise 2-3 sentence summary of a training dataset
+      # Used for data-aware instruction proposal in MIPROv2
+      #
+      # @param trainset [Array<DSPy::Example>] Training examples to summarize
+      # @param view_data_batch_size [Integer] Number of examples to process per batch
+      # @param prompt_model [DSPy::LM, nil] Language model to use (defaults to DSPy.lm)
+      # @param verbose [Boolean] Whether to print progress information
+      # @return [String] 2-3 sentence summary of the dataset characteristics
+      #
+      # @example Basic usage
+      #   summary = DatasetSummaryGenerator.create_dataset_summary(
+      #     trainset,
+      #     view_data_batch_size: 10,
+      #     prompt_model: DSPy::LM.new('gpt-4o-mini')
+      #   )
+      #
+      sig do
+        params(
+          trainset: T::Array[DSPy::Example],
+          view_data_batch_size: Integer,
+          prompt_model: T.nilable(DSPy::LM),
+          verbose: T::Boolean
+        ).returns(String)
+      end
+      def self.create_dataset_summary(trainset, view_data_batch_size, prompt_model, verbose: false)
+        if verbose
+          puts "\nBootstrapping dataset summary (this will be used to generate instructions)..."
+        end
+
+        # Use provided model or fall back to global LM
+        lm = prompt_model || DSPy.lm
+        raise ArgumentError, "No language model configured. Set prompt_model or DSPy.lm" unless lm
+
+        # Use provided LM in a block context
+        DSPy.with_lm(lm) do
+          # Initial observation from first batch
+          upper_lim = [trainset.length, view_data_batch_size].min
+          examples_repr = order_input_keys_in_string(trainset[0...upper_lim].inspect)
+
+          predictor = DSPy::Predict.new(DatasetDescriptor)
+          observation = predictor.call(examples: examples_repr)
+          observations = observation.observations
+
+          # Iteratively refine observations with additional batches
+          skips = 0
+          max_calls = 10
+          calls = 0
+
+          begin
+            (view_data_batch_size...trainset.length).step(view_data_batch_size) do |b|
+              calls += 1
+              break if calls >= max_calls
+
+              puts "Processing batch starting at index #{b}" if verbose
+
+              upper_lim = [trainset.length, b + view_data_batch_size].min
+              examples_repr = order_input_keys_in_string(trainset[b...upper_lim].inspect)
+
+              predictor = DSPy::Predict.new(DatasetDescriptorWithPriorObservations)
+              output = predictor.call(
+                prior_observations: observations,
+                examples: examples_repr
+              )
+
+              # Check if LLM indicates observations are complete
+              if output.observations.length >= 8 && output.observations[0...8].upcase == "COMPLETE"
+                skips += 1
+                break if skips >= 5
+                next
+              end
+
+              observations += output.observations
+            end
+          rescue => e
+            if verbose
+              puts "Error during observation refinement: #{e.message}. Using observations from past round for summary."
+            end
+          end
+
+          # Generate final summary from accumulated observations
+          predictor = DSPy::Predict.new(ObservationSummarizer)
+          summary = predictor.call(observations: observations)
+
+          if verbose
+            puts "\nGenerated summary: #{strip_prefix(summary.summary)}\n"
+          end
+
+          strip_prefix(summary.summary)
+        end
+      end
+    end
+  end
+end