dspy 0.34.2 → 0.34.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fe4cbffffd520f31219caa7dbce4b75ef39684cdd5e422b60144aa3ae3329e9
-  data.tar.gz: '0974465586686c0b93292b464f9b49abcb10a265ca85295c65584e989a271d7f'
+  metadata.gz: 5d5296e0130d0550156345659e6703451bd6ca6fb9ffbac33d8584ee203f2a84
+  data.tar.gz: 339772eb768a2babbb8b700b868fc772183473b7cf4f8a6867e55945f75a3655
 SHA512:
-  metadata.gz: 5602b8a59a8454306921a2528ccb58824cfe3878a4d31f3b8b4b93d94730c6f2e804c439a9fd1f7bb44a2afe6aff6cb3843e1d7ad6f45c51e4e01aec7d44db5c
-  data.tar.gz: 4bf2656ade52cbf55e6416a061e9107c9332a0e669b9bafe07acf045aac605eaa38410ae433268b78a7d285b47450e03e8416e9a456d978e258177fce00a90e9
+  metadata.gz: 827360cba1ad8d03373d40d9b1b9ce3acf966e896261b918537150568cf4635904e591c238cdea7d8e8bf45980851ce3c581f709639215c8d7e4c7e1ea78dc08
+  data.tar.gz: e8d91df3e7204ac0d0db830c5839a4cbdd9683a00be2a77dec38de156052f0a0b3956e25c8b7026fcce23880e9806fc9af023fc2a4fe830926f288f82474a85b

data/README.md

@@ -137,26 +137,18 @@ result.answer     # => "60 km/h"
 Build agents that use tools to accomplish tasks:
 
 ```ruby
-class SearchTool < DSPy::Tools::Tool
+class SearchTool < DSPy::Tools::Base
   tool_name "search"
-  description "Search for information"
-
-  input do
-    const :query, String
-  end
-
-  output do
-    const :results, T::Array[String]
-  end
+  tool_description "Search for information"
 
+  sig { params(query: String).returns(String) }
   def call(query:)
     # Your search implementation
-    { results: ["Result 1", "Result 2"] }
+    "Result 1, Result 2"
   end
 end
 
-toolset = DSPy::Tools::Toolset.new(tools: [SearchTool.new])
-agent = DSPy::ReAct.new(signature: ResearchTask, tools: toolset, max_iterations: 5)
+agent = DSPy::ReAct.new(ResearchTask, tools: [SearchTool.new], max_iterations: 5)
 result = agent.call(question: "What's the latest on Ruby 3.4?")
 ```
 
@@ -185,8 +177,8 @@ result = agent.call(question: "What's the latest on Ruby 3.4?")
 A [Claude Skill](https://github.com/vicentereig/dspy-rb-skill) is available to help you build DSPy.rb applications:
 
 ```bash
-# Claude Code
-git clone https://github.com/vicentereig/dspy-rb-skill ~/.claude/skills/dspy-rb
+# Claude Code — install from the vicentereig/engineering marketplace
+claude install-skill vicentereig/engineering --skill dspy-rb
 ```
 
 For Claude.ai Pro/Max, download the [skill ZIP](https://github.com/vicentereig/dspy-rb-skill/archive/refs/heads/main.zip) and upload via Settings > Skills.
@@ -201,7 +193,7 @@ The [examples/](examples/) directory has runnable code for common patterns:
 - Prompt optimization
 
 ```bash
-bundle exec ruby examples/first_predictor.rb
+bundle exec ruby examples/basic_search_agent.rb
 ```
 
 ## Optional Gems

data/lib/dspy/chain_of_thought.rb

@@ -47,7 +47,8 @@ module DSPy
         output_schema: @signature_class.output_json_schema,
         few_shot_examples: new_prompt.few_shot_examples,
         signature_class_name: @signature_class.name,
-        schema_format: new_prompt.schema_format
+        schema_format: new_prompt.schema_format,
+        data_format: new_prompt.data_format
       )
       
       instance.instance_variable_set(:@prompt, enhanced_prompt)
@@ -93,7 +94,7 @@ module DSPy
       
       # Create a temporary Predict instance with our enhanced signature to get the prediction
       predict_instance = DSPy::Predict.new(@signature_class)
-      predict_instance.config.lm = self.lm  # Use the same LM configuration
+      predict_instance.configure { |c| c.lm = self.lm }  # Use the same LM configuration
       
       # Call predict's forward method, which will create the Predict span
       prediction_result = predict_instance.forward(**input_values)

data/lib/dspy/context.rb

@@ -31,6 +31,18 @@ module DSPy
         context
       end
 
+      def with_request(request_id, start_time)
+        previous_request_id = current[:request_id]
+        previous_start_time = current[:request_start_time]
+
+        current[:request_id] = request_id
+        current[:request_start_time] = start_time
+        yield
+      ensure
+        current[:request_id] = previous_request_id
+        current[:request_start_time] = previous_start_time
+      end
+
       def fork_context(parent_context)
         clone_context(parent_context)
       end
@@ -62,8 +74,9 @@ module DSPy
             # Prepare attributes and add trace name for root spans
             span_attributes = sanitized_attributes.transform_keys(&:to_s).reject { |k, v| v.nil? }
             
-            # Set trace name if this is likely a root span (no parent in our stack)
-            if current[:span_stack].length == 1  # This will be the first span
+            # Set trace name if this is likely a root span (no parent in our stack),
+            # unless callers already specified one explicitly.
+            if current[:span_stack].length == 1 && !span_attributes.key?('langfuse.trace.name')
               span_attributes['langfuse.trace.name'] = operation
             end
             
@@ -72,6 +85,12 @@ module DSPy
             
             # Get parent OpenTelemetry span for proper context propagation
             parent_otel_span = current[:otel_span_stack].last
+            if !parent_otel_span && defined?(OpenTelemetry::Trace)
+              current_span = OpenTelemetry::Trace.current_span
+              if current_span && current_span != OpenTelemetry::Trace::Span::INVALID
+                parent_otel_span = current_span
+              end
+            end
             
             # Create span with proper parent context
             if parent_otel_span
@@ -84,20 +103,18 @@ module DSPy
                 ) do |span|
                   # Add to our OpenTelemetry span stack
                   current[:otel_span_stack].push(span)
+                  succeeded = false
                   
                   begin
                     result = yield(span)
-                    
-                    # Add explicit timing information to help Langfuse
-                    if span
-                      duration_ms = ((Time.now - otel_start_time) * 1000).round(3)
-                      span.set_attribute('duration.ms', duration_ms)
-                      span.set_attribute('langfuse.observation.startTime', otel_start_time.iso8601(3))
-                      span.set_attribute('langfuse.observation.endTime', Time.now.iso8601(3))
-                    end
-                    
+                    succeeded = true
                     result
+                  rescue StandardError => e
+                    set_span_error_attributes(span, e)
+                    raise
                   ensure
+                    set_span_status_attribute(span, succeeded)
+                    set_span_timing_attributes(span, otel_start_time)
                     # Remove from our OpenTelemetry span stack
                     current[:otel_span_stack].pop
                   end
@@ -112,20 +129,18 @@ module DSPy
               ) do |span|
                 # Add to our OpenTelemetry span stack
                 current[:otel_span_stack].push(span)
+                succeeded = false
                 
                 begin
                   result = yield(span)
-                  
-                  # Add explicit timing information to help Langfuse
-                  if span
-                    duration_ms = ((Time.now - otel_start_time) * 1000).round(3)
-                    span.set_attribute('duration.ms', duration_ms)
-                    span.set_attribute('langfuse.observation.startTime', otel_start_time.iso8601(3))
-                    span.set_attribute('langfuse.observation.endTime', Time.now.iso8601(3))
-                  end
-                  
+                  succeeded = true
                   result
+                rescue StandardError => e
+                  set_span_error_attributes(span, e)
+                  raise
                 ensure
+                  set_span_status_attribute(span, succeeded)
+                  set_span_timing_attributes(span, otel_start_time)
                   # Remove from our OpenTelemetry span stack
                   current[:otel_span_stack].pop
                 end
@@ -216,7 +231,9 @@ module DSPy
           fiber_id: Fiber.current.object_id,
           span_stack: [],
           otel_span_stack: [],
-          module_stack: []
+          module_stack: [],
+          request_id: nil,
+          request_start_time: nil
         }
       end
 
@@ -227,6 +244,8 @@ module DSPy
         cloned[:module_stack] = Array(context[:module_stack]).map { |entry| entry.dup }
         cloned[:thread_id] = Thread.current.object_id
         cloned[:fiber_id] = Fiber.current.object_id
+        cloned[:request_id] = context[:request_id]
+        cloned[:request_start_time] = context[:request_start_time]
         cloned
       end
 
@@ -280,6 +299,36 @@ module DSPy
           label: explicit_label || (module_instance.respond_to?(:module_scope_label) ? module_instance.module_scope_label : nil)
         }
       end
+
+      def set_span_timing_attributes(span, otel_start_time)
+        return unless span
+
+        now = Time.now
+        duration_ms = ((now - otel_start_time) * 1000).round(3)
+        span.set_attribute('duration.ms', duration_ms)
+        span.set_attribute('langfuse.observation.startTime', otel_start_time.iso8601(3))
+        span.set_attribute('langfuse.observation.endTime', now.iso8601(3))
+      rescue StandardError
+        nil
+      end
+
+      def set_span_error_attributes(span, error)
+        return unless span
+
+        span.set_attribute('error', true)
+        span.set_attribute('error.type', error.class.name)
+        span.set_attribute('error.message', error.message.to_s[0, 2000]) if error.message
+      rescue StandardError
+        nil
+      end
+
+      def set_span_status_attribute(span, succeeded)
+        return unless span
+
+        span.set_attribute('dspy.status', succeeded ? 'completed' : 'error')
+      rescue StandardError
+        nil
+      end
     end
   end
 end

data/lib/dspy/evals/version.rb

@@ -2,6 +2,6 @@
 
 module DSPy
   class Evals
-    VERSION = '1.0.1'
+    VERSION = '1.0.2'
   end
 end

data/lib/dspy/evals.rb

@@ -254,25 +254,7 @@ module DSPy
     # Evaluate program on a single example
     sig { params(example: T.untyped, trace: T.nilable(T.untyped)).returns(EvaluationResult) }
     def call(example, trace: nil)
-      run_callbacks(:before, :call, example: example)
-
-      DSPy::Context.with_span(
-        operation: 'evaluation.example',
-        'dspy.module' => 'Evaluator',
-        'evaluation.program' => @program.class.name,
-        'evaluation.has_metric' => !@metric.nil?
-      ) do
-        begin
-          perform_call(example, trace: trace)
-        rescue => e
-          build_error_result(example, e, trace: trace)
-        end
-      end.then do |result|
-        @last_example_result = result
-        emit_example_observation(example, result)
-        run_callbacks(:after, :call, example: example, result: result)
-        result
-      end
+      call_with_program(@program, example, trace: trace, track_state: true)
     end
 
     # Evaluate program on multiple examples
@@ -403,8 +385,9 @@ module DSPy
 
         futures = batch.map do |item|
           Concurrent::Promises.future_on(executor) do
-            [:ok, item[:index], safe_call(item[:example])]
-          rescue => e
+            program_for_thread = fork_program_for_thread
+            [:ok, item[:index], safe_call(item[:example], program: program_for_thread, track_state: false)]
+          rescue StandardError => e
             [:error, item[:index], e]
           end
         end
@@ -441,18 +424,18 @@ module DSPy
       results.compact
     end
 
-    def safe_call(example)
-      call(example)
-    rescue => e
+    def safe_call(example, program: @program, track_state: true)
+      call_with_program(program, example, track_state: track_state)
+    rescue StandardError => e
       build_error_result(example, e)
     end
 
-    def perform_call(example, trace:)
+    def perform_call(example, trace:, program:)
       # Extract input from example - support both hash and object formats
       input_values = extract_input_values(example)
 
       # Run prediction
-      prediction = @program.call(**input_values)
+      prediction = program.call(**input_values)
 
       # Calculate metrics if provided
       metrics = {}
@@ -469,7 +452,7 @@ module DSPy
             passed = !!metric_result
             metrics[:passed] = passed
           end
-        rescue => e
+        rescue StandardError => e
           passed = false
           metrics[:error] = e.message
           metrics[:passed] = false
@@ -490,6 +473,34 @@ module DSPy
       )
     end
 
+    def call_with_program(program, example, trace: nil, track_state: true)
+      run_callbacks(:before, :call, example: example)
+
+      DSPy::Context.with_span(
+        operation: 'evaluation.example',
+        'dspy.module' => 'Evaluator',
+        'evaluation.program' => program.class.name,
+        'evaluation.has_metric' => !@metric.nil?
+      ) do
+        begin
+          perform_call(example, trace: trace, program: program)
+        rescue StandardError => e
+          build_error_result(example, e, trace: trace)
+        end
+      end.then do |result|
+        @last_example_result = result if track_state
+        emit_example_observation(example, result)
+        run_callbacks(:after, :call, example: example, result: result)
+        result
+      end
+    end
+
+    def fork_program_for_thread
+      return @program if @program.nil?
+      return @program.dup_for_thread if @program.respond_to?(:dup_for_thread)
+      @program.dup
+    end
+
     def build_error_result(example, error, trace: nil)
       metrics = {
         error: error.message,
@@ -680,7 +691,7 @@ module DSPy
       if @export_scores
         export_example_score(example, result)
       end
-    rescue => e
+    rescue StandardError => e
       DSPy.log('evals.example.observation_error', error: e.message)
     end
 
@@ -698,7 +709,7 @@ module DSPy
       if @export_scores
         export_batch_score(batch_result)
       end
-    rescue => e
+    rescue StandardError => e
       DSPy.log('evals.batch.observation_error', error: e.message)
     end
 
@@ -711,7 +722,7 @@ module DSPy
         score_value,
         comment: "Example: #{example_id || 'unknown'}, passed: #{result.passed}"
       )
-    rescue => e
+    rescue StandardError => e
       DSPy.log('evals.score_export_error', error: e.message)
     end
 
@@ -721,7 +732,7 @@ module DSPy
         batch_result.pass_rate,
         comment: "Batch: #{batch_result.passed_examples}/#{batch_result.total_examples} passed"
       )
-    rescue => e
+    rescue StandardError => e
       DSPy.log('evals.batch_score_export_error', error: e.message)
     end
 

data/lib/dspy/events.rb

@@ -11,7 +11,6 @@ module DSPy
   class EventRegistry
     def initialize
       @listeners = {}
-      @subscription_counter = 0
       @mutex = Mutex.new
     end
 
@@ -53,7 +52,7 @@ module DSPy
       matching_listeners.each do |id, listener|
         begin
           listener[:block].call(event_name, attributes)
-        rescue => e
+        rescue StandardError => e
           # Log the error but continue processing other listeners
           # Use emit_log directly to avoid infinite recursion
           DSPy.send(:emit_log, 'event.listener.error', {
@@ -80,4 +79,4 @@ module DSPy
       end
     end
   end
-end
+end

data/lib/dspy/example.rb

@@ -178,7 +178,7 @@ module DSPy
             id: example_data[:id] || "example_#{index}"
           )
           examples << example
-        rescue => e
+        rescue StandardError => e
           errors << "Example #{index}: #{e.message}"
         end
       end

data/lib/dspy/lm/adapter.rb

@@ -57,6 +57,45 @@ module DSPy
           content.is_a?(Array) && content.any? { |item| item[:type] == 'image' }
         end
       end
+
+      # Format multimodal messages for a specific provider
+      # @param messages [Array<Hash>] Array of message hashes
+      # @param provider_name [String] Provider name for image validation and formatting
+      # @return [Array<Hash>] Messages with images formatted for the provider
+      def format_multimodal_messages(messages, provider_name)
+        messages.map do |msg|
+          if msg[:content].is_a?(Array)
+            formatted_content = msg[:content].map do |item|
+              case item[:type]
+              when 'text'
+                { type: 'text', text: item[:text] }
+              when 'image'
+                format_image_for_provider(item[:image], provider_name)
+              else
+                item
+              end
+            end
+            { role: msg[:role], content: formatted_content }
+          else
+            msg
+          end
+        end
+      end
+
+      # Format an image for a specific provider
+      # @param image [DSPy::Image] The image to format
+      # @param provider_name [String] Provider name (openai, anthropic, gemini, etc.)
+      # @return [Hash] Provider-specific image format
+      def format_image_for_provider(image, provider_name)
+        image.validate_for_provider!(provider_name)
+        format_method = "to_#{provider_name}_format"
+        if image.respond_to?(format_method)
+          image.send(format_method)
+        else
+          # For providers without specific format methods, return the item as-is
+          { type: 'image', image: image }
+        end
+      end
     end
   end
 end

data/lib/dspy/lm/json_strategy.rb

@@ -38,17 +38,8 @@ module DSPy
           # OpenAI/Ollama: try to extract JSON from various formats
           extract_json_from_content(response.content)
         elsif adapter_class_name.include?('AnthropicAdapter')
-          # Anthropic: try tool use first if structured_outputs enabled, else use content extraction
-          structured_outputs_enabled = adapter.instance_variable_get(:@structured_outputs_enabled)
-          structured_outputs_enabled = true if structured_outputs_enabled.nil?  # Default to true
-
-          if structured_outputs_enabled
-            extracted = extract_anthropic_tool_json(response)
-            extracted || extract_json_from_content(response.content)
-          else
-            # Skip tool extraction, use enhanced prompting extraction
-            extract_json_from_content(response.content)
-          end
+          # Anthropic: Beta API returns JSON in content, same as OpenAI/Gemini
+          extract_json_from_content(response.content)
         elsif adapter_class_name.include?('GeminiAdapter')
           # Gemini: try to extract JSON from various formats
           extract_json_from_content(response.content)
@@ -90,25 +81,30 @@ module DSPy
       # Anthropic preparation
       sig { params(messages: T::Array[T::Hash[Symbol, T.untyped]], request_params: T::Hash[Symbol, T.untyped]).void }
       def prepare_anthropic_request(messages, request_params)
-        # Only use tool-based extraction if structured_outputs is enabled (default: true)
-        structured_outputs_enabled = adapter.instance_variable_get(:@structured_outputs_enabled)
+        begin
+          require "dspy/anthropic/lm/schema_converter"
+        rescue LoadError
+          msg = <<~MSG
+            Anthropic adapter is optional; structured output helpers will be unavailable until the gem is installed.
+            Add `gem 'dspy-anthropic'` to your Gemfile and run `bundle install`.
+          MSG
+          raise DSPy::LM::MissingAdapterError, msg
+        end
 
-        # Default to true if not set (backward compatibility)
+        # Only use Beta API structured outputs if enabled (default: true)
+        structured_outputs_enabled = adapter.instance_variable_get(:@structured_outputs_enabled)
         structured_outputs_enabled = true if structured_outputs_enabled.nil?
 
         return unless structured_outputs_enabled
 
-        # Convert signature to tool schema
-        tool_schema = convert_to_anthropic_tool_schema
+        # Use Anthropic Beta API structured outputs
+        schema = DSPy::Anthropic::LM::SchemaConverter.to_beta_format(signature_class)
 
-        # Add tool definition
-        request_params[:tools] = [tool_schema]
-
-        # Force tool use
-        request_params[:tool_choice] = {
-          type: "tool",
-          name: "json_output"
-        }
+        request_params[:output_format] = ::Anthropic::Models::Beta::BetaJSONOutputFormat.new(
+          type: :json_schema,
+          schema: schema
+        )
+        request_params[:betas] = ["structured-outputs-2025-11-13"]
       end
 
       # Gemini preparation
@@ -135,54 +131,19 @@ module DSPy
         end
       end
 
-      # Convert signature to Anthropic tool schema
-      sig { returns(T::Hash[Symbol, T.untyped]) }
-      def convert_to_anthropic_tool_schema
-        output_fields = signature_class.output_field_descriptors
-
-        {
-          name: "json_output",
-          description: "Output the result in the required JSON format",
-          input_schema: {
-            type: "object",
-            properties: build_properties_from_fields(output_fields),
-            required: output_fields.keys.map(&:to_s)
-          }
-        }
-      end
-
-      # Build JSON schema properties from output fields
-      sig { params(fields: T::Hash[Symbol, T.untyped]).returns(T::Hash[String, T.untyped]) }
-      def build_properties_from_fields(fields)
-        properties = {}
-        fields.each do |field_name, descriptor|
-          properties[field_name.to_s] = DSPy::TypeSystem::SorbetJsonSchema.type_to_json_schema(descriptor.type)
-        end
-        properties
-      end
-
-      # Extract JSON from Anthropic tool use response
-      sig { params(response: DSPy::LM::Response).returns(T.nilable(String)) }
-      def extract_anthropic_tool_json(response)
-        # Check for tool calls in metadata
-        if response.metadata.respond_to?(:tool_calls) && response.metadata.tool_calls
-          tool_calls = response.metadata.tool_calls
-          if tool_calls.is_a?(Array) && !tool_calls.empty?
-            first_call = tool_calls.first
-            if first_call[:name] == "json_output" && first_call[:input]
-              return JSON.generate(first_call[:input])
-            end
-          end
-        end
-
-        nil
-      end
-
       # Extract JSON from content that may contain markdown or plain JSON
       sig { params(content: String).returns(String) }
       def extract_json_from_content(content)
         return content if content.nil? || content.empty?
 
+        # Fix Anthropic Beta API bug with optional fields producing invalid JSON
+        # When some output fields are optional and not returned, Anthropic's structured outputs
+        # can produce trailing comma+brace: {"field1": {...},} instead of {"field1": {...}}
+        # This workaround removes the invalid trailing syntax before JSON parsing
+        if content =~ /,\s*\}\s*$/
+          content = content.sub(/,(\s*\}\s*)$/, '\1')
+        end
+
         # Try 1: Check for ```json code block (with or without preceding text)
         if content.include?('```json')
           json_match = content.match(/```json\s*\n(.*?)\n```/m)

data/lib/dspy/lm/message.rb

@@ -154,7 +154,7 @@ module DSPy
           content: formatted_content,
           name: data[:name]&.to_s
         )
-      rescue => e
+      rescue StandardError => e
         DSPy.logger.debug("Failed to create Message: #{e.message}")
         nil
       end

data/lib/dspy/lm/response.rb

@@ -118,7 +118,7 @@ module DSPy
       extend T::Sig
       
       const :content, String
-      const :usage, T.nilable(T.any(Usage, OpenAIUsage)), default: nil
+      const :usage, T.nilable(T.any(Usage, OpenAIUsage, AnthropicUsage)), default: nil
       const :metadata, T.any(ResponseMetadata, OpenAIResponseMetadata, AnthropicResponseMetadata, GeminiResponseMetadata, T::Hash[Symbol, T.untyped])
       
       sig { returns(String) }
@@ -182,7 +182,7 @@ module DSPy
         else
           ResponseMetadata.new(**common_fields)
         end
-      rescue => e
+      rescue StandardError => e
         DSPy.logger.debug("Failed to create response metadata: #{e.message}")
         # Fallback to basic metadata
         ResponseMetadata.new(