dspy 0.28.2 → 0.29.0

data/lib/dspy/propose/grounded_proposer.rb

@@ -11,6 +11,8 @@ module DSPy
     class GroundedProposer
       extend T::Sig
 
+      MAX_HISTORY_INSTRUCTIONS = 5
+
       # Python-compatible TIPS dictionary for instruction generation
       TIPS = {
         "none" => "",
@@ -93,6 +95,9 @@ module DSPy
         sig { returns(T::Array[String]) }
         attr_reader :candidate_instructions
 
+        sig { returns(T::Hash[Integer, T::Array[String]]) }
+        attr_reader :predictor_instructions
+
         sig { returns(T::Hash[Symbol, T.untyped]) }
         attr_reader :analysis
 
@@ -103,11 +108,16 @@ module DSPy
           params(
             candidate_instructions: T::Array[String],
             analysis: T::Hash[Symbol, T.untyped],
-            metadata: T::Hash[Symbol, T.untyped]
+            metadata: T::Hash[Symbol, T.untyped],
+            predictor_instructions: T.nilable(T::Hash[Integer, T::Array[String]])
           ).void
         end
-        def initialize(candidate_instructions:, analysis:, metadata:)
+        def initialize(candidate_instructions:, analysis:, metadata:, predictor_instructions: nil)
           @candidate_instructions = candidate_instructions.freeze
+        normalized_predictor_instructions = (predictor_instructions || {}).each_with_object({}) do |(index, instructions), memo|
+            memo[index] = instructions.dup.freeze
+          end
+          @predictor_instructions = normalized_predictor_instructions.freeze
           @analysis = analysis.freeze
           @metadata = metadata.freeze
         end
@@ -192,10 +202,11 @@ module DSPy
           signature_class: T.class_of(DSPy::Signature),
           examples: T::Array[T.untyped],
           few_shot_examples: T.nilable(T::Array[T.untyped]),
-          current_instruction: T.nilable(String)
+          current_instruction: T.nilable(String),
+          trial_logs: T.nilable(T::Hash[Integer, T::Hash[Symbol, T.untyped]])
         ).returns(ProposalResult)
       end
-      def propose_instructions(signature_class, examples, few_shot_examples: nil, current_instruction: nil)
+      def propose_instructions(signature_class, examples, few_shot_examples: nil, current_instruction: nil, trial_logs: nil)
         DSPy::Context.with_span(
           operation: 'optimization.instruction_proposal',
           'dspy.module' => 'GroundedProposer',
@@ -212,7 +223,8 @@ module DSPy
             signature_class,
             analysis,
             current_instruction,
-            few_shot_examples: few_shot_examples
+            few_shot_examples: few_shot_examples,
+            trial_logs: trial_logs
           )
 
           # Filter and rank candidates
@@ -236,6 +248,50 @@ module DSPy
         end
       end
 
+      sig do
+        params(
+          trainset: T::Array[T.untyped],
+          program: T.untyped,
+          demo_candidates: T::Hash[Integer, T::Array[T::Array[DSPy::FewShotExample]]],
+          trial_logs: T.nilable(T::Hash[Integer, T::Hash[Symbol, T.untyped]]),
+          num_instruction_candidates: T.nilable(Integer)
+        ).returns(ProposalResult)
+      end
+      def propose_instructions_for_program(trainset:, program:, demo_candidates:, trial_logs: nil, num_instruction_candidates: nil)
+        num_candidates = num_instruction_candidates || @config.num_instruction_candidates
+
+        current_instruction = if program.respond_to?(:prompt) && program.prompt.respond_to?(:instruction)
+          program.prompt.instruction
+        else
+          nil
+        end
+
+        few_shot_examples = demo_candidates[0]&.flatten&.take(@config.num_demos_in_context) || []
+
+        signature_class = if program.respond_to?(:signature_class)
+          program.signature_class
+        else
+          raise ArgumentError, "Program must expose signature_class for instruction proposal"
+        end
+
+        base_result = propose_instructions(
+          signature_class,
+          trainset,
+          few_shot_examples: few_shot_examples,
+          current_instruction: current_instruction,
+          trial_logs: trial_logs
+        )
+
+        predictor_instructions = { 0 => base_result.candidate_instructions.take(num_candidates) }
+
+        ProposalResult.new(
+          candidate_instructions: base_result.candidate_instructions,
+          analysis: base_result.analysis,
+          metadata: base_result.metadata,
+          predictor_instructions: predictor_instructions
+        )
+      end
+
       private
 
       # Analyze the task based on signature and training examples
@@ -418,16 +474,18 @@ module DSPy
           signature_class: T.class_of(DSPy::Signature),
           analysis: T::Hash[Symbol, T.untyped],
           current_instruction: T.nilable(String),
-          few_shot_examples: T.nilable(T::Array[T.untyped])
+          few_shot_examples: T.nilable(T::Array[T.untyped]),
+          trial_logs: T.nilable(T::Hash[Integer, T::Hash[Symbol, T.untyped]])
         ).returns(T::Array[String])
       end
-      def generate_instruction_candidates(signature_class, analysis, current_instruction, few_shot_examples: nil)
+      def generate_instruction_candidates(signature_class, analysis, current_instruction, few_shot_examples: nil, trial_logs: nil)
         # Build context for instruction generation
         context = build_generation_context(
           signature_class,
           analysis,
           current_instruction,
-          few_shot_examples: few_shot_examples
+          few_shot_examples: few_shot_examples,
+          trial_logs: trial_logs
         )
         
         # Create instruction generation signature
@@ -467,10 +525,11 @@ module DSPy
           signature_class: T.class_of(DSPy::Signature),
           analysis: T::Hash[Symbol, T.untyped],
           current_instruction: T.nilable(String),
-          few_shot_examples: T.nilable(T::Array[T.untyped])
+          few_shot_examples: T.nilable(T::Array[T.untyped]),
+          trial_logs: T.nilable(T::Hash[Integer, T::Hash[Symbol, T.untyped]])
         ).returns(String)
       end
-      def build_generation_context(signature_class, analysis, current_instruction, few_shot_examples: nil)
+      def build_generation_context(signature_class, analysis, current_instruction, few_shot_examples: nil, trial_logs: nil)
         context_parts = []
 
         # Include dataset summary if enabled and available
@@ -515,6 +574,13 @@ module DSPy
           context_parts << "Tip: #{tip}" if tip && !tip.empty?
         end
 
+        if @config.use_instruct_history
+          history_summary = build_instruction_history_summary(trial_logs, predictor_index: 0, top_n: MAX_HISTORY_INSTRUCTIONS)
+          unless history_summary.empty?
+            context_parts << "Previous instructions:\n#{history_summary}"
+          end
+        end
+
         context_parts.join("\n\n")
       end
 
@@ -565,6 +631,47 @@ module DSPy
         end
       end
 
+      sig do
+        params(
+          trial_logs: T.nilable(T::Hash[Integer, T::Hash[Symbol, T.untyped]]),
+          predictor_index: Integer,
+          top_n: Integer
+        ).returns(String)
+      end
+      def build_instruction_history_summary(trial_logs, predictor_index:, top_n:)
+        return "" unless @config.use_instruct_history
+
+        logs = trial_logs || {}
+        aggregate = Hash.new { |hash, key| hash[key] = { total: 0.0, count: 0 } }
+
+        logs.each_value do |entry|
+          score = entry[:score]
+          next unless score.respond_to?(:to_f)
+
+          instructions = entry[:instructions]
+          instruction = nil
+          if instructions.respond_to?(:[])
+            instruction = instructions[predictor_index] || instructions[:default]
+          end
+          instruction ||= entry[:instruction]
+
+          next unless instruction.is_a?(String) && !instruction.empty?
+
+          aggregate[instruction][:total] += score.to_f
+          aggregate[instruction][:count] += 1
+        end
+
+        return "" if aggregate.empty?
+
+        ranked = aggregate.map do |instruction, stats|
+          average = stats[:total] / stats[:count]
+          [instruction, average]
+        end
+
+        top_entries = ranked.sort_by { |(_, avg)| -avg }.take(top_n).reverse
+        top_entries.map { |instruction, avg| format("%s | Score: %.4f", instruction, avg) }.join("\n\n")
+      end
+
       # Build requirements text for instruction generation
       sig { params(analysis: T::Hash[Symbol, T.untyped]).returns(String) }
       def build_requirements_text(analysis)
@@ -740,4 +847,4 @@ module DSPy
       end
     end
   end
-end
+end

data/lib/dspy/re_act.rb

@@ -144,6 +144,19 @@ module DSPy
       super(enhanced_signature)
     end
 
+    sig { override.returns(T::Array[[String, DSPy::Module]]) }
+    def named_predictors
+      pairs = T.let([], T::Array[[String, DSPy::Module]])
+      pairs << ["thought_generator", @thought_generator]
+      pairs << ["observation_processor", @observation_processor]
+      pairs
+    end
+
+    sig { override.returns(T::Array[DSPy::Module]) }
+    def predictors
+      named_predictors.map { |(_, predictor)| predictor }
+    end
+
     sig { params(kwargs: T.untyped).returns(T.untyped).override }
     def forward(**kwargs)
       # Validate input

data/lib/dspy/reflection_lm.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module DSPy
+  # Lightweight wrapper for running reflection prompts without structured outputs.
+  class ReflectionLM
+    extend T::Sig
+
+    sig do
+      params(
+        model_id: String,
+        api_key: T.nilable(String),
+        options: T.untyped
+      ).void
+    end
+    def initialize(model_id, api_key: nil, **options)
+      opts = options.each_with_object({}) do |(key, value), memo|
+        memo[key.to_sym] = value
+      end
+      opts[:api_key] = api_key if api_key
+      @lm = DSPy::LM.new(model_id, structured_outputs: false, schema_format: :json, **opts)
+    end
+
+    sig { params(prompt: String).returns(String) }
+    def call(prompt)
+      response = @lm.raw_chat([{ role: 'user', content: prompt }])
+      response.respond_to?(:content) ? response.content : response.to_s
+    end
+
+    sig { params(messages: T.nilable(T::Array[T::Hash[Symbol, String]]), block: T.nilable(T.proc.params(arg0: T.untyped).void)).returns(T.untyped) }
+    def raw_chat(messages = nil, &block)
+      @lm.raw_chat(messages, &block)
+    end
+  end
+end