dspy 0.26.1 → 0.27.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e243b7278275462baea2f493270166a1ae4b5419d4f072a769e4ba4b0f65e3e0
-  data.tar.gz: 13bcbcf4ee67c08f19ad619bc8118e39ca9a02045c5a18b3a664fb112724fa87
+  metadata.gz: 7962564b749798c462b3202e16153aa9e508e8d7fb10d6618c76e740ecb171d1
+  data.tar.gz: d81fad4637c82967745d644c291f7436e26c0c1bf06785ff56028c71d4d5f26d
 SHA512:
-  metadata.gz: 687385021bf9391b22ae51a3f7c05880bec9691347a4e8ecac9175b7e81190c9f63cb0670a94e7324a045d748346cc91b6f7e174808607eaf0d02b8a0a117992
-  data.tar.gz: 3212712d53aca34cbc475503396d4fbeb7b8c11632b673782e7cd2dc2e6fdb22a3ad67688d92b60bd72e845f7b598b446e94fd3f5c6efd5e87f212bb1be14b9e
+  metadata.gz: 38ed78b62481f7267a9d1fa7157af436bdfd82d6a8281b00b9d8915fa74e7b0b5d896f8dfa9d6f4a91aa829973f7db94445d76b3cdb5e7c66800cd23f28f1fe9
+  data.tar.gz: 61f0ef47790c3c9aa6c6ecd1f7ee11268ac81b27ca75212af2c69b4f4b077fa07c9acb237c7d7b3f4174c85d7de415684ac9fef5c88e01d538671b93910fa889

data/README.md

@@ -59,6 +59,25 @@ puts result.sentiment    # => #<Sentiment::Positive>
 puts result.confidence   # => 0.85
 ```
 
+### Alternative Providers
+
+DSPy.rb supports multiple providers with native structured outputs:
+
+```ruby
+# Google Gemini with native structured outputs
+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
+end
+
+# Anthropic Claude with tool-based extraction
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('anthropic/claude-3-sonnet-20241022',
+                      api_key: ENV['ANTHROPIC_API_KEY'])  # Automatic strategy selection
+end
+```
+
 ## What You Get
 
 **Core Building Blocks:**
@@ -77,7 +96,7 @@ puts result.confidence   # => 0.85
 - **GEPA Optimization** - Genetic-Pareto optimization for multi-objective prompt improvement
 
 **Production Features:**
-- **Reliable JSON Extraction** - Native OpenAI structured outputs, Anthropic extraction patterns, and automatic strategy selection with fallback
+- **Reliable JSON Extraction** - Native structured outputs for OpenAI and Gemini, Anthropic tool-based extraction, and automatic strategy selection with fallback
 - **Type-Safe Configuration** - Strategy enums with automatic provider optimization (Strict/Compatible modes)
 - **Smart Retry Logic** - Progressive fallback with exponential backoff for handling transient failures
 - **Zero-Config Langfuse Integration** - Set env vars and get automatic OpenTelemetry traces in Langfuse
@@ -89,6 +108,7 @@ puts result.confidence   # => 0.85
 - LLM provider support using official Ruby clients:
   - [OpenAI Ruby](https://github.com/openai/openai-ruby) with vision model support
   - [Anthropic Ruby SDK](https://github.com/anthropics/anthropic-sdk-ruby) with multimodal capabilities
+  - [Google Gemini API](https://ai.google.dev/) with native structured outputs
   - [Ollama](https://ollama.com/) via OpenAI compatibility layer for local models
 - **Multimodal Support** - Complete image analysis with DSPy::Image, type-safe bounding boxes, vision-capable models
 - Runtime type checking with [Sorbet](https://sorbet.org/) including T::Enum and union types

data/lib/dspy/context.rb

@@ -6,29 +6,31 @@ module DSPy
   class Context
     class << self
       def current
-        # Check if we're in an async context (fiber created by async gem)
-        if in_async_context?
-          # Use Fiber storage for async contexts to enable inheritance
-          # Inherit from Thread.current if Fiber storage is not set
-          Fiber[:dspy_context] ||= Thread.current[:dspy_context] || {
-            trace_id: SecureRandom.uuid,
-            span_stack: []
-          }
-          
-          # Return Fiber storage in async contexts
-          Fiber[:dspy_context]
+        # Use a combination of Thread and Fiber storage for proper context management
+        # Thread storage ensures thread isolation
+        # Fiber storage ensures OpenTelemetry context propagation
+        
+        # Create a unique key for this thread to ensure isolation
+        thread_key = :"dspy_context_#{Thread.current.object_id}"
+        
+        # Check if this thread has its own context
+        if Thread.current[thread_key]
+          # Thread has context, ensure fiber has it too for OpenTelemetry
+          Fiber[:dspy_context] ||= Thread.current[thread_key]
         else
-          # Use Thread.current for regular synchronous contexts
-          Thread.current[:dspy_context] ||= {
+          # No context for this thread - create new one
+          context = {
             trace_id: SecureRandom.uuid,
             span_stack: []
           }
-          
-          # Also sync to Fiber storage so async contexts can inherit it
-          Fiber[:dspy_context] = Thread.current[:dspy_context]
-          
-          Thread.current[:dspy_context]
+          # Set in both Thread and Fiber storage
+          Thread.current[thread_key] = context
+          Thread.current[:dspy_context] = context  # Keep for backward compatibility
+          Fiber[:dspy_context] = context
         end
+        
+        # Return the context (from Fiber storage for OpenTelemetry compatibility)
+        Fiber[:dspy_context]
       end
       
       def with_span(operation:, **attributes)
@@ -65,6 +67,7 @@ module DSPy
             # Record start time for explicit duration tracking
             otel_start_time = Time.now
             
+            # Always use in_span which properly manages context internally
             DSPy::Observability.tracer.in_span(
               operation,
               attributes: span_attributes,
@@ -102,6 +105,9 @@ module DSPy
       end
       
       def clear!
+        # Clear both the thread-specific key and the legacy key
+        thread_key = :"dspy_context_#{Thread.current.object_id}"
+        Thread.current[thread_key] = nil
         Thread.current[:dspy_context] = nil
         Fiber[:dspy_context] = nil
       end

data/lib/dspy/lm/adapter_factory.rb

@@ -24,8 +24,8 @@ module DSPy
           
           # Pass provider-specific options
           adapter_options = { model: model, api_key: api_key }
-          # Both OpenAI and Ollama accept additional options
-          adapter_options.merge!(options) if %w[openai ollama].include?(provider)
+          # OpenAI, Ollama, and Gemini accept additional options
+          adapter_options.merge!(options) if %w[openai ollama gemini].include?(provider)
           
           adapter_class.new(**adapter_options)
         end

data/lib/dspy/lm/adapters/gemini/schema_converter.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require_relative "../../cache_manager"
+
+module DSPy
+  class LM
+    module Adapters
+      module Gemini
+        # Converts DSPy signatures to Gemini structured output format
+        class SchemaConverter
+          extend T::Sig
+
+          # Models that support structured outputs
+          STRUCTURED_OUTPUT_MODELS = T.let([
+            "gemini-1.5-pro",
+            "gemini-1.5-flash",
+            "gemini-2.0-flash-exp"
+          ].freeze, T::Array[String])
+
+          sig { params(signature_class: T.class_of(DSPy::Signature)).returns(T::Hash[Symbol, T.untyped]) }
+          def self.to_gemini_format(signature_class)
+            # Check cache first
+            cache_manager = DSPy::LM.cache_manager
+            cached_schema = cache_manager.get_schema(signature_class, "gemini", {})
+            
+            if cached_schema
+              DSPy.logger.debug("Using cached schema for #{signature_class.name}")
+              return cached_schema
+            end
+            
+            # Get the output JSON schema from the signature class
+            output_schema = signature_class.output_json_schema
+            
+            # Convert to Gemini format (OpenAPI 3.0 Schema subset - not related to OpenAI)
+            gemini_schema = convert_dspy_schema_to_gemini(output_schema)
+            
+            # Cache the result
+            cache_manager.cache_schema(signature_class, "gemini", gemini_schema, {})
+            
+            gemini_schema
+          end
+
+          sig { params(model: String).returns(T::Boolean) }
+          def self.supports_structured_outputs?(model)
+            # Check cache first
+            cache_manager = DSPy::LM.cache_manager
+            cached_result = cache_manager.get_capability(model, "structured_outputs")
+            
+            if !cached_result.nil?
+              DSPy.logger.debug("Using cached capability check for #{model}")
+              return cached_result
+            end
+            
+            # Extract base model name without provider prefix
+            base_model = model.sub(/^gemini\//, "")
+            
+            # Check if it's a supported model or a newer version
+            result = STRUCTURED_OUTPUT_MODELS.any? { |supported| base_model.start_with?(supported) }
+            
+            # Cache the result
+            cache_manager.cache_capability(model, "structured_outputs", result)
+            
+            result
+          end
+
+          sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Array[String]) }
+          def self.validate_compatibility(schema)
+            issues = []
+
+            # Check for deeply nested objects (Gemini has depth limits)
+            depth = calculate_depth(schema)
+            if depth > 5
+              issues << "Schema depth (#{depth}) exceeds recommended limit of 5 levels"
+            end
+
+            issues
+          end
+
+          private
+
+          sig { params(dspy_schema: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+          def self.convert_dspy_schema_to_gemini(dspy_schema)
+            result = {
+              type: "object",
+              properties: {},
+              required: []
+            }
+
+            # Convert properties
+            properties = dspy_schema[:properties] || {}
+            properties.each do |prop_name, prop_schema|
+              result[:properties][prop_name] = convert_property_to_gemini(prop_schema)
+            end
+
+            # Set required fields
+            result[:required] = (dspy_schema[:required] || []).map(&:to_s)
+
+            result
+          end
+
+          sig { params(property_schema: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+          def self.convert_property_to_gemini(property_schema)
+            case property_schema[:type]
+            when "string"
+              result = { type: "string" }
+              result[:enum] = property_schema[:enum] if property_schema[:enum]
+              result
+            when "integer"
+              { type: "integer" }
+            when "number"
+              { type: "number" }
+            when "boolean"
+              { type: "boolean" }
+            when "array"
+              {
+                type: "array",
+                items: convert_property_to_gemini(property_schema[:items] || { type: "string" })
+              }
+            when "object"
+              result = { type: "object" }
+              
+              if property_schema[:properties]
+                result[:properties] = {}
+                property_schema[:properties].each do |nested_prop, nested_schema|
+                  result[:properties][nested_prop] = convert_property_to_gemini(nested_schema)
+                end
+                
+                # Set required fields for nested objects
+                if property_schema[:required]
+                  result[:required] = property_schema[:required].map(&:to_s)
+                end
+              end
+              
+              result
+            else
+              # Default to string for unknown types
+              { type: "string" }
+            end
+          end
+
+          sig { params(schema: T::Hash[Symbol, T.untyped], current_depth: Integer).returns(Integer) }
+          def self.calculate_depth(schema, current_depth = 0)
+            return current_depth unless schema.is_a?(Hash)
+
+            max_depth = current_depth
+
+            # Check properties
+            if schema[:properties].is_a?(Hash)
+              schema[:properties].each_value do |prop|
+                if prop.is_a?(Hash)
+                  prop_depth = calculate_depth(prop, current_depth + 1)
+                  max_depth = [max_depth, prop_depth].max
+                end
+              end
+            end
+
+            # Check array items
+            if schema[:items].is_a?(Hash)
+              items_depth = calculate_depth(schema[:items], current_depth + 1)
+              max_depth = [max_depth, items_depth].max
+            end
+
+            max_depth
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -7,10 +7,12 @@ require_relative '../vision_models'
 module DSPy
   class LM
     class GeminiAdapter < Adapter
-      def initialize(model:, api_key:)
-        super
+      def initialize(model:, api_key:, structured_outputs: false)
+        super(model: model, api_key: api_key)
         validate_api_key!(api_key, 'gemini')
         
+        @structured_outputs_enabled = structured_outputs
+        
         @client = Gemini.new(
           credentials: {
             service: 'generative-language-api',

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "base_strategy"
+require_relative "../adapters/gemini/schema_converter"
+
+module DSPy
+  class LM
+    module Strategies
+      # Strategy for using Gemini's native structured output feature
+      class GeminiStructuredOutputStrategy < BaseStrategy
+        extend T::Sig
+
+        sig { override.returns(T::Boolean) }
+        def available?
+          # Check if adapter is Gemini and supports structured outputs
+          return false unless adapter.is_a?(DSPy::LM::GeminiAdapter)
+          return false unless adapter.instance_variable_get(:@structured_outputs_enabled)
+          
+          DSPy::LM::Adapters::Gemini::SchemaConverter.supports_structured_outputs?(adapter.model)
+        end
+
+        sig { override.returns(Integer) }
+        def priority
+          100 # Highest priority - native structured outputs are most reliable
+        end
+
+        sig { override.returns(String) }
+        def name
+          "gemini_structured_output"
+        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 to Gemini schema format
+          schema = DSPy::LM::Adapters::Gemini::SchemaConverter.to_gemini_format(signature_class)
+          
+          # Add generation_config for structured output
+          request_params[:generation_config] = {
+            response_mime_type: "application/json",
+            response_schema: schema
+          }
+        end
+
+        sig { override.params(response: DSPy::LM::Response).returns(T.nilable(String)) }
+        def extract_json(response)
+          # With Gemini structured outputs, the response should already be valid JSON
+          # Just return the content as-is
+          response.content
+        end
+
+        sig { override.params(error: StandardError).returns(T::Boolean) }
+        def handle_error(error)
+          # Handle Gemini-specific structured output errors
+          error_msg = error.message.to_s.downcase
+          if error_msg.include?("schema") || error_msg.include?("generation_config") || error_msg.include?("response_schema")
+            # Log the error and return true to indicate we handled it
+            # This allows fallback to another strategy
+            DSPy.logger.warn("Gemini structured output failed: #{error.message}")
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dspy/lm/strategy_selector.rb

@@ -5,6 +5,7 @@ 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/gemini_structured_output_strategy"
 require_relative "strategies/enhanced_prompting_strategy"
 
 module DSPy
@@ -13,11 +14,23 @@ module DSPy
     class StrategySelector
       extend T::Sig
 
+      # Strategy names enum for type safety
+      class StrategyName < T::Enum
+        enums do
+          OpenAIStructuredOutput = new('openai_structured_output')
+          AnthropicToolUse = new('anthropic_tool_use')  
+          AnthropicExtraction = new('anthropic_extraction')
+          GeminiStructuredOutput = new('gemini_structured_output')
+          EnhancedPrompting = new('enhanced_prompting')
+        end
+      end
+
       # Available strategies in order of registration
       STRATEGIES = [
         Strategies::OpenAIStructuredOutputStrategy,
         Strategies::AnthropicToolUseStrategy,
         Strategies::AnthropicExtractionStrategy,
+        Strategies::GeminiStructuredOutputStrategy,
         Strategies::EnhancedPromptingStrategy
       ].freeze
 
@@ -38,7 +51,7 @@ module DSPy
           
           # If strict strategy not available, fall back to compatible for Strict preference
           if is_strict_preference?(DSPy.config.structured_outputs.strategy)
-            compatible_strategy = find_strategy_by_name("enhanced_prompting")
+            compatible_strategy = find_strategy_by_name(StrategyName::EnhancedPrompting)
             return compatible_strategy if compatible_strategy&.available?
           end
           
@@ -65,7 +78,7 @@ module DSPy
       end
 
       # Check if a specific strategy is available
-      sig { params(strategy_name: String).returns(T::Boolean) }
+      sig { params(strategy_name: StrategyName).returns(T::Boolean) }
       def strategy_available?(strategy_name)
         strategy = find_strategy_by_name(strategy_name)
         strategy&.available? || false
@@ -82,7 +95,7 @@ module DSPy
           select_provider_optimized_strategy
         when DSPy::Strategy::Compatible
           # Use enhanced prompting
-          find_strategy_by_name("enhanced_prompting")
+          find_strategy_by_name(StrategyName::EnhancedPrompting)
         else
           nil
         end
@@ -98,15 +111,19 @@ module DSPy
       sig { returns(T.nilable(Strategies::BaseStrategy)) }
       def select_provider_optimized_strategy
         # Try OpenAI structured output first
-        openai_strategy = find_strategy_by_name("openai_structured_output")
+        openai_strategy = find_strategy_by_name(StrategyName::OpenAIStructuredOutput)
         return openai_strategy if openai_strategy&.available?
         
+        # Try Gemini structured output
+        gemini_strategy = find_strategy_by_name(StrategyName::GeminiStructuredOutput)
+        return gemini_strategy if gemini_strategy&.available?
+        
         # Try Anthropic tool use first
-        anthropic_tool_strategy = find_strategy_by_name("anthropic_tool_use")
+        anthropic_tool_strategy = find_strategy_by_name(StrategyName::AnthropicToolUse)
         return anthropic_tool_strategy if anthropic_tool_strategy&.available?
         
         # Fall back to Anthropic extraction
-        anthropic_strategy = find_strategy_by_name("anthropic_extraction")
+        anthropic_strategy = find_strategy_by_name(StrategyName::AnthropicExtraction)
         return anthropic_strategy if anthropic_strategy&.available?
         
         # No provider-specific strategy available
@@ -118,9 +135,9 @@ module DSPy
         STRATEGIES.map { |klass| klass.new(@adapter, @signature_class) }
       end
 
-      sig { params(name: String).returns(T.nilable(Strategies::BaseStrategy)) }
+      sig { params(name: StrategyName).returns(T.nilable(Strategies::BaseStrategy)) }
       def find_strategy_by_name(name)
-        @strategies.find { |s| s.name == name }
+        @strategies.find { |s| s.name == name.serialize }
       end
     end
   end

data/lib/dspy/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.26.1
+  version: 0.27.1
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
 bindir: bin
 cert_chain: []
-date: 2025-09-10 00:00:00.000000000 Z
+date: 2025-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -207,6 +207,7 @@ files:
 - lib/dspy/lm/adapter.rb
 - lib/dspy/lm/adapter_factory.rb
 - lib/dspy/lm/adapters/anthropic_adapter.rb
+- lib/dspy/lm/adapters/gemini/schema_converter.rb
 - lib/dspy/lm/adapters/gemini_adapter.rb
 - lib/dspy/lm/adapters/ollama_adapter.rb
 - lib/dspy/lm/adapters/openai/schema_converter.rb
@@ -221,6 +222,7 @@ files:
 - 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/gemini_structured_output_strategy.rb
 - lib/dspy/lm/strategies/openai_structured_output_strategy.rb
 - lib/dspy/lm/strategy_selector.rb
 - lib/dspy/lm/structured_output_strategy.rb