dspy 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d80d5b0166fe5a101e4918ffee13a70dec6ca67b493cf2e68dff1c18b2df36c1
-  data.tar.gz: 1687fe88d41c5d4627592ff5e98f87ca9f40186870386291b1ead091f51235da
+  metadata.gz: 92f074914faabe00390399080ef0efecca6ca6dbfeeca38201c127cfbef11528
+  data.tar.gz: 91c07b99351fd1095f5e61e1b8c9560c1c67ee67c97c945437f4a2964172eaca
 SHA512:
-  metadata.gz: 7bedebf2e58243bedcf8003d25b4f55789a7e4a611f9f1997a322e93db553fe117fde155415c5a607a65b49f61f2a640c7899a0fd4793bcdf9e8672602f54755
-  data.tar.gz: cdf39e605a7550e94334c5bad13ccc5af2a255b7039559b56b918e1ba3706e671c52960558459a0c96edab318c68bc9828b1eb03530b47daa896766a2cb7aa7d
+  metadata.gz: 303990f2586f73beaf638ed85b1e5266a318f760aae0342af4738652078b0087e7d6826588d80fb4d26b3b9ca026dfc1b3f3e6645e3b24213d0cf94b1fbb450f
+  data.tar.gz: db445cef172a2009d565b659fd4170895045dacbbbd9073b0d20ab8c054e2085ed62cfb8d1dbf6b98e203422cc999a495fb2e84ba3363d31360472b10f1487e9

data/README.md

@@ -46,7 +46,7 @@ The result? LLM applications that actually scale and don't break when you sneeze
 
 ## Development Status
 
-DSPy.rb is actively developed and approaching stability at **v0.10.1**. The core framework is production-ready with comprehensive documentation, but I'm battle-testing features through the 0.x series before committing to a stable v1.0 API. 
+DSPy.rb is actively developed and approaching stability at **v0.13.0**. The core framework is production-ready with comprehensive documentation, but I'm battle-testing features through the 0.x series before committing to a stable v1.0 API. 
 
 Real-world usage feedback is invaluable - if you encounter issues or have suggestions, please open a GitHub issue!
 
@@ -55,7 +55,7 @@ Real-world usage feedback is invaluable - if you encounter issues or have sugges
 ### Installation
 
 ```ruby
-gem 'dspy', '~> 0.9'
+gem 'dspy', '~> 0.13'
 ```
 
 Or add to your Gemfile:
@@ -138,6 +138,12 @@ puts result.confidence   # => 0.85
 
 📖 **[Complete Documentation Website](https://vicentereig.github.io/dspy.rb/)**
 
+### LLM-Friendly Documentation
+
+For LLMs and AI assistants working with DSPy.rb:
+- **[llms.txt](https://vicentereig.github.io/dspy.rb/llms.txt)** - Concise reference optimized for LLMs
+- **[llms-full.txt](https://vicentereig.github.io/dspy.rb/llms-full.txt)** - Comprehensive API documentation
+
 ### Getting Started
 - **[Installation & Setup](docs/src/getting-started/installation.md)** - Detailed installation and configuration
 - **[Quick Start Guide](docs/src/getting-started/quick-start.md)** - Your first DSPy programs
@@ -177,7 +183,7 @@ DSPy.rb has rapidly evolved from experimental to production-ready:
 
 ## Roadmap - Battle-Testing Toward v1.0
 
-DSPy.rb is currently at **v0.10.1** and approaching stability. I'm focusing on real-world usage and refinement through the 0.11, 0.12+ series before committing to a stable v1.0 API.
+DSPy.rb is currently at **v0.13.0** and approaching stability. I'm focusing on real-world usage and refinement through the 0.14, 0.15+ series before committing to a stable v1.0 API.
 
 **Current Focus Areas:**
 - 🚧 **Ollama Support** - Local model integration

data/lib/dspy/lm/adapters/anthropic_adapter.rb

@@ -15,15 +15,20 @@ module DSPy
         # Anthropic requires system message to be separate from messages
         system_message, user_messages = extract_system_message(normalize_messages(messages))
         
-        # Apply JSON prefilling if needed for better Claude JSON compliance
-        user_messages = prepare_messages_for_json(user_messages, system_message)
+        # Check if this is a tool use request
+        has_tools = extra_params.key?(:tools) && !extra_params[:tools].empty?
+        
+        # Apply JSON prefilling if needed for better Claude JSON compliance (but not for tool use)
+        unless has_tools
+          user_messages = prepare_messages_for_json(user_messages, system_message)
+        end
         
         request_params = {
           model: model,
           messages: user_messages,
           max_tokens: 4096, # Required for Anthropic
           temperature: 0.0 # DSPy default for deterministic responses
-        }
+        }.merge(extra_params)
 
         # Add system message if present
         request_params[:system] = system_message if system_message
@@ -60,21 +65,44 @@ module DSPy
               raise AdapterError, "Anthropic API error: #{response.error}"
             end
 
-            content = response.content.first.text if response.content.is_a?(Array) && response.content.first
+            # Handle both text content and tool use
+            content = ""
+            tool_calls = []
+            
+            if response.content.is_a?(Array)
+              response.content.each do |content_block|
+                case content_block.type.to_s
+                when "text"
+                  content += content_block.text
+                when "tool_use"
+                  tool_calls << {
+                    id: content_block.id,
+                    name: content_block.name,
+                    input: content_block.input
+                  }
+                end
+              end
+            end
+            
             usage = response.usage
 
             # Convert usage data to typed struct
             usage_struct = UsageFactory.create('anthropic', usage)
             
+            metadata = {
+              provider: 'anthropic',
+              model: model,
+              response_id: response.id,
+              role: response.role
+            }
+            
+            # Add tool calls to metadata if present
+            metadata[:tool_calls] = tool_calls unless tool_calls.empty?
+            
             Response.new(
               content: content,
               usage: usage_struct,
-              metadata: {
-                provider: 'anthropic',
-                model: model,
-                response_id: response.id,
-                role: response.role
-              }
+              metadata: metadata
             )
           end
         rescue => e

data/lib/dspy/lm/strategies/anthropic_tool_use_strategy.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module DSPy
+  class LM
+    module Strategies
+      # Strategy for using Anthropic's tool use feature for guaranteed JSON output
+      class AnthropicToolUseStrategy < BaseStrategy
+        extend T::Sig
+
+        sig { override.returns(T::Boolean) }
+        def available?
+          # Only available for Anthropic adapters with models that support tool use
+          adapter.is_a?(DSPy::LM::AnthropicAdapter) && supports_tool_use?
+        end
+
+        sig { override.returns(Integer) }
+        def priority
+          95 # Higher priority than extraction strategy - tool use is more reliable
+        end
+
+        sig { override.returns(String) }
+        def name
+          "anthropic_tool_use"
+        end
+
+        sig { override.params(messages: T::Array[T::Hash[Symbol, String]], request_params: T::Hash[Symbol, T.untyped]).void }
+        def prepare_request(messages, request_params)
+          # Convert signature output schema to Anthropic tool format
+          tool_schema = convert_to_tool_schema
+          
+          # Add the tool definition to request params
+          request_params[:tools] = [tool_schema]
+          
+          # Force the model to use our tool
+          request_params[:tool_choice] = {
+            type: "tool",
+            name: "json_output"
+          }
+          
+          # Update the last user message to request tool use
+          if messages.any? && messages.last[:role] == "user"
+            messages.last[:content] += "\n\nPlease use the json_output tool to provide your response."
+          end
+        end
+
+        sig { override.params(response: DSPy::LM::Response).returns(T.nilable(String)) }
+        def extract_json(response)
+          # Extract JSON from tool use response
+          begin
+            # Check for tool calls in metadata first (this is the primary method)
+            if response.metadata && 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]
+                  json_result = JSON.generate(first_call[:input])
+                  return json_result
+                end
+              end
+            end
+            
+            # Fallback: try to extract from content if it contains tool use blocks
+            content = response.content
+            if content && !content.empty? && content.include?("<tool_use>")
+              tool_content = content[/<tool_use>.*?<\/tool_use>/m]
+              if tool_content
+                json_match = tool_content[/<input>(.*?)<\/input>/m, 1]
+                return json_match.strip if json_match
+              end
+            end
+            
+            nil
+          rescue => e
+            DSPy.logger.debug("Failed to extract tool use JSON: #{e.message}")
+            nil
+          end
+        end
+
+        sig { override.params(error: StandardError).returns(T::Boolean) }
+        def handle_error(error)
+          # Tool use errors should trigger fallback to extraction strategy
+          if error.message.include?("tool") || error.message.include?("invalid_request_error")
+            DSPy.logger.warn("Anthropic tool use failed: #{error.message}")
+            true # We handled it, try next strategy
+          else
+            false # Let retry handler deal with it
+          end
+        end
+
+        private
+
+        sig { returns(T::Boolean) }
+        def supports_tool_use?
+          # Check if model supports tool use
+          # Claude 3 models (Opus, Sonnet, Haiku) support tool use
+          model = adapter.model.downcase
+          model.include?("claude-3") || model.include?("claude-3.5")
+        end
+
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def convert_to_tool_schema
+          # Get output fields from signature
+          output_fields = signature_class.output_field_descriptors
+          
+          # Convert to Anthropic tool format
+          {
+            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
+
+        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] = convert_type_to_json_schema(descriptor.type)
+          end
+          
+          properties
+        end
+
+        sig { params(type: T.untyped).returns(T::Hash[String, T.untyped]) }
+        def convert_type_to_json_schema(type)
+          # Handle raw Ruby class types - use === for class comparison
+          if type == String
+            return { type: "string" }
+          elsif type == Integer
+            return { type: "integer" }
+          elsif type == Float
+            return { type: "number" }
+          elsif type == TrueClass || type == FalseClass
+            return { type: "boolean" }
+          end
+          
+          # Handle Sorbet types
+          case type
+          when T::Types::Simple
+            case type.raw_type.to_s
+            when "String"
+              { type: "string" }
+            when "Integer"
+              { type: "integer" }
+            when "Float", "Numeric"
+              { type: "number" }
+            when "TrueClass", "FalseClass"
+              { type: "boolean" }
+            else
+              { type: "string" } # Default fallback
+            end
+          when T::Types::TypedArray
+            {
+              type: "array",
+              items: convert_type_to_json_schema(type.type)
+            }
+          when T::Types::TypedHash
+            {
+              type: "object",
+              additionalProperties: convert_type_to_json_schema(type.values)
+            }
+          else
+            # For complex types, try to introspect
+            if type.respond_to?(:props)
+              {
+                type: "object",
+                properties: build_properties_from_props(type.props)
+              }
+            else
+              { type: "object" } # Generic object fallback
+            end
+          end
+        end
+
+        sig { params(props: T.untyped).returns(T::Hash[String, T.untyped]) }
+        def build_properties_from_props(props)
+          result = {}
+          props.each do |prop_name, prop_info|
+            result[prop_name.to_s] = convert_type_to_json_schema(prop_info[:type])
+          end
+          result
+        end
+      end
+    end
+  end
+end

data/lib/dspy/lm/strategy_selector.rb

@@ -3,6 +3,7 @@
 require "sorbet-runtime"
 require_relative "strategies/base_strategy"
 require_relative "strategies/openai_structured_output_strategy"
+require_relative "strategies/anthropic_tool_use_strategy"
 require_relative "strategies/anthropic_extraction_strategy"
 require_relative "strategies/enhanced_prompting_strategy"
 
@@ -15,6 +16,7 @@ module DSPy
       # Available strategies in order of registration
       STRATEGIES = [
         Strategies::OpenAIStructuredOutputStrategy,
+        Strategies::AnthropicToolUseStrategy,
         Strategies::AnthropicExtractionStrategy,
         Strategies::EnhancedPromptingStrategy
       ].freeze
@@ -99,7 +101,11 @@ module DSPy
         openai_strategy = find_strategy_by_name("openai_structured_output")
         return openai_strategy if openai_strategy&.available?
         
-        # Try Anthropic extraction
+        # Try Anthropic tool use first
+        anthropic_tool_strategy = find_strategy_by_name("anthropic_tool_use")
+        return anthropic_tool_strategy if anthropic_tool_strategy&.available?
+        
+        # Fall back to Anthropic extraction
         anthropic_strategy = find_strategy_by_name("anthropic_extraction")
         return anthropic_strategy if anthropic_strategy&.available?
         

data/lib/dspy/lm/structured_output_strategy.rb

@@ -8,6 +8,7 @@ module DSPy
     class StructuredOutputStrategy < T::Enum
       enums do
         OpenAIStructuredOutput = new("openai_structured_output")
+        AnthropicToolUse = new("anthropic_tool_use")
         AnthropicExtraction = new("anthropic_extraction")
         EnhancedPrompting = new("enhanced_prompting")
       end

data/lib/dspy/lm.rb

@@ -118,7 +118,7 @@ module DSPy
       end
       
       # Let strategy handle JSON extraction if needed
-      if signature_class && response.content
+      if signature_class
         extracted_json = strategy.extract_json(response)
         if extracted_json && extracted_json != response.content
           # Create a new response with extracted JSON

data/lib/dspy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DSPy
-  VERSION = "0.13.0"
+  VERSION = "0.14.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-07-25 00:00:00.000000000 Z
+date: 2025-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -150,8 +150,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
-description: A Ruby implementation of DSPy, a framework for programming with large
-  language models
+description: The Ruby framework for programming with large language models.
 email:
 - hey@vicente.services
 executables: []
@@ -181,6 +180,7 @@ files:
 - lib/dspy/lm/response.rb
 - lib/dspy/lm/retry_handler.rb
 - lib/dspy/lm/strategies/anthropic_extraction_strategy.rb
+- lib/dspy/lm/strategies/anthropic_tool_use_strategy.rb
 - lib/dspy/lm/strategies/base_strategy.rb
 - lib/dspy/lm/strategies/enhanced_prompting_strategy.rb
 - lib/dspy/lm/strategies/openai_structured_output_strategy.rb
@@ -249,5 +249,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key: 
 specification_version: 4
-summary: Ruby port of DSPy 2.6
+summary: The Ruby framework for programming—rather than prompting—language models.
 test_files: []