dspy 0.31.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 972e09f00d8d5417d5c1af255eb01503fc33ab370264345b4c7de880b4f99fda
-  data.tar.gz: 21f6f7952a9caaf8398a24a69516147bf68c88e510b88aa2f45239786bbfd31b
+  metadata.gz: a3f15cdf0298a37b8ddf1ffb484e15e01e9bb8f794154d2a993dd91beaa4d22e
+  data.tar.gz: f6d0376e92a84d0086257546111e3f456043d814f9dd051a18ce84569e30ff1e
 SHA512:
-  metadata.gz: 780f786797df9d50950c1526296c8bc7a0db87dab29078e14de2d32a0ec608ae30585963a4dda3a5261b60530b3dd59e0b9e5915eab6c8d60360c4d1b6e1d8af
-  data.tar.gz: 3fb5d69bb58d9b57905a6f9985ecdd5d792be0aa91fb5e980f437f5d8887144564697d1151ed9bb8ec742b4ae4c1efff5303b53d937603ac7719959ffb11cfd9
+  metadata.gz: 5c26922fcf7fd867b6469bdcae24f3c2937a2f2e89b0583026a478c766c4138896709d98d598814d09220a8becd7f624bc824ad3a9f569bbac60abf7ec4e49d7
+  data.tar.gz: a251452f69f157a026e0c23bc912f9ddc2252d4e977e2ebbc3f2276ffd293fe7ff4af7aaa97c7807c21e5cdd805fd50d54046016c44664fb153b87788e5a9a16

data/README.md

@@ -13,12 +13,10 @@
 > 
 > If you want to contribute, feel free to reach out to me to coordinate efforts: hey at vicente.services
 >
-> And, yes, this is 100% a legit project. :) 
-
 
 **Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
 
-DSPy.rb is the Ruby-first surgical port of Stanford's [DSPy framework](https://github.com/stanfordnlp/dspy). It delivers structured LLM programming, prompt engineering, and context engineering in the language we love. Instead of wrestling with brittle prompt strings, you define typed signatures in idiomatic Ruby and compose workflows and agents that actually behave.
+DSPy.rb is the Ruby-first surgical port of Stanford's [DSPy paradigm](https://github.com/stanfordnlp/dspy). It delivers structured LLM programming, prompt engineering, and context engineering in the language we love. Instead of wrestling with brittle prompt strings, you define typed signatures in idiomatic Ruby and compose workflows and agents that actually behave.
 
 **Prompts are just functions.** 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/): define modular signatures and let the framework deal with the messy bits.
 
@@ -104,6 +102,7 @@ DSPy.rb ships multiple gems from this monorepo so you can opt into features with
 | `dspy-openai` | Packages the OpenAI/OpenRouter/Ollama adapters plus the official SDK guardrails. Install whenever you call `openai/*`, `openrouter/*`, or `ollama/*`. [Adapter README](https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/openai/README.md) | **Stable** (v1.0.0) |
 | `dspy-anthropic` | Claude adapters, streaming, and structured-output helpers behind the official `anthropic` SDK. [Adapter README](https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/anthropic/README.md) | **Stable** (v1.0.0) |
 | `dspy-gemini` | Gemini adapters with multimodal + tool-call support via `gemini-ai`. [Adapter README](https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/gemini/README.md) | **Stable** (v1.0.0) |
+| `dspy-ruby_llm` | Unified access to 12+ LLM providers (OpenAI, Anthropic, Gemini, Bedrock, Ollama, DeepSeek, etc.) via [RubyLLM](https://rubyllm.com). [Adapter README](https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/ruby_llm/README.md) | **Stable** (v0.1.0) |
 | `dspy-code_act` | Think-Code-Observe agents that synthesize and execute Ruby safely. (Add the gem or set `DSPY_WITH_CODE_ACT=1` before requiring `dspy/code_act`.) | **Stable** (v1.0.0) |
 | `dspy-datasets` | Dataset helpers plus Parquet/Polars tooling for richer evaluation corpora. (Toggle via `DSPY_WITH_DATASETS`.) | **Stable** (v1.0.0) |
 | `dspy-evals` | High-throughput evaluation harness with metrics, callbacks, and regression fixtures. (Toggle via `DSPY_WITH_EVALS`.) | **Stable** (v1.0.0) |

data/lib/dspy/evals/version.rb

@@ -2,6 +2,6 @@
 
 module DSPy
   class Evals
-    VERSION = '1.0.0'
+    VERSION = '1.0.1'
   end
 end

data/lib/dspy/lm/adapter_factory.rb

@@ -10,10 +10,11 @@ module DSPy
         'anthropic' => { class_name: 'DSPy::Anthropic::LM::Adapters::AnthropicAdapter', gem_name: 'dspy-anthropic' },
         'ollama' => { class_name: 'DSPy::OpenAI::LM::Adapters::OllamaAdapter', gem_name: 'dspy-openai' },
         'gemini' => { class_name: 'DSPy::Gemini::LM::Adapters::GeminiAdapter', gem_name: 'dspy-gemini' },
-        'openrouter' => { class_name: 'DSPy::OpenAI::LM::Adapters::OpenRouterAdapter', gem_name: 'dspy-openai' }
+        'openrouter' => { class_name: 'DSPy::OpenAI::LM::Adapters::OpenRouterAdapter', gem_name: 'dspy-openai' },
+        'ruby_llm' => { class_name: 'DSPy::RubyLLM::LM::Adapters::RubyLLMAdapter', gem_name: 'dspy-ruby_llm' }
       }.freeze
 
-      PROVIDERS_WITH_EXTRA_OPTIONS = %w[openai anthropic ollama gemini openrouter].freeze
+      PROVIDERS_WITH_EXTRA_OPTIONS = %w[openai anthropic ollama gemini openrouter ruby_llm].freeze
 
       class AdapterData < Data.define(:class_name, :gem_name)
         def self.from_prefix(provider_prefix)

data/lib/dspy/mixins/type_coercion.rb

@@ -36,6 +36,8 @@ module DSPy
           coerce_array_value(value, prop_type)
         when ->(type) { hash_type?(type) }
           coerce_hash_value(value, prop_type)
+        when ->(type) { type == String || simple_type_match?(type, String) }
+          value.to_s
         when ->(type) { enum_type?(type) }
           coerce_enum_value(value, prop_type)
         when ->(type) { type == Float || simple_type_match?(type, Float) }

data/lib/dspy/observability.rb

@@ -26,29 +26,33 @@ rescue LoadError
       end
     end
 
-    class ObservationType < T::Enum
-      enums do
-        Generation = new('generation')
-        Agent = new('agent')
-        Tool = new('tool')
-        Chain = new('chain')
-        Retriever = new('retriever')
-        Embedding = new('embedding')
-        Evaluator = new('evaluator')
-        Span = new('span')
-        Event = new('event')
-      end
+    # Guard against double-loading with Zeitwerk/Rails autoloader
+    # See: https://github.com/vicentereig/dspy.rb/issues/190
+    unless defined?(DSPy::ObservationType)
+      class ObservationType < T::Enum
+        enums do
+          Generation = new('generation')
+          Agent = new('agent')
+          Tool = new('tool')
+          Chain = new('chain')
+          Retriever = new('retriever')
+          Embedding = new('embedding')
+          Evaluator = new('evaluator')
+          Span = new('span')
+          Event = new('event')
+        end
 
-      def self.for_module_class(_module_class)
-        Span
-      end
+        def self.for_module_class(_module_class)
+          Span
+        end
 
-      def langfuse_attribute
-        ['langfuse.observation.type', serialize]
-      end
+        def langfuse_attribute
+          ['langfuse.observation.type', serialize]
+        end
 
-      def langfuse_attributes
-        { 'langfuse.observation.type' => serialize }
+        def langfuse_attributes
+          { 'langfuse.observation.type' => serialize }
+        end
       end
     end
   end

data/lib/dspy/prompt.rb

@@ -155,17 +155,38 @@ module DSPy
         end
       end
 
-      if data_format == :toon && @signature_class
+      if toon_data_format_enabled?
+        sections << "## TOON data format instructions"
+        sections << "All input and output payloads must use Token-Oriented Object Notation (TOON). Do not return JSON, YAML, or prose."
+        sections << ""
         sections << "## Input values"
+        sections << "Copy the TOON block below and replace the placeholder values with the correct inputs."
         sections << "```toon"
         sections << "{input_values}"
         sections << "```"
+
+        if (example_input = example_toon_payload(:input))
+          sections << ""
+          sections << "### Example TOON input"
+          sections << "```toon"
+          sections << example_input
+          sections << "```"
+        end
+
         sections << ""
         sections << "## Output values"
-        sections << "Respond exclusively with a ```toon``` block containing only the output fields defined above, in the same order."
+        sections << "Respond exclusively with a ```toon``` block that lists the output fields in the exact order shown in the schema."
         sections << "```toon"
         sections << "{output_values}"
         sections << "```"
+
+        if (example_output = example_toon_payload(:output))
+          sections << ""
+          sections << "### Example TOON output"
+          sections << "```toon"
+          sections << example_output
+          sections << "```"
+        end
       else
         sections << "## Input values"
         sections << "```json"
@@ -189,15 +210,16 @@ module DSPy
     def render_user_prompt(input_values)
       sections = []
 
-      if data_format == :toon && @signature_class
+      if toon_data_format_enabled?
         toon_payload = DSPy::Schema::SorbetToonAdapter.render_input(@signature_class, input_values)
 
         sections << "## Input Values"
+        sections << "Use the TOON block below as-is; do not convert it to JSON."
         sections << "```toon"
         sections << toon_payload
         sections << "```"
         sections << ""
-        sections << "Respond with the corresponding output schema fields encoded as TOON inside a ```toon``` block starting with the heading `## Output values`."
+        sections << "Respond with the corresponding output schema fields encoded as TOON inside a ```toon``` block starting with the heading `## Output values`. Do not include any JSON."
       else
         sections << "## Input Values"
         sections << "```json"
@@ -393,5 +415,96 @@ module DSPy
       
       result
     end
+
+    def toon_data_format_enabled?
+      data_format == :toon && @signature_class
+    end
+
+    SAMPLE_DEPTH_LIMIT = 3
+    private_constant :SAMPLE_DEPTH_LIMIT
+
+    def example_toon_payload(role)
+      return nil unless toon_data_format_enabled?
+
+      sample_values = case role
+                      when :input
+                        sample_struct_values(@signature_class.input_struct_class)
+                      when :output
+                        sample_struct_values(@signature_class.output_struct_class)
+                      else
+                        {}
+                      end
+
+      return nil if sample_values.empty?
+
+      case role
+      when :input
+        DSPy::Schema::SorbetToonAdapter.render_input(@signature_class, sample_values)
+      when :output
+        DSPy::Schema::SorbetToonAdapter.render_expected_output(@signature_class, sample_values)
+      end
+    rescue StandardError
+      nil
+    end
+
+    def sample_struct_values(struct_class, depth = 0)
+      return {} unless struct_class&.respond_to?(:props)
+      struct_class.props.each_with_object({}) do |(name, prop_info), memo|
+        memo[name] = sample_value_for_type(prop_info[:type], name, depth)
+      end
+    end
+
+    def sample_value_for_type(prop_type, field_name, depth)
+      return sample_string(field_name) if prop_type.nil? || depth > SAMPLE_DEPTH_LIMIT
+
+      case prop_type
+      when T::Types::Simple
+        sample_value_for_type(prop_type.raw_type, field_name, depth + 1)
+      when T::Types::Union
+        preferred = prop_type.types.find { |type| !nil_type?(type) } || prop_type.types.first
+        sample_value_for_type(preferred, field_name, depth + 1)
+      when T::Types::TypedArray
+        [sample_value_for_type(prop_type.type, field_name, depth + 1)]
+      when T::Types::TypedHash
+        key_sample = sample_value_for_type(prop_type.keys, "#{field_name}_key", depth + 1)
+        value_sample = sample_value_for_type(prop_type.values, "#{field_name}_value", depth + 1)
+        { key_sample.to_s => value_sample }
+      when Class
+        sample_for_class_type(prop_type, field_name, depth)
+      else
+        sample_string(field_name)
+      end
+    end
+
+    def sample_for_class_type(prop_type, field_name, depth)
+      if prop_type <= String
+        sample_string(field_name)
+      elsif prop_type <= Integer
+        1
+      elsif prop_type <= Float
+        1.0
+      elsif prop_type <= Numeric
+        1
+      elsif prop_type <= TrueClass || prop_type <= FalseClass
+        true
+      elsif prop_type <= T::Enum
+        enum_value = prop_type.values.first
+        enum_value ? enum_value.serialize : sample_string(field_name)
+      elsif prop_type <= T::Struct
+        sample_struct_values(prop_type, depth + 1)
+      else
+        sample_string(field_name)
+      end
+    end
+
+    def nil_type?(type)
+      (type.respond_to?(:raw_type) && type.raw_type == NilClass) || type == NilClass
+    end
+
+    def sample_string(field_name)
+      base = field_name.to_s.gsub(/[^a-z0-9]+/i, '_').gsub(/_{2,}/, '_').sub(/^_+|_+$/, '')
+      base = 'value' if base.empty?
+      "example_#{base}"
+    end
   end
 end

data/lib/dspy/ruby_llm/guardrails.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'dspy/lm/errors'
+
+module DSPy
+  module RubyLLM
+    class Guardrails
+      SUPPORTED_RUBY_LLM_VERSIONS = "~> 1.3".freeze
+
+      def self.ensure_ruby_llm_installed!
+        require 'ruby_llm'
+
+        spec = Gem.loaded_specs["ruby_llm"]
+        unless spec && Gem::Requirement.new(SUPPORTED_RUBY_LLM_VERSIONS).satisfied_by?(spec.version)
+          msg = <<~MSG
+            DSPy requires the `ruby_llm` gem #{SUPPORTED_RUBY_LLM_VERSIONS}.
+            Please install or upgrade it with `bundle add ruby_llm --version "#{SUPPORTED_RUBY_LLM_VERSIONS}"`.
+          MSG
+          raise DSPy::LM::UnsupportedVersionError, msg
+        end
+      end
+    end
+  end
+end

data/lib/dspy/ruby_llm/lm/adapters/ruby_llm_adapter.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'ruby_llm'
+require 'dspy/lm/adapter'
+require 'dspy/lm/vision_models'
+
+require 'dspy/ruby_llm/guardrails'
+DSPy::RubyLLM::Guardrails.ensure_ruby_llm_installed!
+
+module DSPy
+  module RubyLLM
+    module LM
+      module Adapters
+        class RubyLLMAdapter < DSPy::LM::Adapter
+          attr_reader :provider
+
+          # Options that require a scoped context instead of global RubyLLM config
+          SCOPED_OPTIONS = %i[base_url timeout max_retries].freeze
+
+          def initialize(model:, api_key: nil, **options)
+            @api_key = api_key
+            @options = options
+            @structured_outputs_enabled = options.fetch(:structured_outputs, true)
+            @provider_override = options[:provider] # Optional provider override
+
+            # Detect provider eagerly (matches OpenAI/Anthropic/Gemini adapters)
+            @provider = detect_provider(model)
+
+            # Determine if we should use global RubyLLM config or create scoped context
+            @use_global_config = should_use_global_config?(api_key, options)
+
+            super(model: model, api_key: api_key)
+
+            # Only validate API key if not using global config
+            unless @use_global_config
+              validate_api_key_for_provider!(api_key)
+            end
+
+            # Validate base_url if provided
+            validate_base_url!(@options[:base_url])
+          end
+
+          # Returns the context - either scoped or global
+          def context
+            @context ||= @use_global_config ? nil : create_context(@api_key)
+          end
+
+          def chat(messages:, signature: nil, &block)
+            normalized_messages = normalize_messages(messages)
+
+            # Validate vision support if images are present
+            if contains_images?(normalized_messages)
+              validate_vision_support!
+              normalized_messages = format_multimodal_messages(normalized_messages)
+            end
+
+            chat_instance = create_chat_instance
+
+            if block_given?
+              stream_response(chat_instance, normalized_messages, signature, &block)
+            else
+              standard_response(chat_instance, normalized_messages, signature)
+            end
+          rescue ::RubyLLM::UnauthorizedError => e
+            raise DSPy::LM::MissingAPIKeyError.new(provider)
+          rescue ::RubyLLM::RateLimitError => e
+            raise DSPy::LM::AdapterError, "Rate limit exceeded for #{provider}: #{e.message}"
+          rescue ::RubyLLM::ModelNotFoundError => e
+            raise DSPy::LM::AdapterError, "Model not found: #{e.message}. Check available models with RubyLLM.models.all"
+          rescue ::RubyLLM::BadRequestError => e
+            raise DSPy::LM::AdapterError, "Invalid request to #{provider}: #{e.message}"
+          rescue ::RubyLLM::ConfigurationError => e
+            raise DSPy::LM::ConfigurationError, "RubyLLM configuration error: #{e.message}"
+          rescue ::RubyLLM::Error => e
+            raise DSPy::LM::AdapterError, "RubyLLM error (#{provider}): #{e.message}"
+          end
+
+          private
+
+          # Detect provider from RubyLLM's model registry or use explicit override
+          def detect_provider(model_id)
+            return @provider_override.to_s if @provider_override
+
+            model_info = ::RubyLLM.models.find(model_id)
+            model_info.provider.to_s
+          rescue ::RubyLLM::ModelNotFoundError
+            raise DSPy::LM::ConfigurationError,
+              "Model '#{model_id}' not found in RubyLLM registry. " \
+              "Use provider: option to specify explicitly, or run RubyLLM.models.refresh!"
+          end
+
+          # Check if we should use RubyLLM's global configuration
+          # Uses global config when no api_key and no provider-specific options provided
+          def should_use_global_config?(api_key, options)
+            api_key.nil? && (options.keys & SCOPED_OPTIONS).empty?
+          end
+
+          # Validate API key for providers that require it
+          def validate_api_key_for_provider!(api_key)
+            # Ollama and some local providers don't require API keys
+            return if provider_allows_no_api_key?
+
+            validate_api_key!(api_key, provider)
+          end
+
+          def provider_allows_no_api_key?
+            %w[ollama gpustack].include?(provider)
+          end
+
+          def validate_base_url!(url)
+            return if url.nil?
+
+            uri = URI.parse(url)
+            unless %w[http https].include?(uri.scheme)
+              raise DSPy::LM::ConfigurationError, "base_url must use http or https scheme"
+            end
+          rescue URI::InvalidURIError
+            raise DSPy::LM::ConfigurationError, "Invalid base_url format: #{url}"
+          end
+
+          def create_context(api_key)
+            ::RubyLLM.context do |config|
+              configure_provider(config, api_key)
+              configure_connection(config)
+            end
+          end
+
+          # Configure RubyLLM using convention: {provider}_api_key and {provider}_api_base
+          # For providers with non-standard auth (bedrock, vertexai), configure RubyLLM globally
+          def configure_provider(config, api_key)
+            key_method = "#{provider}_api_key="
+            config.send(key_method, api_key) if api_key && config.respond_to?(key_method)
+
+            base_method = "#{provider}_api_base="
+            config.send(base_method, @options[:base_url]) if @options[:base_url] && config.respond_to?(base_method)
+          end
+
+          def configure_connection(config)
+            config.request_timeout = @options[:timeout] if @options[:timeout]
+            config.max_retries = @options[:max_retries] if @options[:max_retries]
+          end
+
+          def create_chat_instance
+            chat_options = { model: model }
+
+            # If provider is explicitly overridden, pass it to RubyLLM
+            if @provider_override
+              chat_options[:provider] = @provider_override.to_sym
+              chat_options[:assume_model_exists] = true
+            end
+
+            # Use global RubyLLM config or scoped context
+            if @use_global_config
+              ::RubyLLM.chat(**chat_options)
+            else
+              context.chat(**chat_options)
+            end
+          end
+
+          def standard_response(chat_instance, messages, signature)
+            chat_instance = prepare_chat_instance(chat_instance, messages, signature)
+            content, attachments = prepare_message_content(messages)
+            return build_empty_response unless content
+
+            response = send_message(chat_instance, content, attachments)
+            map_response(response)
+          end
+
+          def stream_response(chat_instance, messages, signature, &block)
+            chat_instance = prepare_chat_instance(chat_instance, messages, signature)
+            content, attachments = prepare_message_content(messages)
+            return build_empty_response unless content
+
+            response = send_message(chat_instance, content, attachments, &block)
+            map_response(response)
+          end
+
+          # Common setup: apply system instructions, build conversation history, and optional schema
+          def prepare_chat_instance(chat_instance, messages, signature)
+            # First, handle system messages via with_instructions for proper system prompt handling
+            system_message = messages.find { |m| m[:role] == 'system' }
+            chat_instance = chat_instance.with_instructions(system_message[:content]) if system_message
+
+            # Build conversation history by adding all non-system messages except the last user message
+            # The last user message will be passed to ask() to get the response
+            messages_to_add = messages.reject { |m| m[:role] == 'system' }
+
+            # Find the index of the last user message
+            last_user_index = messages_to_add.rindex { |m| m[:role] == 'user' }
+
+            if last_user_index && last_user_index > 0
+              # Add all messages before the last user message to build history
+              messages_to_add[0...last_user_index].each do |msg|
+                content, attachments = extract_content_and_attachments(msg)
+                next unless content
+
+                # Add message with appropriate role
+                if attachments.any?
+                  chat_instance.add_message(role: msg[:role].to_sym, content: content, attachments: attachments)
+                else
+                  chat_instance.add_message(role: msg[:role].to_sym, content: content)
+                end
+              end
+            end
+
+            if signature && @structured_outputs_enabled
+              schema = build_json_schema(signature)
+              chat_instance = chat_instance.with_schema(schema) if schema
+            end
+
+            chat_instance
+          end
+
+          # Extract content from last user message
+          # RubyLLM's Chat API builds conversation history via add_message() for previous turns,
+          # and the last user message is passed to ask() to get the response.
+          def prepare_message_content(messages)
+            last_user_message = messages.reverse.find { |m| m[:role] == 'user' }
+            return [nil, []] unless last_user_message
+
+            extract_content_and_attachments(last_user_message)
+          end
+
+          # Send message with optional streaming block
+          def send_message(chat_instance, content, attachments, &block)
+            kwargs = attachments.any? ? { with: attachments } : {}
+
+            if block_given?
+              chat_instance.ask(content, **kwargs) do |chunk|
+                block.call(chunk.content) if chunk.content
+              end
+            else
+              chat_instance.ask(content, **kwargs)
+            end
+          end
+
+          def extract_content_and_attachments(message)
+            content = message[:content]
+            attachments = []
+
+            if content.is_a?(Array)
+              text_parts = []
+              content.each do |item|
+                case item[:type]
+                when 'text'
+                  text_parts << item[:text]
+                when 'image'
+                  # Extract image URL or path
+                  image = item[:image]
+                  if image.respond_to?(:url)
+                    attachments << image.url
+                  elsif image.respond_to?(:path)
+                    attachments << image.path
+                  elsif item[:image_url]
+                    attachments << item[:image_url][:url]
+                  end
+                end
+              end
+              content = text_parts.join("\n")
+            end
+
+            [content.to_s, attachments]
+          end
+
+          def map_response(ruby_llm_response)
+            DSPy::LM::Response.new(
+              content: ruby_llm_response.content.to_s,
+              usage: build_usage(ruby_llm_response),
+              metadata: build_metadata(ruby_llm_response)
+            )
+          end
+
+          def build_usage(response)
+            input_tokens = response.input_tokens || 0
+            output_tokens = response.output_tokens || 0
+
+            DSPy::LM::Usage.new(
+              input_tokens: input_tokens,
+              output_tokens: output_tokens,
+              total_tokens: input_tokens + output_tokens
+            )
+          end
+
+          def build_metadata(response)
+            DSPy::LM::ResponseMetadataFactory.create('ruby_llm', {
+              model: response.model_id || model,
+              underlying_provider: provider
+            })
+          end
+
+          def build_empty_response
+            DSPy::LM::Response.new(
+              content: '',
+              usage: DSPy::LM::Usage.new(input_tokens: 0, output_tokens: 0, total_tokens: 0),
+              metadata: DSPy::LM::ResponseMetadataFactory.create('ruby_llm', {
+                model: model,
+                underlying_provider: provider
+              })
+            )
+          end
+
+          def build_json_schema(signature)
+            return nil unless signature.respond_to?(:json_schema)
+
+            schema = signature.json_schema
+            normalize_schema(schema)
+          end
+
+          def normalize_schema(schema)
+            return schema unless schema.is_a?(Hash)
+
+            @normalized_schema_cache ||= {}
+            cache_key = schema.hash
+
+            @normalized_schema_cache[cache_key] ||= begin
+              duped = deep_dup(schema)
+              add_additional_properties_false(duped)
+              duped.freeze
+            end
+          end
+
+          def add_additional_properties_false(schema)
+            return unless schema.is_a?(Hash)
+
+            if schema[:type] == 'object' || schema['type'] == 'object'
+              schema[:additionalProperties] = false
+              schema['additionalProperties'] = false
+            end
+
+            # Recursively process nested schemas
+            schema.each_value { |v| add_additional_properties_false(v) if v.is_a?(Hash) }
+
+            # Handle arrays with items
+            if schema[:items]
+              add_additional_properties_false(schema[:items])
+            elsif schema['items']
+              add_additional_properties_false(schema['items'])
+            end
+          end
+
+          def deep_dup(obj)
+            case obj
+            when Hash
+              obj.transform_values { |v| deep_dup(v) }
+            when Array
+              obj.map { |v| deep_dup(v) }
+            else
+              obj
+            end
+          end
+
+          def validate_vision_support!
+            # RubyLLM handles vision validation internally, but we can add
+            # additional DSPy-specific validation here if needed
+            DSPy::LM::VisionModels.validate_vision_support!(provider, model)
+          rescue DSPy::LM::IncompatibleImageFeatureError
+            # If DSPy doesn't know about the model, let RubyLLM handle it
+            # RubyLLM has its own model registry with capability detection
+          end
+
+          def format_multimodal_messages(messages)
+            messages.map do |msg|
+              if msg[:content].is_a?(Array)
+                formatted_content = msg[:content].map do |item|
+                  case item[:type]
+                  when 'text'
+                    { type: 'text', text: item[:text] }
+                  when 'image'
+                    # Validate and format image for provider
+                    image = item[:image]
+                    if image.respond_to?(:validate_for_provider!)
+                      image.validate_for_provider!(provider)
+                    end
+                    item
+                  else
+                    item
+                  end
+                end
+
+                { role: msg[:role], content: formatted_content }
+              else
+                msg
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dspy/ruby_llm/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module DSPy
+  module RubyLLM
+    VERSION = '0.1.0'
+  end
+end

data/lib/dspy/ruby_llm.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'dspy/ruby_llm/version'
+
+require 'dspy/ruby_llm/guardrails'
+DSPy::RubyLLM::Guardrails.ensure_ruby_llm_installed!
+
+require 'dspy/ruby_llm/lm/adapters/ruby_llm_adapter'

data/lib/dspy/schema/sorbet_toon_adapter.rb

@@ -37,7 +37,8 @@ module DSPy
         Sorbet::Toon.decode(
           payload,
           signature: signature_class,
-          role: :output
+          role: :output,
+          strict: false
         )
       rescue Sorbet::Toon::DecodeError => e
         log_decode_error(payload, e)

data/lib/dspy/tools/github_cli_toolset.rb

@@ -66,6 +66,8 @@ module DSPy
       tool :get_issue, description: "Get details of a specific GitHub issue"
       tool :get_pr, description: "Get details of a specific GitHub pull request"
       tool :api_request, description: "Make an arbitrary GitHub API request"
+      tool :traffic_views, description: "Get repository traffic views (last 14 days by default)"
+      tool :traffic_clones, description: "Get repository traffic clones (last 14 days by default)"
 
       sig { void }
       def initialize
@@ -216,6 +218,40 @@ module DSPy
         "Error making API request: #{e.message}"
       end
 
+      sig { params(repo: String, per: T.nilable(String)).returns(String) }
+      def traffic_views(repo:, per: nil)
+        endpoint = "repos/#{repo}/traffic/views"
+        cmd = build_gh_command(['api', shell_escape(endpoint)])
+        cmd << ['-f', "per=#{shell_escape(per)}"] if per
+
+        result = execute_command(cmd.flatten.join(' '))
+
+        if result[:success]
+          parse_traffic(result[:output], label: 'Views')
+        else
+          "Failed to fetch traffic views: #{result[:error]}"
+        end
+      rescue => e
+        "Error fetching traffic views: #{e.message}"
+      end
+
+      sig { params(repo: String, per: T.nilable(String)).returns(String) }
+      def traffic_clones(repo:, per: nil)
+        endpoint = "repos/#{repo}/traffic/clones"
+        cmd = build_gh_command(['api', shell_escape(endpoint)])
+        cmd << ['-f', "per=#{shell_escape(per)}"] if per
+
+        result = execute_command(cmd.flatten.join(' '))
+
+        if result[:success]
+          parse_traffic(result[:output], label: 'Clones')
+        else
+          "Failed to fetch traffic clones: #{result[:error]}"
+        end
+      rescue => e
+        "Error fetching traffic clones: #{e.message}"
+      end
+
       private
 
       sig { params(args: T::Array[String]).returns(T::Array[String]) }
@@ -225,6 +261,7 @@ module DSPy
 
       sig { params(str: String).returns(String) }
       def shell_escape(str)
+        return '""' if str.nil?
         "\"#{str.gsub(/"/, '\\"')}\""
       end
 
@@ -240,6 +277,29 @@ module DSPy
         }
       end
 
+      sig { params(json_output: String, label: String).returns(String) }
+      def parse_traffic(json_output, label:)
+        data = JSON.parse(json_output)
+
+        total = data['count'] || 0
+        uniques = data['uniques'] || 0
+        series = data[label.downcase] || data['views'] || []
+
+        lines = []
+        lines << "#{label}: #{total} total (#{uniques} unique) over the last #{series.length} data points"
+
+        series.each do |point|
+          ts = point['timestamp'] || point['timestamp'.to_sym]
+          count = point['count'] || 0
+          uniq = point['uniques'] || 0
+          lines << "  #{ts}: #{count} (#{uniq} unique)"
+        end
+
+        lines.join("\n")
+      rescue JSON::ParserError => e
+        "Failed to parse traffic data: #{e.message}"
+      end
+
       sig { params(json_output: String).returns(String) }
       def parse_issue_list(json_output)
         issues = JSON.parse(json_output)
@@ -327,4 +387,4 @@ module DSPy
       end
     end
   end
-end
+end

data/lib/dspy/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.31.0
+  version: 0.32.0
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
@@ -210,6 +210,10 @@ files:
 - lib/dspy/reflection_lm.rb
 - lib/dspy/registry/registry_manager.rb
 - lib/dspy/registry/signature_registry.rb
+- lib/dspy/ruby_llm.rb
+- lib/dspy/ruby_llm/guardrails.rb
+- lib/dspy/ruby_llm/lm/adapters/ruby_llm_adapter.rb
+- lib/dspy/ruby_llm/version.rb
 - lib/dspy/schema.rb
 - lib/dspy/schema/sorbet_json_schema.rb
 - lib/dspy/schema/sorbet_toon_adapter.rb