dspy 0.34.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01f38786c88d525a1031cf41931f578c3d2dcbfa29ee6a8dac1a381cafe47edf
-  data.tar.gz: 6334bfb483b3011fa91e163f688127be763a126ea7cd0edc44f07b0557dc2a30
+  metadata.gz: 85ae2299dbddc20bfd710c68e9e8dfbeeb201b742e3fd18b768669ddc4443261
+  data.tar.gz: ba0ee2d5f637f499448e456fb58f0513aa58b5b258e754bf1b32839ea8c49b63
 SHA512:
-  metadata.gz: 744087dd87e936b247d194539407f2a74b29d5e6a28b4ba872c4aa0ef77103c4a6957c97b6bed3ee7e8ef899824f3e6e0f40c2b429c47312aa10924bb1fbca3c
-  data.tar.gz: 4e343687e84570d199ce9c7695d19d0a0a551cac66693fda131fe03268d3907e2d20f4648530d1e6a5de0a73092b03f3ec7bcec877d9c23662332193aaee0e31
+  metadata.gz: 310de5ce11b23d29bd168069eae4f5ce3ac154ba91974c96b9d70e5d02a0dcb45122dc4c83f80097a409ff448a0a30d45ebec3ff0883d80b2cdd8f1215d2dfff
+  data.tar.gz: 1ce5ff1bfe900bcedabab28efba1e8352fed81c6cbf458d5b7c54e8f7eea29fa6b7ee33a62dcc73b456ede6181a85bbf055541e4fb70037ac4de05e3be2b8ce9

data/README.md

@@ -9,6 +9,7 @@
 **Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
 
 DSPy.rb is the Ruby port of Stanford's [DSPy](https://dspy.ai). Instead of wrestling with brittle prompt strings, you define typed signatures and let the framework handle the rest. Prompts become functions. LLM calls become predictable.
+The `1.x` line is the stable release track for production Ruby LLM applications.
 
 ```ruby
 require 'dspy'
@@ -137,26 +138,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 +178,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 +194,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/context.rb

@@ -74,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
             
@@ -84,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
@@ -96,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
@@ -124,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
@@ -296,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/document.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'stringio'
+require 'uri'
+
+module DSPy
+  class Document
+    class RubyLLMInlineAttachment < StringIO
+      attr_reader :path
+
+      def initialize(content, path:)
+        super(content)
+        @path = path
+        binmode
+      end
+    end
+
+    private_constant :RubyLLMInlineAttachment
+
+    attr_reader :url, :base64, :data, :content_type
+
+    SUPPORTED_FORMATS = %w[application/pdf].freeze
+    MAX_SIZE_BYTES = 32 * 1024 * 1024 # 32MB limit
+
+    def initialize(url: nil, base64: nil, data: nil, content_type: nil)
+      validate_input!(url, base64, data)
+
+      if url
+        @url = url
+        @content_type = content_type || infer_content_type_from_url(url)
+      elsif base64
+        raise ArgumentError, "content_type is required when using base64" unless content_type
+
+        @base64 = base64
+        @content_type = content_type
+        validate_size!(Base64.decode64(base64).bytesize)
+      elsif data
+        raise ArgumentError, "content_type is required when using data" unless content_type
+
+        @data = data
+        @content_type = content_type
+        validate_size!(data.size)
+      end
+
+      validate_content_type!
+    end
+
+    def to_openai_format
+      raise DSPy::LM::IncompatibleDocumentFeatureError,
+            "OpenAI document inputs are not supported in this release. Use Anthropic directly or Anthropic via RubyLLM."
+    end
+
+    def to_anthropic_format
+      if url
+        {
+          type: 'document',
+          source: {
+            type: 'url',
+            url: url
+          }
+        }
+      else
+        {
+          type: 'document',
+          source: {
+            type: 'base64',
+            media_type: content_type,
+            data: to_base64
+          }
+        }
+      end
+    end
+
+    def to_gemini_format
+      raise DSPy::LM::IncompatibleDocumentFeatureError,
+            "Gemini document inputs are not supported in this release. Use Anthropic directly or Anthropic via RubyLLM."
+    end
+
+    def to_ruby_llm_attachment
+      if url
+        url
+      else
+        RubyLLMInlineAttachment.new(to_binary, path: 'document.pdf')
+      end
+    end
+
+    def to_base64
+      return base64 if base64
+      return Base64.strict_encode64(data.pack('C*')) if data
+
+      nil
+    end
+
+    def validate_for_provider!(provider)
+      case provider
+      when 'anthropic'
+        true
+      when 'openai'
+        raise DSPy::LM::IncompatibleDocumentFeatureError,
+              "OpenAI document inputs are not supported in this release. Use Anthropic directly or Anthropic via RubyLLM."
+      when 'gemini'
+        raise DSPy::LM::IncompatibleDocumentFeatureError,
+              "Gemini document inputs are not supported in this release. Use Anthropic directly or Anthropic via RubyLLM."
+      else
+        raise DSPy::LM::IncompatibleDocumentFeatureError,
+              "Unknown provider '#{provider}'. Document inputs are currently supported only for Anthropic."
+      end
+    end
+
+    private
+
+    def validate_input!(url, base64, data)
+      inputs = [url, base64, data].compact
+
+      if inputs.empty?
+        raise ArgumentError, "Must provide either url, base64, or data"
+      elsif inputs.size > 1
+        raise ArgumentError, "Only one of url, base64, or data can be provided"
+      end
+    end
+
+    def validate_content_type!
+      unless SUPPORTED_FORMATS.include?(content_type)
+        raise ArgumentError, "Unsupported document format: #{content_type}. Supported formats: #{SUPPORTED_FORMATS.join(', ')}"
+      end
+    end
+
+    def validate_size!(size_bytes)
+      if size_bytes > MAX_SIZE_BYTES
+        raise ArgumentError, "Document size exceeds 32MB limit (got #{size_bytes} bytes)"
+      end
+    end
+
+    def infer_content_type_from_url(url)
+      extension = File.extname(URI.parse(url).path).downcase
+
+      case extension
+      when '.pdf'
+        'application/pdf'
+      else
+        raise ArgumentError, "Document URL must point to a PDF (.pdf): #{url}"
+      end
+    end
+
+    def to_binary
+      return Base64.decode64(base64) if base64
+      return data.pack('C*') if data
+
+      raise ArgumentError, "Document has no binary content"
+    end
+  end
+end

data/lib/dspy/lm/adapter.rb

@@ -58,6 +58,17 @@ module DSPy
         end
       end
 
+      def contains_documents?(messages)
+        messages.any? do |msg|
+          content = msg[:content] || msg.content
+          content.is_a?(Array) && content.any? { |item| item[:type] == 'document' }
+        end
+      end
+
+      def contains_media?(messages)
+        contains_images?(messages) || contains_documents?(messages)
+      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
@@ -71,6 +82,8 @@ module DSPy
                 { type: 'text', text: item[:text] }
               when 'image'
                 format_image_for_provider(item[:image], provider_name)
+              when 'document'
+                format_document_for_provider(item[:document], provider_name)
               else
                 item
               end
@@ -96,6 +109,16 @@ module DSPy
           { type: 'image', image: image }
         end
       end
+
+      def format_document_for_provider(document, provider_name)
+        document.validate_for_provider!(provider_name)
+        format_method = "to_#{provider_name}_format"
+        if document.respond_to?(format_method)
+          document.send(format_method)
+        else
+          { type: 'document', document: document }
+        end
+      end
     end
   end
 end

data/lib/dspy/lm/errors.rb

@@ -7,8 +7,6 @@ module DSPy
     class UnsupportedProviderError < Error; end
     class ConfigurationError < Error; end
     class MissingAdapterError < Error; end
-    class UnsupportedVersionError < Error; end
-    class MissingOfficialSDKError < Error; end
     
     # Raised when API key is missing or invalid
     class MissingAPIKeyError < Error
@@ -29,5 +27,12 @@ module DSPy
         super(message)
       end
     end
+
+    # Raised when document features are incompatible with the target provider
+    class IncompatibleDocumentFeatureError < AdapterError
+      def initialize(message)
+        super(message)
+      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
-
-        # Add tool definition
-        request_params[:tools] = [tool_schema]
+        # Use Anthropic Beta API structured outputs
+        schema = DSPy::Anthropic::LM::SchemaConverter.to_beta_format(signature_class)
 
-        # 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,84 +131,6 @@ module DSPy
         end
       end
 
-      # Convert signature to Anthropic tool schema
-      # Uses strict: true for constrained decoding (Anthropic structured outputs)
-      # Anthropic strict mode requires ALL properties in required at every level.
-      sig { returns(T::Hash[Symbol, T.untyped]) }
-      def convert_to_anthropic_tool_schema
-        output_fields = signature_class.output_field_descriptors
-
-        schema = {
-          name: "json_output",
-          description: "Output the result in the required JSON format",
-          strict: true,
-          input_schema: {
-            type: "object",
-            properties: build_properties_from_fields(output_fields),
-            required: build_required_from_fields(output_fields),
-            additionalProperties: false
-          }
-        }
-
-        # Anthropic strict mode: ALL properties must be in required at every level.
-        # Non-required properties get auto-wrapped in null unions by the grammar compiler,
-        # which counts against the 16-union-parameter limit.
-        enforce_all_required(schema[:input_schema])
-
-        schema
-      end
-
-      # Build required field list, excluding fields that have defaults
-      sig { params(fields: T::Hash[Symbol, T.untyped]).returns(T::Array[String]) }
-      def build_required_from_fields(fields)
-        fields.reject { |_name, descriptor| descriptor.has_default }.keys.map(&:to_s)
-      end
-
-      # Recursively enforce that all properties are in required and
-      # additionalProperties is false, as required by Anthropic strict mode.
-      sig { params(schema: T::Hash[Symbol, T.untyped]).void }
-      def enforce_all_required(schema)
-        return unless schema.is_a?(Hash)
-
-        if schema[:type] == "object" && schema[:properties]
-          schema[:required] = schema[:properties].keys.map(&:to_s)
-          schema[:additionalProperties] = false
-          schema[:properties].each_value { |v| enforce_all_required(v) }
-        elsif schema[:type] == "array" && schema[:items]
-          enforce_all_required(schema[:items])
-        elsif schema[:type].is_a?(Array)
-          # type: ["array", "null"] — check items if present
-          enforce_all_required(schema[:items]) if schema[:items]
-        end
-      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)
@@ -221,48 +139,93 @@ module DSPy
         # 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)
-          return json_match[1].strip if json_match
+          if json_match
+            normalized = normalize_json_candidate(json_match[1].strip)
+            return normalized if valid_json?(normalized)
+          end
         end
 
         # Try 2: Check for generic ``` code block
         if content.include?('```')
           code_match = content.match(/```\s*\n(.*?)\n```/m)
           if code_match
-            potential_json = code_match[1].strip
-            # Verify it's JSON
-            begin
-              JSON.parse(potential_json)
-              return potential_json
-            rescue JSON::ParserError
-              # Not valid JSON, continue
-            end
+            potential_json = normalize_json_candidate(code_match[1].strip)
+            return potential_json if valid_json?(potential_json)
           end
         end
 
         # Try 3: Try parsing entire content as JSON
-        begin
-          JSON.parse(content)
-          return content
-        rescue JSON::ParserError
-          # Not pure JSON, try extracting
-        end
+        normalized_content = normalize_json_candidate(content)
+        return normalized_content if valid_json?(normalized_content)
 
         # Try 4: Look for JSON object pattern in text (greedy match for nested objects)
         json_pattern = /\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\}/m
         json_match = content.match(json_pattern)
         if json_match
-          potential_json = json_match[0]
-          begin
-            JSON.parse(potential_json)
-            return potential_json
-          rescue JSON::ParserError
-            # Not valid JSON
-          end
+          potential_json = normalize_json_candidate(json_match[0])
+          return potential_json if valid_json?(potential_json)
         end
 
         # Return content as-is if no JSON found
         content
       end
+
+      sig { params(content: String).returns(String) }
+      def normalize_json_candidate(content)
+        escape_control_characters_in_strings(remove_trailing_object_commas(content))
+      end
+
+      sig { params(content: String).returns(String) }
+      def remove_trailing_object_commas(content)
+        content.sub(/,(\s*\}\s*)$/, '\1')
+      end
+
+      sig { params(content: String).returns(T::Boolean) }
+      def valid_json?(content)
+        JSON.parse(content)
+        true
+      rescue JSON::ParserError
+        false
+      end
+
+      sig { params(content: String).returns(String) }
+      def escape_control_characters_in_strings(content)
+        escaped = +""
+        in_string = false
+        escaping = false
+
+        content.each_char do |char|
+          if in_string
+            if escaping
+              escaped << char
+              escaping = false
+              next
+            end
+
+            case char
+            when '\\'
+              escaped << char
+              escaping = true
+            when '"'
+              escaped << char
+              in_string = false
+            when "\n"
+              escaped << '\n'
+            when "\r"
+              escaped << '\r'
+            when "\t"
+              escaped << '\t'
+            else
+              escaped << (char.ord < 0x20 ? "" : char)
+            end
+          else
+            escaped << char
+            in_string = true if char == '"'
+          end
+        end
+
+        escaped
+      end
     end
   end
 end