dspy 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d80d5b0166fe5a101e4918ffee13a70dec6ca67b493cf2e68dff1c18b2df36c1
-  data.tar.gz: 1687fe88d41c5d4627592ff5e98f87ca9f40186870386291b1ead091f51235da
+  metadata.gz: 0df0301fbda6076f6d4ecaeb7fa907982b11fe67521d4aa689ca812cb1485a71
+  data.tar.gz: ba7d57fa4fef32861b37ccb428c12f58c4262123bff1069dddb3c53c72e9dd67
 SHA512:
-  metadata.gz: 7bedebf2e58243bedcf8003d25b4f55789a7e4a611f9f1997a322e93db553fe117fde155415c5a607a65b49f61f2a640c7899a0fd4793bcdf9e8672602f54755
-  data.tar.gz: cdf39e605a7550e94334c5bad13ccc5af2a255b7039559b56b918e1ba3706e671c52960558459a0c96edab318c68bc9828b1eb03530b47daa896766a2cb7aa7d
+  metadata.gz: 07a619845a4e65cb03d4b9e53726bb6b306ddb5d5c08a6521785c415d6f4a5e1a21949f5120c2dafc3429114c5b97c0a1f2d19d30528bfcfe311aef97bc28245
+  data.tar.gz: 90a800ee9a612da5fd735b36b3c887df8fc777ccd0ed5b4badf4049352c19bcb64a508e7b722b4eae51b08ddf5386e292ae7bbc893c1b444ee1e3b1305f46f05

data/README.md

@@ -40,13 +40,14 @@ The result? LLM applications that actually scale and don't break when you sneeze
 - LLM provider support using official Ruby clients:
   - [OpenAI Ruby](https://github.com/openai/openai-ruby)
   - [Anthropic Ruby SDK](https://github.com/anthropics/anthropic-sdk-ruby)
+  - [Ollama](https://ollama.com/) via OpenAI compatibility layer
 - Runtime type checking with [Sorbet](https://sorbet.org/)
 - Type-safe tool definitions for ReAct agents
 - Comprehensive instrumentation and observability
 
 ## 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 +56,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 +139,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 +184,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/adapter_factory.rb

@@ -7,7 +7,8 @@ module DSPy
       # Maps provider prefixes to adapter classes
       ADAPTER_MAP = {
         'openai' => 'OpenAIAdapter',
-        'anthropic' => 'AnthropicAdapter'
+        'anthropic' => 'AnthropicAdapter',
+        'ollama' => 'OllamaAdapter'
       }.freeze
 
       class << self
@@ -22,7 +23,8 @@ module DSPy
           
           # Pass provider-specific options
           adapter_options = { model: model, api_key: api_key }
-          adapter_options.merge!(options) if provider == 'openai' # Only OpenAI accepts structured_outputs for now
+          # Both OpenAI and Ollama accept additional options
+          adapter_options.merge!(options) if %w[openai ollama].include?(provider)
           
           adapter_class.new(**adapter_options)
         end

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/adapters/ollama_adapter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'openai'
+
+module DSPy
+  class LM
+    class OllamaAdapter < OpenAIAdapter
+      DEFAULT_BASE_URL = 'http://localhost:11434/v1'
+      
+      def initialize(model:, api_key: nil, base_url: nil, structured_outputs: true)
+        # Ollama doesn't require API key for local instances
+        # But may need it for remote/protected instances
+        api_key ||= 'ollama' # OpenAI client requires non-empty key
+        base_url ||= DEFAULT_BASE_URL
+        
+        # Store base_url before calling super
+        @base_url = base_url
+        
+        # Don't call parent's initialize, do it manually to control client creation
+        @model = model
+        @api_key = api_key
+        @structured_outputs_enabled = structured_outputs
+        validate_configuration!
+        
+        # Create client with custom base URL
+        @client = OpenAI::Client.new(
+          api_key: @api_key,
+          base_url: @base_url
+        )
+      end
+      
+      def chat(messages:, signature: nil, response_format: nil, &block)
+        # For Ollama, we need to be more lenient with structured outputs
+        # as it may not fully support OpenAI's response_format spec
+        begin
+          super
+        rescue => e
+          # If structured output fails, retry with enhanced prompting
+          if @structured_outputs_enabled && signature && e.message.include?('response_format')
+            DSPy.logger.debug("Ollama structured output failed, falling back to enhanced prompting")
+            @structured_outputs_enabled = false
+            retry
+          else
+            raise
+          end
+        end
+      end
+      
+      private
+      
+      def validate_configuration!
+        super
+        # Additional Ollama-specific validation could go here
+      end
+      
+      def validate_api_key!(api_key, provider)
+        # For Ollama, API key is optional for local instances
+        # Only validate if it looks like a remote URL
+        if @base_url && !@base_url.include?('localhost') && !@base_url.include?('127.0.0.1')
+          super
+        end
+      end
+      
+      
+      # Ollama may have different model support for structured outputs
+      def supports_structured_outputs?
+        # For now, assume all Ollama models support basic JSON mode
+        # but may not support full OpenAI structured output spec
+        true
+      end
+    end
+  end
+end

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/strategies/openai_structured_output_strategy.rb

@@ -11,10 +11,15 @@ module DSPy
 
         sig { override.returns(T::Boolean) }
         def available?
-          # Check if adapter is OpenAI and supports structured outputs
-          return false unless adapter.is_a?(DSPy::LM::OpenAIAdapter)
+          # Check if adapter is OpenAI or Ollama and supports structured outputs
+          return false unless adapter.is_a?(DSPy::LM::OpenAIAdapter) || adapter.is_a?(DSPy::LM::OllamaAdapter)
           return false unless adapter.instance_variable_get(:@structured_outputs_enabled)
           
+          # For Ollama, we assume it supports basic structured outputs
+          if adapter.is_a?(DSPy::LM::OllamaAdapter)
+            return true
+          end
+          
           DSPy::LM::Adapters::OpenAI::SchemaConverter.supports_structured_outputs?(adapter.model)
         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

@@ -13,6 +13,7 @@ require_relative 'instrumentation/token_tracker'
 # Load adapters
 require_relative 'lm/adapters/openai_adapter'
 require_relative 'lm/adapters/anthropic_adapter'
+require_relative 'lm/adapters/ollama_adapter'
 
 # Load strategy system
 require_relative 'lm/strategy_selector'
@@ -118,7 +119,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.15.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.15.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: []
@@ -173,6 +172,7 @@ files:
 - lib/dspy/lm/adapter.rb
 - lib/dspy/lm/adapter_factory.rb
 - lib/dspy/lm/adapters/anthropic_adapter.rb
+- lib/dspy/lm/adapters/ollama_adapter.rb
 - lib/dspy/lm/adapters/openai/schema_converter.rb
 - lib/dspy/lm/adapters/openai_adapter.rb
 - lib/dspy/lm/cache_manager.rb
@@ -181,6 +181,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 +250,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: []