dspy 0.27.5 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8a0e5d292482730715265985f5334aa60853c2146c9dde2dc18ffa9b882ca6d
-  data.tar.gz: 9ae0827c01495b38b9250714254d841948a1191b74e3f7af59360f1b2e4705c1
+  metadata.gz: df0e7cf901df85567e1553a3d7df8659a71f254fa5671803ea98f0573de0c39a
+  data.tar.gz: b2d5d37cb05678f97143a1463410d92848ba10178bd50d60ee384827e9efe9b1
 SHA512:
-  metadata.gz: b7912c2a40ea8f036211bf7553cac71746cfbf0b24790cb3a69df0bf513771fbcdf7d317d5e492ea8354b46acca0b17d62bd02a3a2debaf191343ff7934df68c
-  data.tar.gz: cafc3cd07f94829e3aae3277630c2a875b6c2cfb982ca64fa493531b6274fe10079fca447824b42d31d8d1a7a4bb43714e5256d3ce7505e31b01a5d4b10007df
+  metadata.gz: 0d870f2d338fcdce0540143decd3674e94a9c24e5fad796536772e6c8064af75dcafc36533bf39a0a1eeefac30777de1d6541a3ab57eb2568a007260d7a5d7a3
+  data.tar.gz: 13f92278a81ca870f90b662fa40972e41aa6203d27a8792d3d03c13b97d971d7684a0f661dfb86bf03ef5c58e4a8f2f57c2ac48414ed9b8f8e5f0bce7628f231

data/README.md

@@ -59,22 +59,41 @@ puts result.sentiment    # => #<Sentiment::Positive>
 puts result.confidence   # => 0.85
 ```
 
-### Alternative Providers
+### Access to 200+ Models Across 5 Providers
 
-DSPy.rb supports multiple providers with native structured outputs:
+DSPy.rb provides unified access to major LLM providers with provider-specific optimizations:
 
 ```ruby
-# Google Gemini with native structured outputs
+# OpenAI (GPT-4, GPT-4o, GPT-4o-mini, GPT-5, etc.)
 DSPy.configure do |c|
-  c.lm = DSPy::LM.new('gemini/gemini-1.5-flash',
-                      api_key: ENV['GEMINI_API_KEY'], 
-                      structured_outputs: true)  # Supports gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash-exp
+  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
+                      api_key: ENV['OPENAI_API_KEY'],
+                      structured_outputs: true)  # Native JSON mode
+end
+
+# Google Gemini (Gemini 1.5 Pro, Flash, Gemini 2.0, etc.)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('gemini/gemini-2.5-flash',
+                      api_key: ENV['GEMINI_API_KEY'],
+                      structured_outputs: true)  # Native structured outputs
+end
+
+# Anthropic Claude (Claude 3.5, Claude 4, etc.)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-5-20250929',
+                      api_key: ENV['ANTHROPIC_API_KEY'],
+                      structured_outputs: true)  # Tool-based extraction (default)
+end
+
+# Ollama - Run any local model (Llama, Mistral, Gemma, etc.)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('ollama/llama3.2')  # Free, runs locally, no API key needed
 end
 
-# Anthropic Claude with tool-based extraction
+# OpenRouter - Access to 200+ models from multiple providers
 DSPy.configure do |c|
-  c.lm = DSPy::LM.new('anthropic/claude-3-sonnet-20241022',
-                      api_key: ENV['ANTHROPIC_API_KEY'])  # Automatic strategy selection
+  c.lm = DSPy::LM.new('openrouter/deepseek/deepseek-chat-v3.1:free',
+                      api_key: ENV['OPENROUTER_API_KEY'])
 end
 ```
 

data/lib/dspy/lm/adapter_factory.rb

@@ -13,7 +13,7 @@ module DSPy
         'openrouter' => 'OpenrouterAdapter'
       }.freeze
 
-      PROVIDERS_WITH_EXTRA_OPTIONS = %w[openai ollama gemini openrouter].freeze
+      PROVIDERS_WITH_EXTRA_OPTIONS = %w[openai anthropic ollama gemini openrouter].freeze
 
       class << self
         # Creates an adapter instance based on model_id

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

@@ -6,10 +6,11 @@ require_relative '../vision_models'
 module DSPy
   class LM
     class AnthropicAdapter < Adapter
-      def initialize(model:, api_key:)
-        super
+      def initialize(model:, api_key:, structured_outputs: true)
+        super(model: model, api_key: api_key)
         validate_api_key!(api_key, 'anthropic')
         @client = Anthropic::Client.new(api_key: api_key)
+        @structured_outputs_enabled = structured_outputs
       end
 
       def chat(messages:, signature: nil, **extra_params, &block)

data/lib/dspy/lm/chat_strategy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module DSPy
+  class LM
+    # Simple chat strategy that passes messages through without JSON extraction
+    class ChatStrategy
+      extend T::Sig
+
+      sig { params(adapter: T.untyped).void }
+      def initialize(adapter)
+        @adapter = adapter
+      end
+
+      # No modifications to messages for simple chat
+      sig { params(messages: T::Array[T::Hash[Symbol, T.untyped]], request_params: T::Hash[Symbol, T.untyped]).void }
+      def prepare_request(messages, request_params)
+        # Pass through unchanged
+      end
+
+      # No JSON extraction for chat
+      sig { params(response: DSPy::LM::Response).returns(NilClass) }
+      def extract_json(response)
+        nil
+      end
+
+      sig { returns(String) }
+      def name
+        'chat'
+      end
+
+      private
+
+      attr_reader :adapter
+    end
+  end
+end

data/lib/dspy/lm/json_strategy.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require_relative "adapters/openai/schema_converter"
+require_relative "adapters/gemini/schema_converter"
+
+module DSPy
+  class LM
+    # JSON extraction strategy with provider-specific handling
+    class JSONStrategy
+      extend T::Sig
+
+      sig { params(adapter: T.untyped, signature_class: T.class_of(DSPy::Signature)).void }
+      def initialize(adapter, signature_class)
+        @adapter = adapter
+        @signature_class = signature_class
+      end
+
+      # Prepare request with provider-specific JSON extraction parameters
+      sig { params(messages: T::Array[T::Hash[Symbol, T.untyped]], request_params: T::Hash[Symbol, T.untyped]).void }
+      def prepare_request(messages, request_params)
+        adapter_class_name = adapter.class.name
+
+        if adapter_class_name.include?('OpenAIAdapter') || adapter_class_name.include?('OllamaAdapter')
+          prepare_openai_request(request_params)
+        elsif adapter_class_name.include?('AnthropicAdapter')
+          prepare_anthropic_request(messages, request_params)
+        elsif adapter_class_name.include?('GeminiAdapter')
+          prepare_gemini_request(request_params)
+        end
+        # Unknown provider - no special handling
+      end
+
+      # Extract JSON from response based on provider
+      sig { params(response: DSPy::LM::Response).returns(T.nilable(String)) }
+      def extract_json(response)
+        adapter_class_name = adapter.class.name
+
+        if adapter_class_name.include?('OpenAIAdapter') || adapter_class_name.include?('OllamaAdapter')
+          # 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
+        elsif adapter_class_name.include?('GeminiAdapter')
+          # Gemini: try to extract JSON from various formats
+          extract_json_from_content(response.content)
+        else
+          # Unknown provider: try to extract JSON
+          extract_json_from_content(response.content)
+        end
+      end
+
+      sig { returns(String) }
+      def name
+        'json'
+      end
+
+      private
+
+      attr_reader :adapter, :signature_class
+
+      # OpenAI/Ollama preparation
+      sig { params(request_params: T::Hash[Symbol, T.untyped]).void }
+      def prepare_openai_request(request_params)
+        # Check if structured outputs are supported
+        if adapter.instance_variable_get(:@structured_outputs_enabled) &&
+           DSPy::LM::Adapters::OpenAI::SchemaConverter.supports_structured_outputs?(adapter.model)
+          response_format = DSPy::LM::Adapters::OpenAI::SchemaConverter.to_openai_format(signature_class)
+          request_params[:response_format] = response_format
+        end
+      end
+
+      # 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)
+
+        # Default to true if not set (backward compatibility)
+        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]
+
+        # Force tool use
+        request_params[:tool_choice] = {
+          type: "tool",
+          name: "json_output"
+        }
+
+        # Update last user message
+        if messages.any? && messages.last[:role] == "user"
+          messages.last[:content] += "\n\nPlease use the json_output tool to provide your response."
+        end
+      end
+
+      # Gemini preparation
+      sig { params(request_params: T::Hash[Symbol, T.untyped]).void }
+      def prepare_gemini_request(request_params)
+        # Check if structured outputs are supported
+        if adapter.instance_variable_get(:@structured_outputs_enabled) &&
+           DSPy::LM::Adapters::Gemini::SchemaConverter.supports_structured_outputs?(adapter.model)
+          schema = DSPy::LM::Adapters::Gemini::SchemaConverter.to_gemini_format(signature_class)
+
+          request_params[:generation_config] = {
+            response_mime_type: "application/json",
+            response_json_schema: schema
+          }
+        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?
+
+        # 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
+        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
+          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
+
+        # 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
+        end
+
+        # Return content as-is if no JSON found
+        content
+      end
+    end
+  end
+end

data/lib/dspy/lm.rb

@@ -20,8 +20,8 @@ require_relative 'lm/adapters/gemini_adapter'
 require_relative 'lm/adapters/openrouter_adapter'
 
 # Load strategy system
-require_relative 'lm/strategy_selector'
-require_relative 'lm/retry_handler'
+require_relative 'lm/chat_strategy'
+require_relative 'lm/json_strategy'
 
 # Load message builder and message types
 require_relative 'lm/message'
@@ -64,7 +64,10 @@ module DSPy
         response = instrument_lm_request(messages, signature_class.name) do
           chat_with_strategy(messages, signature_class, &block)
         end
-        
+
+        # Emit the standard lm.tokens event (consistent with raw_chat)
+        emit_token_usage(response, signature_class.name)
+
         # Parse response (no longer needs separate instrumentation)
         parsed_result = parse_response(response, input_values, signature_class)
         
@@ -96,21 +99,15 @@ module DSPy
     private
 
     def chat_with_strategy(messages, signature_class, &block)
-      # Select the best strategy for JSON extraction
-      strategy_selector = StrategySelector.new(adapter, signature_class)
-      initial_strategy = strategy_selector.select
-      
-      if DSPy.config.structured_outputs.retry_enabled && signature_class
-        # Use retry handler for JSON responses
-        retry_handler = RetryHandler.new(adapter, signature_class)
-        
-        retry_handler.with_retry(initial_strategy) do |strategy|
-          execute_chat_with_strategy(messages, signature_class, strategy, &block)
-        end
+      # Choose strategy based on whether we need JSON extraction
+      strategy = if signature_class
+        JSONStrategy.new(adapter, signature_class)
       else
-        # No retry logic, just execute once
-        execute_chat_with_strategy(messages, signature_class, initial_strategy, &block)
+        ChatStrategy.new(adapter)
       end
+
+      # Execute with the selected strategy (no retry, no fallback)
+      execute_chat_with_strategy(messages, signature_class, strategy, &block)
     end
 
     def execute_chat_with_strategy(messages, signature_class, strategy, &block)