dspy 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '080e190ff2991ff97869bad95117f30a9e17a79b264285e1f122b1de6df4bbaf'
-  data.tar.gz: d3b47ff7e835a22111466e9c3e9a3be445e0a39c77a18c109482814c2804104e
+  metadata.gz: 44cf35be07e90187237ccdc79533d0ca76dbe2cb1040f0e841bff69afd7e71fc
+  data.tar.gz: 443a4d5dafe1fc7c90335e2b6294a4b1e1dd77b77cb24c19c7f8237f1824b2d0
 SHA512:
-  metadata.gz: 2aa3f3222b7e8c2039003e7acf724f32c9c5b5ad45d226fd93e74d2ca484a1be5332be96058b30ff1a5509e702ad4321dd9e1194b273820c897492277356efcc
-  data.tar.gz: 592266d28de856aad7da0481b62bf3ad9a6ce7ac06013ea1c8c980b1dc964267a3d85a930db8945a516f1265a0c0a38dbbf27206d1243eda7cf4a978468f0754
+  metadata.gz: 6e2e2e6098773c599190e0ab5e43ecd883e04359268557f28b0350219b98995c8fbe6633db2a5d1a34be1d250ae10ce05cd4aaaebefd6c13f5e855fcf587b5ef
+  data.tar.gz: b14760bb9cf7075991fdfc274bab60e1d55a4547a8b0da2b78c37bb76c69c4963a899f8ab26f26612210957f6184999b769adc590f90bd60714f992ab1c20230

data/README.md

@@ -2,12 +2,17 @@
 
 [![Gem Version](https://img.shields.io/gem/v/dspy)](https://rubygems.org/gems/dspy)
 [![Total Downloads](https://img.shields.io/gem/dt/dspy)](https://rubygems.org/gems/dspy)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/vicentereig/dspy.rb/ruby.yml?branch=main&label=build)](https://github.com/vicentereig/dspy.rb/actions/workflows/ruby.yml)
+[![Documentation](https://img.shields.io/badge/docs-vicentereig.github.io%2Fdspy.rb-blue)](https://vicentereig.github.io/dspy.rb/)
 
 **Build reliable LLM applications in Ruby using composable, type-safe modules.**
 
-DSPy.rb brings structured LLM programming to Ruby developers. Instead of wrestling with prompt strings and parsing responses, you define typed signatures and compose them into pipelines that just work.
+DSPy.rb brings structured LLM programming to Ruby developers. Instead of wrestling with prompt strings and parsing 
+responses, you define typed signatures and compose them into pipelines that just work.
 
-Traditional prompting is like writing code with string concatenation: it works until it doesn't. DSPy.rb brings you the programming approach pioneered by [dspy.ai](https://dspy.ai/): instead of crafting fragile prompts, you define modular signatures and let the framework handle the messy details.
+Traditional prompting is like writing code with string concatenation: it works until it doesn't. DSPy.rb brings you 
+the programming approach pioneered by [dspy.ai](https://dspy.ai/): instead of crafting fragile prompts, you define modular 
+signatures and let the framework handle the messy details.
 
 The result? LLM applications that actually scale and don't break when you sneeze.
 
@@ -54,18 +59,18 @@ puts result.confidence   # => 0.85
 ## What You Get
 
 **Core Building Blocks:**
-- **Signatures** - Define input/output schemas using Sorbet types
-- **Predict** - Basic LLM completion with structured data
-- **Chain of Thought** - Step-by-step reasoning for complex problems
-- **ReAct** - Tool-using agents with basic tool integration
+- **Signatures** - Define input/output schemas using Sorbet types with T::Enum and union type support
+- **Predict** - LLM completion with structured data extraction and multimodal support
+- **Chain of Thought** - Step-by-step reasoning for complex problems with automatic prompt optimization
+- **ReAct** - Tool-using agents with type-safe tool definitions and error recovery
 - **CodeAct** - Dynamic code execution agents for programming tasks
-- **Manual Composition** - Combine multiple LLM calls into workflows
+- **Module Composition** - Combine multiple LLM calls into production-ready workflows
 
 **Optimization & Evaluation:**
 - **Prompt Objects** - Manipulate prompts as first-class objects instead of strings
 - **Typed Examples** - Type-safe training data with automatic validation
-- **Evaluation Framework** - Basic testing with simple metrics
-- **Basic Optimization** - Simple prompt optimization techniques
+- **Evaluation Framework** - Advanced metrics beyond simple accuracy with error-resilient pipelines
+- **MIPROv2 Optimization** - Automatic prompt optimization with storage and persistence
 
 **Production Features:**
 - **Reliable JSON Extraction** - Native OpenAI structured outputs, Anthropic extraction patterns, and automatic strategy selection with fallback
@@ -78,28 +83,64 @@ puts result.confidence   # => 0.85
 
 **Developer Experience:**
 - 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/)
+  - [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
+  - [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
 - Type-safe tool definitions for ReAct agents
 - Comprehensive instrumentation and observability
 
 ## Development Status
 
-DSPy.rb is actively developed and approaching stability at **v0.15.4**. 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. 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!
 
+## Documentation
+
+📖 **[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
+- **[Core Concepts](docs/src/getting-started/core-concepts.md)** - Understanding signatures, predictors, and modules
+
+### Core Features
+- **[Signatures & Types](docs/src/core-concepts/signatures.md)** - Define typed interfaces for LLM operations
+- **[Predictors](docs/src/core-concepts/predictors.md)** - Predict, ChainOfThought, ReAct, and more
+- **[Modules & Pipelines](docs/src/core-concepts/modules.md)** - Compose complex multi-stage workflows
+- **[Multimodal Support](docs/src/core-concepts/multimodal.md)** - Image analysis with vision-capable models
+- **[Examples & Validation](docs/src/core-concepts/examples.md)** - Type-safe training data
+
+### Optimization
+- **[Evaluation Framework](docs/src/optimization/evaluation.md)** - Advanced metrics beyond simple accuracy
+- **[Prompt Optimization](docs/src/optimization/prompt-optimization.md)** - Manipulate prompts as objects
+- **[MIPROv2 Optimizer](docs/src/optimization/miprov2.md)** - Automatic optimization algorithms
+
+### Production Features
+- **[Storage System](docs/src/production/storage.md)** - Persistence and optimization result storage
+- **[Observability](docs/src/production/observability.md)** - Zero-config Langfuse integration and structured logging
+
+### Advanced Usage
+- **[Complex Types](docs/src/advanced/complex-types.md)** - Sorbet type integration with automatic coercion for structs, enums, and arrays
+- **[Manual Pipelines](docs/src/advanced/pipelines.md)** - Manual module composition patterns
+- **[RAG Patterns](docs/src/advanced/rag.md)** - Manual RAG implementation with external services
+- **[Custom Metrics](docs/src/advanced/custom-metrics.md)** - Proc-based evaluation logic
+
 ## Quick Start
 
 ### Installation
 
-```ruby
-gem 'dspy', '~> 0.15'
-```
-
-Or add to your Gemfile:
+Add to your Gemfile:
 
 ```ruby
 gem 'dspy'
@@ -135,68 +176,51 @@ sudo apt-get install cmake
 
 **Note**: The `polars-df` gem compilation can take 15-20 minutes. Pre-built binaries are available for most platforms, so compilation is only needed if a pre-built binary isn't available for your system.
 
-## Documentation
-
-📖 **[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
-- **[Core Concepts](docs/src/getting-started/core-concepts.md)** - Understanding signatures, predictors, and modules
-
-### Core Features
-- **[Signatures & Types](docs/src/core-concepts/signatures.md)** - Define typed interfaces for LLM operations
-- **[Predictors](docs/src/core-concepts/predictors.md)** - Predict, ChainOfThought, ReAct, and more
-- **[Modules & Pipelines](docs/src/core-concepts/modules.md)** - Compose complex multi-stage workflows
-- **[Examples & Validation](docs/src/core-concepts/examples.md)** - Type-safe training data
-
-### Optimization
-- **[Evaluation Framework](docs/src/optimization/evaluation.md)** - Basic testing with simple metrics
-- **[Prompt Optimization](docs/src/optimization/prompt-optimization.md)** - Manipulate prompts as objects
-- **[MIPROv2 Optimizer](docs/src/optimization/miprov2.md)** - Basic automatic optimization
-
-### Production Features
-- **[Storage System](docs/src/production/storage.md)** - Basic file-based persistence
-- **[Observability](docs/src/production/observability.md)** - Zero-config Langfuse integration and structured logging
-
-### Advanced Usage
-- **[Complex Types](docs/src/advanced/complex-types.md)** - Sorbet type integration with automatic coercion for structs, enums, and arrays
-- **[Manual Pipelines](docs/src/advanced/pipelines.md)** - Manual module composition patterns
-- **[RAG Patterns](docs/src/advanced/rag.md)** - Manual RAG implementation with external services
-- **[Custom Metrics](docs/src/advanced/custom-metrics.md)** - Proc-based evaluation logic
-
 ## Recent Achievements
 
 DSPy.rb has rapidly evolved from experimental to production-ready:
 
-- ✅ **JSON Parsing Reliability** (v0.8.0) - Native OpenAI structured outputs, strategy selection, retry logic
-- ✅ **Type-Safe Strategy Configuration** (v0.9.0) - Provider-optimized automatic strategy selection  
-- ✅ **Documentation Website** (v0.6.4) - Comprehensive docs at [vicentereig.github.io/dspy.rb](https://vicentereig.github.io/dspy.rb)
+### Foundation
+- ✅ **JSON Parsing Reliability** - Native OpenAI structured outputs, strategy selection, retry logic
+- ✅ **Type-Safe Strategy Configuration** - Provider-optimized automatic strategy selection  
+- ✅ **Core Module System** - Predict, ChainOfThought, ReAct, CodeAct with type safety
 - ✅ **Production Observability** - OpenTelemetry, New Relic, and Langfuse integration
 - ✅ **Optimization Framework** - MIPROv2 algorithm with storage & persistence
-- ✅ **Core Module System** - Predict, ChainOfThought, ReAct, CodeAct with type safety
 
-## Roadmap - Battle-Testing Toward v1.0
+### Recent Advances  
+- ✅ **Comprehensive Multimodal Framework** - Complete image analysis with `DSPy::Image`, type-safe bounding boxes, vision model integration
+- ✅ **Advanced Type System** - `T::Enum` integration, union types for agentic workflows, complex type coercion
+- ✅ **Production-Ready Evaluation** - Multi-factor metrics beyond accuracy, error-resilient evaluation pipelines
+- ✅ **Documentation Ecosystem** - `llms.txt` for AI assistants, ADRs, blog articles, comprehensive examples
+- ✅ **API Maturation** - Simplified idiomatic patterns, better error handling, production-proven designs
 
-DSPy.rb is currently at **v0.15.2** and approaching stability. I'm focusing on real-world usage and refinement through the 0.16+ series before committing to a stable v1.0 API.
+## Roadmap - Production Battle-Testing Toward v1.0
+
+DSPy.rb has transitioned from **feature building** to **production validation**. The core framework is
+feature-complete and stable - now I'm focusing on real-world usage patterns, performance optimization, 
+and ecosystem integration.
 
 **Current Focus Areas:**
-- ✅ **Ollama Support** - Local model integration (completed in v0.15.0)
-- ✅ **Agentic Memory** - Persistent agent state management with Memory module
-- 🚧 **Google Gemini Support** - Integration with Gemini models (#52)
-- 🚧 **Context Engineering** - Advanced prompt optimization techniques
-- 🚧 **MCP Support** - Model Context Protocol integration
-- 🚧 **Additional Optimizer Support** - Expanding teleprompt capabilities
-- 🚧 **Performance Optimization** - Based on production usage patterns
+
+### Production Readiness
+- 🚧 **Production Patterns** - Real-world usage validation and performance optimization
+- 🚧 **Ruby Ecosystem Integration** - Rails integration, Sidekiq compatibility, deployment patterns
+- 🚧 **Scale Testing** - High-volume usage, memory management, connection pooling
+- 🚧 **Error Recovery** - Robust failure handling patterns for production environments
+
+### Ecosystem Expansion  
+- 🚧 **Model Context Protocol (MCP)** - Integration with MCP ecosystem
+- 🚧 **Additional Provider Support** - Google Gemini, Azure OpenAI, local models beyond Ollama
+- 🚧 **Tool Ecosystem** - Expanded tool integrations for ReAct agents
+
+### Community & Adoption
+- 🚧 **Community Examples** - Real-world applications and case studies
+- 🚧 **Contributor Experience** - Making it easier to contribute and extend
+- 🚧 **Performance Benchmarks** - Comparative analysis vs other frameworks
 
 **v1.0 Philosophy:** 
-v1.0 will be released after extensive production battle-testing, not after checking off features. This ensures a stable, reliable API backed by real-world validation.
+v1.0 will be released after extensive production battle-testing, not after checking off features. 
+The API is already stable - v1.0 represents confidence in production reliability backed by real-world validation.
 
 ## License
 

data/lib/dspy/chain_of_thought.rb

@@ -25,6 +25,7 @@ module DSPy
       @signature_class = enhanced_signature
     end
 
+
     # Override prompt-based methods to maintain ChainOfThought behavior
     sig { override.params(new_prompt: Prompt).returns(ChainOfThought) }
     def with_prompt(new_prompt)

data/lib/dspy/code_act.rb

@@ -129,8 +129,16 @@ module DSPy
         # Use the enhanced output struct with CodeAct fields
         @output_struct_class = enhanced_output_struct
 
+        # Store original signature name
+        @original_signature_name = signature_class.name
+
         class << self
-          attr_reader :input_struct_class, :output_struct_class
+          attr_reader :input_struct_class, :output_struct_class, :original_signature_name
+          
+          # Override name to return the original signature name
+          def name
+            @original_signature_name || super
+          end
         end
       end
 
@@ -140,8 +148,6 @@ module DSPy
 
     sig { params(kwargs: T.untyped).returns(T.untyped).override }
     def forward(**kwargs)
-      lm = config.lm || DSPy.config.lm
-
       # Validate input and serialize all fields as task context
       input_struct = @original_signature_class.input_struct_class.new(**kwargs)
       task = DSPy::TypeSerializer.serialize(input_struct).to_json

data/lib/dspy/image.rb

@@ -19,6 +19,10 @@ module DSPy
       'anthropic' => {
         sources: %w[base64 data], 
         parameters: []
+      },
+      'gemini' => {
+        sources: %w[base64 data], # Gemini supports inline base64 data, not URLs
+        parameters: []
       }
     }.freeze
     
@@ -99,6 +103,27 @@ module DSPy
       end
     end
     
+    def to_gemini_format
+      if url
+        # Gemini requires base64 for inline data, URLs not supported for inline_data
+        raise NotImplementedError, "URL fetching for Gemini not yet implemented. Use base64 or data instead."
+      elsif base64
+        {
+          inline_data: {
+            mime_type: content_type,
+            data: base64
+          }
+        }
+      elsif data
+        {
+          inline_data: {
+            mime_type: content_type,
+            data: to_base64
+          }
+        }
+      end
+    end
+    
     def to_base64
       return base64 if base64
       return Base64.strict_encode64(data.pack('C*')) if data
@@ -139,6 +164,11 @@ module DSPy
             raise DSPy::LM::IncompatibleImageFeatureError,
                   "Anthropic doesn't support image URLs. Please provide base64 or raw data instead."
           end
+        when 'gemini'
+          if current_source == 'url'
+            raise DSPy::LM::IncompatibleImageFeatureError,
+                  "Gemini doesn't support image URLs for inline data. Please provide base64 or raw data instead."
+          end
         end
       end
       
@@ -148,6 +178,9 @@ module DSPy
         when 'anthropic'
           raise DSPy::LM::IncompatibleImageFeatureError,
                 "Anthropic doesn't support the 'detail' parameter. This feature is OpenAI-specific."
+        when 'gemini'
+          raise DSPy::LM::IncompatibleImageFeatureError,
+                "Gemini doesn't support the 'detail' parameter. This feature is OpenAI-specific."
         end
       end
     end

data/lib/dspy/lm/adapter_factory.rb

@@ -8,7 +8,8 @@ module DSPy
       ADAPTER_MAP = {
         'openai' => 'OpenAIAdapter',
         'anthropic' => 'AnthropicAdapter',
-        'ollama' => 'OllamaAdapter'
+        'ollama' => 'OllamaAdapter',
+        'gemini' => 'GeminiAdapter'
       }.freeze
 
       class << self

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

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require 'gemini-ai'
+require 'json'
+require_relative '../vision_models'
+
+module DSPy
+  class LM
+    class GeminiAdapter < Adapter
+      def initialize(model:, api_key:)
+        super
+        validate_api_key!(api_key, 'gemini')
+        
+        @client = Gemini.new(
+          credentials: {
+            service: 'generative-language-api',
+            api_key: api_key
+          },
+          options: { 
+            model: model,
+            server_sent_events: true
+          }
+        )
+      end
+
+      def chat(messages:, signature: nil, **extra_params, &block)
+        normalized_messages = normalize_messages(messages)
+        
+        # Validate vision support if images are present
+        if contains_images?(normalized_messages)
+          VisionModels.validate_vision_support!('gemini', model)
+          # Convert messages to Gemini format with proper image handling
+          normalized_messages = format_multimodal_messages(normalized_messages)
+        end
+        
+        # Convert DSPy message format to Gemini format
+        gemini_messages = convert_messages_to_gemini_format(normalized_messages)
+        
+        request_params = {
+          contents: gemini_messages
+        }.merge(extra_params)
+
+        begin
+          # Always use streaming
+          content = ""
+          final_response_data = nil
+          
+          @client.stream_generate_content(request_params) do |chunk|
+            # Handle case where chunk might be a string (from SSE VCR)
+            if chunk.is_a?(String)
+              begin
+                chunk = JSON.parse(chunk)
+              rescue JSON::ParserError => e
+                raise AdapterError, "Failed to parse Gemini streaming response: #{e.message}"
+              end
+            end
+            
+            # Extract content from chunks
+            if chunk.dig('candidates', 0, 'content', 'parts')
+              chunk_text = extract_text_from_parts(chunk.dig('candidates', 0, 'content', 'parts'))
+              content += chunk_text
+              
+              # Call block only if provided (for real streaming)
+              block.call(chunk) if block_given?
+            end
+            
+            # Store final response data (usage, metadata) from last chunk
+            if chunk['usageMetadata'] || chunk.dig('candidates', 0, 'finishReason')
+              final_response_data = chunk
+            end
+          end
+          
+          # Extract usage information from final chunk
+          usage_data = final_response_data&.dig('usageMetadata')
+          usage_struct = usage_data ? UsageFactory.create('gemini', usage_data) : nil
+          
+          # Create metadata from final chunk
+          metadata = {
+            provider: 'gemini',
+            model: model,
+            finish_reason: final_response_data&.dig('candidates', 0, 'finishReason'),
+            safety_ratings: final_response_data&.dig('candidates', 0, 'safetyRatings'),
+            streaming: block_given?
+          }
+          
+          # Create typed metadata
+          typed_metadata = ResponseMetadataFactory.create('gemini', metadata)
+          
+          Response.new(
+            content: content,
+            usage: usage_struct,
+            metadata: typed_metadata
+          )
+        rescue => e
+          handle_gemini_error(e)
+        end
+      end
+
+      private
+
+      # Convert DSPy message format to Gemini format
+      def convert_messages_to_gemini_format(messages)
+        # Gemini expects contents array with role and parts
+        messages.map do |msg|
+          role = case msg[:role]
+                 when 'system'
+                   'user' # Gemini doesn't have explicit system role, merge with user
+                 when 'assistant'
+                   'model'
+                 else
+                   msg[:role]
+                 end
+          
+          if msg[:content].is_a?(Array)
+            # Multimodal content
+            parts = msg[:content].map do |item|
+              case item[:type]
+              when 'text'
+                { text: item[:text] }
+              when 'image'
+                item[:image].to_gemini_format
+              else
+                item
+              end
+            end
+            
+            { role: role, parts: parts }
+          else
+            # Text-only content
+            { role: role, parts: [{ text: msg[:content] }] }
+          end
+        end
+      end
+      
+      # Extract text content from Gemini parts array
+      def extract_text_from_parts(parts)
+        return "" unless parts.is_a?(Array)
+        
+        parts.map { |part| part['text'] }.compact.join
+      end
+      
+      # Format multimodal messages for Gemini
+      def format_multimodal_messages(messages)
+        messages.map do |msg|
+          if msg[:content].is_a?(Array)
+            # Convert multimodal content to Gemini format
+            formatted_content = msg[:content].map do |item|
+              case item[:type]
+              when 'text'
+                { type: 'text', text: item[:text] }
+              when 'image'
+                # Validate image compatibility before formatting
+                item[:image].validate_for_provider!('gemini')
+                item[:image].to_gemini_format
+              else
+                item
+              end
+            end
+            
+            {
+              role: msg[:role],
+              content: formatted_content
+            }
+          else
+            msg
+          end
+        end
+      end
+      
+      # Handle Gemini-specific errors
+      def handle_gemini_error(error)
+        error_msg = error.message.to_s
+        
+        if error_msg.include?('API_KEY') || error_msg.include?('status 400') || error_msg.include?('status 401') || error_msg.include?('status 403')
+          raise AdapterError, "Gemini authentication failed: #{error_msg}. Check your API key."
+        elsif error_msg.include?('RATE_LIMIT') || error_msg.downcase.include?('quota') || error_msg.include?('status 429')
+          raise AdapterError, "Gemini rate limit exceeded: #{error_msg}. Please wait and try again."
+        elsif error_msg.include?('SAFETY') || error_msg.include?('blocked')
+          raise AdapterError, "Gemini content was blocked by safety filters: #{error_msg}"
+        elsif error_msg.include?('image') || error_msg.include?('media')
+          raise AdapterError, "Gemini image processing failed: #{error_msg}. Ensure your image is a valid format and under size limits."
+        else
+          # Generic error handling
+          raise AdapterError, "Gemini adapter error: #{error_msg}"
+        end
+      end
+    end
+  end
+end

data/lib/dspy/lm/response.rb

@@ -84,13 +84,42 @@ module DSPy
       end
     end
     
+    # Gemini-specific metadata with additional fields
+    class GeminiResponseMetadata < T::Struct
+      extend T::Sig
+      
+      const :provider, String
+      const :model, String
+      const :response_id, T.nilable(String), default: nil
+      const :created, T.nilable(Integer), default: nil
+      const :structured_output, T.nilable(T::Boolean), default: nil
+      const :finish_reason, T.nilable(String), default: nil
+      const :safety_ratings, T.nilable(T::Array[T::Hash[String, T.untyped]]), default: nil
+      const :streaming, T.nilable(T::Boolean), default: nil
+      
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h
+        hash = {
+          provider: provider,
+          model: model
+        }
+        hash[:response_id] = response_id if response_id
+        hash[:created] = created if created
+        hash[:structured_output] = structured_output unless structured_output.nil?
+        hash[:finish_reason] = finish_reason if finish_reason
+        hash[:safety_ratings] = safety_ratings if safety_ratings
+        hash[:streaming] = streaming unless streaming.nil?
+        hash
+      end
+    end
+    
     # Normalized response format for all LM providers
     class Response < T::Struct
       extend T::Sig
       
       const :content, String
       const :usage, T.nilable(T.any(Usage, OpenAIUsage)), default: nil
-      const :metadata, T.any(ResponseMetadata, OpenAIResponseMetadata, AnthropicResponseMetadata, T::Hash[Symbol, T.untyped])
+      const :metadata, T.any(ResponseMetadata, OpenAIResponseMetadata, AnthropicResponseMetadata, GeminiResponseMetadata, T::Hash[Symbol, T.untyped])
       
       sig { returns(String) }
       def to_s
@@ -112,7 +141,7 @@ module DSPy
     module ResponseMetadataFactory
       extend T::Sig
       
-      sig { params(provider: String, metadata: T.nilable(T::Hash[Symbol, T.untyped])).returns(T.any(ResponseMetadata, OpenAIResponseMetadata, AnthropicResponseMetadata)) }
+      sig { params(provider: String, metadata: T.nilable(T::Hash[Symbol, T.untyped])).returns(T.any(ResponseMetadata, OpenAIResponseMetadata, AnthropicResponseMetadata, GeminiResponseMetadata)) }
       def self.create(provider, metadata)
         # Handle nil metadata
         metadata ||= {}
@@ -123,7 +152,7 @@ module DSPy
         # Extract common fields
         common_fields = {
           provider: provider,
-          model: metadata[:model] || 'unknown',
+          model: metadata[:model],
           response_id: metadata[:response_id] || metadata[:id],
           created: metadata[:created],
           structured_output: metadata[:structured_output]
@@ -143,6 +172,13 @@ module DSPy
             stop_sequence: metadata[:stop_sequence]&.to_s,
             tool_calls: metadata[:tool_calls]
           )
+        when 'gemini'
+          GeminiResponseMetadata.new(
+            **common_fields,
+            finish_reason: metadata[:finish_reason]&.to_s,
+            safety_ratings: metadata[:safety_ratings],
+            streaming: metadata[:streaming]
+          )
         else
           ResponseMetadata.new(**common_fields)
         end
@@ -151,7 +187,7 @@ module DSPy
         # Fallback to basic metadata
         ResponseMetadata.new(
           provider: provider,
-          model: metadata[:model] || 'unknown'
+          model: metadata[:model]
         )
       end
     end

data/lib/dspy/lm/usage.rb

@@ -72,6 +72,8 @@ module DSPy
           create_openai_usage(normalized)
         when 'anthropic'
           create_anthropic_usage(normalized)
+        when 'gemini'
+          create_gemini_usage(normalized)
         else
           create_generic_usage(normalized)
         end
@@ -136,6 +138,23 @@ module DSPy
         nil
       end
       
+      sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.nilable(Usage)) }
+      def self.create_gemini_usage(data)
+        # Gemini uses promptTokenCount/candidatesTokenCount/totalTokenCount
+        input_tokens = data[:promptTokenCount] || data[:input_tokens] || 0
+        output_tokens = data[:candidatesTokenCount] || data[:output_tokens] || 0
+        total_tokens = data[:totalTokenCount] || data[:total_tokens] || (input_tokens + output_tokens)
+        
+        Usage.new(
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          total_tokens: total_tokens
+        )
+      rescue => e
+        DSPy.logger.debug("Failed to create Gemini usage: #{e.message}")
+        nil
+      end
+      
       sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.nilable(Usage)) }
       def self.create_generic_usage(data)
         # Generic fallback

data/lib/dspy/lm/vision_models.rb

@@ -26,12 +26,35 @@ module DSPy
         'claude-3-5-haiku-20241022'
       ].freeze
       
+      # Gemini vision-capable models (all Gemini models support vision)
+      GEMINI_VISION_MODELS = [
+        # Gemini 2.5 series (2025)
+        'gemini-2.5-pro',
+        'gemini-2.5-flash',
+        'gemini-2.5-flash-lite',
+        # Gemini 2.0 series (2024-2025)
+        'gemini-2.0-flash',
+        'gemini-2.0-flash-experimental',
+        'gemini-2.0-flash-lite', 
+        'gemini-2.0-pro-experimental',
+        # Gemini 1.5 series
+        'gemini-1.5-pro',
+        'gemini-1.5-flash',
+        'gemini-1.5-pro-latest',
+        'gemini-1.5-flash-latest',
+        # Legacy models
+        'gemini-pro-vision',
+        'gemini-1.0-pro-vision'
+      ].freeze
+      
       def self.supports_vision?(provider, model)
         case provider.to_s.downcase
         when 'openai'
           OPENAI_VISION_MODELS.any? { |m| model.include?(m) }
         when 'anthropic'
           ANTHROPIC_VISION_MODELS.any? { |m| model.include?(m) }
+        when 'gemini'
+          GEMINI_VISION_MODELS.any? { |m| model.include?(m) }
         else
           false
         end
@@ -49,6 +72,8 @@ module DSPy
           OPENAI_VISION_MODELS
         when 'anthropic'
           ANTHROPIC_VISION_MODELS
+        when 'gemini'
+          GEMINI_VISION_MODELS
         else
           []
         end

data/lib/dspy/lm.rb

@@ -14,6 +14,7 @@ require_relative 'lm/adapter_factory'
 require_relative 'lm/adapters/openai_adapter'
 require_relative 'lm/adapters/anthropic_adapter'
 require_relative 'lm/adapters/ollama_adapter'
+require_relative 'lm/adapters/gemini_adapter'
 
 # Load strategy system
 require_relative 'lm/strategy_selector'
@@ -232,10 +233,10 @@ module DSPy
           usage = result.usage
           DSPy.log('span.attributes',
             span_id: DSPy::Context.current[:span_stack].last,
-            'gen_ai.response.model' => result.respond_to?(:model) ? result.model : nil,
-            'gen_ai.usage.prompt_tokens' => usage.respond_to?(:input_tokens) ? usage.input_tokens : nil,
-            'gen_ai.usage.completion_tokens' => usage.respond_to?(:output_tokens) ? usage.output_tokens : nil,
-            'gen_ai.usage.total_tokens' => usage.respond_to?(:total_tokens) ? usage.total_tokens : nil
+            'gen_ai.response.model' => result.metadata.model,
+            'gen_ai.usage.prompt_tokens' => usage.input_tokens,
+            'gen_ai.usage.completion_tokens' => usage.output_tokens,
+            'gen_ai.usage.total_tokens' => usage.total_tokens
           )
         end
         

data/lib/dspy/module.rb

@@ -49,10 +49,10 @@ module DSPy
       forward_untyped(**input_values)
     end
 
-    # Get the configured LM for this instance, falling back to global
+    # Get the configured LM for this instance, checking fiber-local context first
     sig { returns(T.untyped) }
     def lm
-      config.lm || DSPy.config.lm
+      config.lm || DSPy.current_lm
     end
   end
 end

data/lib/dspy/predict.rb

@@ -59,6 +59,42 @@ module DSPy
       @prompt = Prompt.from_signature(signature_class)
     end
 
+    # Reconstruct program from serialized hash
+    sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.attached_class) }
+    def self.from_h(data)
+      state = data[:state]
+      raise ArgumentError, "Missing state in serialized data" unless state
+
+      signature_class_name = state[:signature_class]
+      signature_class = Object.const_get(signature_class_name)
+      program = new(signature_class)
+      
+      # Restore instruction if available
+      if state[:instruction]
+        program = program.with_instruction(state[:instruction])
+      end
+      
+      # Restore examples if available
+      few_shot_examples = state[:few_shot_examples]
+      if few_shot_examples && !few_shot_examples.empty?
+        # Convert hash examples back to FewShotExample objects
+        examples = few_shot_examples.map do |ex|
+          if ex.is_a?(Hash)
+            DSPy::FewShotExample.new(
+              input: ex[:input],
+              output: ex[:output],
+              reasoning: ex[:reasoning]
+            )
+          else
+            ex
+          end
+        end
+        program = program.with_examples(examples)
+      end
+      
+      program
+    end
+
     # Backward compatibility methods - delegate to prompt object
     sig { returns(String) }
     def system_signature

data/lib/dspy/propose/grounded_proposer.rb

@@ -172,15 +172,35 @@ module DSPy
       sig { params(struct_class: T.class_of(T::Struct)).returns(T::Array[T::Hash[Symbol, T.untyped]]) }
       def extract_field_info(struct_class)
         struct_class.props.map do |name, prop_info|
-          {
+          field_info = {
             name: name,
             type: prop_info[:type].to_s,
             description: prop_info[:description] || "",
             required: !prop_info[:rules]&.any? { |rule| rule.is_a?(T::Props::NilableRules) }
           }
+          
+          # Extract enum values if this is an enum type
+          if enum_values = extract_enum_values(prop_info[:type])
+            field_info[:enum_values] = enum_values
+            field_info[:is_enum] = true
+          end
+          
+          field_info
+        end
+      end
+
+      # Extract enum values from a type if it's an enum
+      sig { params(type: T.untyped).returns(T.nilable(T::Array[String])) }
+      def extract_enum_values(type)
+        # Handle T::Enum types
+        if type.is_a?(Class) && type < T::Enum
+          type.values.map(&:serialize)
+        else
+          nil
         end
       end
 
+
       # Analyze patterns in training examples
       sig { params(examples: T::Array[T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
       def analyze_example_patterns(examples)
@@ -364,8 +384,12 @@ module DSPy
         context_parts << "Task: #{signature_class.description}" if @config.use_task_description
         
         if @config.use_input_output_analysis
-          context_parts << "Input fields: #{analysis[:input_fields].map { |f| "#{f[:name]} (#{f[:type]})" }.join(', ')}"
-          context_parts << "Output fields: #{analysis[:output_fields].map { |f| "#{f[:name]} (#{f[:type]})" }.join(', ')}"
+          # Build detailed field descriptions including enum values
+          input_descriptions = analysis[:input_fields].map { |f| format_field_description(f) }
+          output_descriptions = analysis[:output_fields].map { |f| format_field_description(f) }
+          
+          context_parts << "Input fields: #{input_descriptions.join(', ')}"
+          context_parts << "Output fields: #{output_descriptions.join(', ')}"
         end
         
         if analysis[:common_themes] && analysis[:common_themes].any?
@@ -379,6 +403,17 @@ module DSPy
         context_parts.join("\n")
       end
 
+      # Format field description with enum values if applicable
+      sig { params(field: T::Hash[Symbol, T.untyped]).returns(String) }
+      def format_field_description(field)
+        base = "#{field[:name]} (#{field[:type]})"
+        if field[:is_enum] && field[:enum_values] && !field[:enum_values].empty?
+          "#{base} [values: #{field[:enum_values].join(', ')}]"
+        else
+          base
+        end
+      end
+
       # Build requirements text for instruction generation
       sig { params(analysis: T::Hash[Symbol, T.untyped]).returns(String) }
       def build_requirements_text(analysis)

data/lib/dspy/re_act.rb

@@ -112,8 +112,16 @@ module DSPy
         # Use the enhanced output struct with ReAct fields
         @output_struct_class = enhanced_output_struct
 
+        # Store original signature name
+        @original_signature_name = signature_class.name
+
         class << self
-          attr_reader :input_struct_class, :output_struct_class
+          attr_reader :input_struct_class, :output_struct_class, :original_signature_name
+          
+          # Override name to return the original signature name
+          def name
+            @original_signature_name || super
+          end
         end
       end
 
@@ -123,9 +131,6 @@ module DSPy
 
     sig { params(kwargs: T.untyped).returns(T.untyped).override }
     def forward(**kwargs)
-      lm = config.lm || DSPy.config.lm
-      available_tools = @tools.keys
-
       # Validate input
       input_struct = @original_signature_class.input_struct_class.new(**kwargs)
 

data/lib/dspy/storage/program_storage.rb

@@ -90,18 +90,39 @@ module DSPy
 
         sig { params(program: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
         def serialize_program(program)
-          # Basic serialization - can be enhanced for specific program types
-          {
-            class_name: program.class.name,
-            state: extract_program_state(program)
-          }
+          # Basic serialization
+          if program.is_a?(Hash)
+            # Already serialized - return as-is to preserve state
+            program
+          else
+            # Real program object - serialize it
+            {
+              class_name: program.class.name,
+              state: extract_program_state(program)
+            }
+          end
         end
 
-        sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
+        sig { params(data: T.untyped).returns(T.untyped) }
         def self.deserialize_program(data)
-          # Basic deserialization - would need enhancement for complex programs
-          # For now, return the serialized state
-          data
+          # Ensure data is a Hash
+          unless data.is_a?(Hash)
+            raise ArgumentError, "Expected Hash for program data, got #{data.class.name}"
+          end
+          
+          # Get class name from the serialized data
+          class_name = data[:class_name]
+          raise ArgumentError, "Missing class_name in serialized data" unless class_name
+          
+          # Get the class constant
+          program_class = Object.const_get(class_name)
+          
+          # Use the class's from_h method
+          unless program_class.respond_to?(:from_h)
+            raise ArgumentError, "Class #{class_name} does not support deserialization (missing from_h method)"
+          end
+          
+          program_class.from_h(data)
         end
 
         sig { params(program: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
@@ -310,6 +331,20 @@ module DSPy
           { programs: [], summary: { total_programs: 0, avg_score: 0.0 } }
         end
         
+        # Extract signature class name from program object
+        unless saved_program.program.respond_to?(:signature_class)
+          raise ArgumentError, "Program #{saved_program.program.class.name} does not respond to signature_class method"
+        end
+        
+        signature_class_name = saved_program.program.signature_class.name
+        
+        if signature_class_name.nil? || signature_class_name.empty?
+          raise(
+            "Program #{saved_program.program.class.name} has a signature class that does not provide a name.\n" \
+            "Ensure the signature class responds to #name or that signature_class_name is stored in program state."
+          )
+        end
+        
         # Add or update program entry
         program_entry = {
           program_id: saved_program.program_id,
@@ -317,7 +352,7 @@ module DSPy
           best_score: saved_program.optimization_result[:best_score_value],
           score_name: saved_program.optimization_result[:best_score_name],
           optimizer: saved_program.optimization_result[:metadata]&.dig(:optimizer),
-          signature_class: saved_program.metadata[:signature_class],
+          signature_class: signature_class_name,
           metadata: saved_program.metadata
         }
         

data/lib/dspy/teleprompt/mipro_v2.rb

@@ -18,8 +18,13 @@ module DSPy
       module AutoMode
         extend T::Sig
 
-        sig { returns(MIPROv2) }
-        def self.light
+        sig do
+          params(
+            metric: T.nilable(T.proc.params(arg0: T.untyped, arg1: T.untyped).returns(T.untyped)),
+            kwargs: T.untyped
+          ).returns(MIPROv2)
+        end
+        def self.light(metric: nil, **kwargs)
           config = MIPROv2Config.new
           config.num_trials = 6
           config.num_instruction_candidates = 3
@@ -28,11 +33,16 @@ module DSPy
           config.bootstrap_sets = 3
           config.optimization_strategy = "greedy"
           config.early_stopping_patience = 2
-          MIPROv2.new(config: config)
+          MIPROv2.new(metric: metric, config: config, **kwargs)
         end
 
-        sig { returns(MIPROv2) }
-        def self.medium
+        sig do
+          params(
+            metric: T.nilable(T.proc.params(arg0: T.untyped, arg1: T.untyped).returns(T.untyped)),
+            kwargs: T.untyped
+          ).returns(MIPROv2)
+        end
+        def self.medium(metric: nil, **kwargs)
           config = MIPROv2Config.new
           config.num_trials = 12
           config.num_instruction_candidates = 5
@@ -41,11 +51,16 @@ module DSPy
           config.bootstrap_sets = 5
           config.optimization_strategy = "adaptive"
           config.early_stopping_patience = 3
-          MIPROv2.new(config: config)
+          MIPROv2.new(metric: metric, config: config, **kwargs)
         end
 
-        sig { returns(MIPROv2) }
-        def self.heavy
+        sig do
+          params(
+            metric: T.nilable(T.proc.params(arg0: T.untyped, arg1: T.untyped).returns(T.untyped)),
+            kwargs: T.untyped
+          ).returns(MIPROv2)
+        end
+        def self.heavy(metric: nil, **kwargs)
           config = MIPROv2Config.new
           config.num_trials = 18
           config.num_instruction_candidates = 8
@@ -54,7 +69,7 @@ module DSPy
           config.bootstrap_sets = 8
           config.optimization_strategy = "bayesian"
           config.early_stopping_patience = 5
-          MIPROv2.new(config: config)
+          MIPROv2.new(metric: metric, config: config, **kwargs)
         end
       end
 
@@ -736,12 +751,27 @@ module DSPy
           best_score_value: best_score,
           metadata: metadata,
           evaluated_candidates: @evaluated_candidates,
-          optimization_trace: optimization_result[:optimization_state] || {},
+          optimization_trace: serialize_optimization_trace(optimization_result[:optimization_state]),
           bootstrap_statistics: bootstrap_result.statistics,
           proposal_statistics: proposal_result.analysis
         )
       end
 
+      # Serialize optimization trace for better JSON output
+      sig { params(optimization_state: T.nilable(T::Hash[Symbol, T.untyped])).returns(T::Hash[Symbol, T.untyped]) }
+      def serialize_optimization_trace(optimization_state)
+        return {} unless optimization_state
+        
+        serialized_trace = optimization_state.dup
+        
+        # Convert candidate objects to their hash representations
+        if serialized_trace[:candidates]
+          serialized_trace[:candidates] = serialized_trace[:candidates].map(&:to_h)
+        end
+        
+        serialized_trace
+      end
+
       # Helper methods
       sig { params(program: T.untyped).returns(T.nilable(String)) }
       def extract_current_instruction(program)

data/lib/dspy/teleprompt/utils.rb

@@ -247,15 +247,17 @@ module DSPy
             prediction = program.call(**example.input_values)
             
             # Check if prediction matches expected output
+            prediction_hash = extract_output_fields_from_prediction(prediction, example.signature_class)
+            
             if metric
-              success = metric.call(example, prediction.to_h)
+              success = metric.call(example, prediction_hash)
             else
-              success = example.matches_prediction?(prediction.to_h)
+              success = example.matches_prediction?(prediction_hash)
             end
 
             if success
               # Create a new example with the successful prediction as reasoning/context
-              successful_example = create_successful_bootstrap_example(example, prediction)
+              successful_example = create_successful_bootstrap_example(example, prediction_hash)
               successful << successful_example
               
               emit_bootstrap_example_event(index, true, nil)
@@ -311,7 +313,7 @@ module DSPy
       sig do
         params(
           original_example: DSPy::Example,
-          prediction: T.untyped
+          prediction: T::Hash[Symbol, T.untyped]
         ).returns(DSPy::Example)
       end
       def self.create_successful_bootstrap_example(original_example, prediction)
@@ -319,7 +321,7 @@ module DSPy
         DSPy::Example.new(
           signature_class: original_example.signature_class,
           input: original_example.input_values,
-          expected: prediction.to_h,
+          expected: prediction,
           id: "bootstrap_#{original_example.id || SecureRandom.uuid}",
           metadata: {
             source: "bootstrap",
@@ -329,6 +331,29 @@ module DSPy
         )
       end
 
+      # Extract only output fields from prediction (exclude input fields)
+      sig do
+        params(
+          prediction: T.untyped,
+          signature_class: T.class_of(DSPy::Signature)
+        ).returns(T::Hash[Symbol, T.untyped])
+      end
+      def self.extract_output_fields_from_prediction(prediction, signature_class)
+        prediction_hash = prediction.to_h
+        
+        # Get output field names from signature
+        output_fields = signature_class.output_field_descriptors.keys
+        
+        # Filter prediction to only include output fields
+        filtered_expected = {}
+        output_fields.each do |field_name|
+          if prediction_hash.key?(field_name)
+            filtered_expected[field_name] = prediction_hash[field_name]
+          end
+        end
+        
+        filtered_expected
+      end
 
       # Create default metric for examples
       sig { params(examples: T::Array[T.untyped]).returns(T.nilable(T.proc.params(arg0: T.untyped, arg1: T.untyped).returns(T::Boolean))) }

data/lib/dspy/version.rb

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

data/lib/dspy.rb

@@ -74,6 +74,20 @@ module DSPy
     end
   end
 
+  # Fiber-local LM context for temporary model overrides
+  FIBER_LM_KEY = :dspy_fiber_lm
+
+  def self.current_lm
+    Fiber[FIBER_LM_KEY] || config.lm
+  end
+
+  def self.with_lm(lm)
+    previous_lm = Fiber[FIBER_LM_KEY]
+    Fiber[FIBER_LM_KEY] = lm
+    yield
+  ensure
+    Fiber[FIBER_LM_KEY] = previous_lm
+  end
 end
 
 require_relative 'dspy/module'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
 bindir: bin
 cert_chain: []
-date: 2025-08-11 00:00:00.000000000 Z
+date: 2025-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -79,6 +79,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.5.0
+- !ruby/object:Gem::Dependency
+  name: gemini-ai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.3'
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
   requirement: !ruby/object:Gem::Requirement
@@ -186,6 +200,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_adapter.rb
 - lib/dspy/lm/adapters/ollama_adapter.rb
 - lib/dspy/lm/adapters/openai/schema_converter.rb
 - lib/dspy/lm/adapters/openai_adapter.rb