dspy 0.31.1 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 584b43a98aa27dcc4bcdb83c64f48b4c3d0f4b67453abfe9a0942cbc30b14e7d
-  data.tar.gz: ab2b58be33ef10e36d1825c371e29783a7a3cea72bfb34b765b9aeab5fb4644f
+  metadata.gz: 52dc686ff0347f7844a3b6fc476b31737f3467d5d179974f34a98b8dbbd12073
+  data.tar.gz: 0e39c94a4766c481167268f49e42277d297b688ee9f960181785062e69f91572
 SHA512:
-  metadata.gz: 6671b0cca0709aa9dea2eaf46abbbc2366d0779a89139377b6840279afa767e659bf635e8314a0a3ca45bc3f476200b7d430f74e83b0af08a085ae221a97c7c5
-  data.tar.gz: 1f8aaba8e3e2f16e1bd0eb81f9694b677f20cbeb7d0dadbacc9571613076ab29bc44991c79f3c5908e821397b2e0616e04801704f4ced5e0e5a8e9eed4f84f4f
+  metadata.gz: bb4fb2ce89ed600e971a07cfabe3eb9edd344563aa77df57304dbec565121eeb9c8a53ba4cdd66f04c81cb3b1231d222a59fb4a15962680051c07de49c080dca
+  data.tar.gz: 2543dd3bc228c98a1ab82c14ce8fffbed86342fa661af674976b90b10752334a5606257401f9ff953bd82f36aa29fe816895acec9e30a5219e8c8dc2d3ea1727

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

@@ -37,7 +37,7 @@ module DSPy
         when ->(type) { hash_type?(type) }
           coerce_hash_value(value, prop_type)
         when ->(type) { type == String || simple_type_match?(type, String) }
-          value.to_s
+          coerce_to_string(value)
         when ->(type) { enum_type?(type) }
           coerce_enum_value(value, prop_type)
         when ->(type) { type == Float || simple_type_match?(type, Float) }
@@ -295,6 +295,18 @@ module DSPy
         nil
       end
 
+      # Coerces a value to String with strict type checking
+      # Only allows String (passthrough) and Symbol (to_s) - rejects other types
+      sig { params(value: T.untyped).returns(String) }
+      def coerce_to_string(value)
+        case value
+        when String then value
+        when Symbol then value.to_s
+        else
+          raise TypeError, "Cannot coerce #{value.class} to String - expected String or Symbol"
+        end
+      end
+
       # Coerces a value to an enum, handling both strings and existing enum instances
       sig { params(value: T.untyped, prop_type: T.untyped).returns(T.untyped) }
       def coerce_enum_value(value, prop_type)

data/lib/dspy/module.rb

@@ -179,6 +179,47 @@ module DSPy
       named_predictors.map { |(_, predictor)| predictor }
     end
 
+    # Override Dry::Configurable's configure to propagate LM to child predictors
+    # When you configure an agent's LM, it automatically propagates to all child predictors
+    # returned by named_predictors, recursively.
+    #
+    # @example Basic usage
+    #   agent.configure { |c| c.lm = DSPy::LM.new('openai/gpt-4o') }
+    #   # All internal predictors now use gpt-4o
+    #
+    # @example Fine-grained control (configure then override)
+    #   agent.configure { |c| c.lm = cheap_lm }
+    #   agent.configure_predictor('thought_generator') { |c| c.lm = expensive_lm }
+    #
+    # @return [self] for method chaining
+    sig { params(block: T.proc.params(config: T.untyped).void).returns(T.self_type) }
+    def configure(&block)
+      super(&block)
+      propagate_lm_to_children(config.lm) if config.lm
+      self
+    end
+
+    # Configure a specific child predictor by name
+    # Use this for fine-grained control when different predictors need different LMs
+    #
+    # @param predictor_name [String] The name of the predictor (e.g., 'thought_generator')
+    # @yield [config] Configuration block
+    # @return [self] for method chaining
+    # @raise [ArgumentError] if predictor_name is not found
+    #
+    # @example
+    #   agent.configure_predictor('thought_generator') { |c| c.lm = expensive_lm }
+    sig { params(predictor_name: String, block: T.proc.params(config: T.untyped).void).returns(T.self_type) }
+    def configure_predictor(predictor_name, &block)
+      _, predictor = named_predictors.find { |name, _| name == predictor_name }
+      unless predictor
+        available = named_predictors.map(&:first).join(', ')
+        raise ArgumentError, "Unknown predictor: #{predictor_name}. Available: #{available}"
+      end
+      predictor.configure(&block)
+      self
+    end
+
     def instrument_forward_call(call_args, call_kwargs)
       ensure_module_subscriptions!
 
@@ -255,6 +296,21 @@ module DSPy
 
     private
 
+    # Propagate LM configuration to child predictors recursively
+    # Skips children that already have an explicit LM configured
+    sig { params(lm: T.untyped).void }
+    def propagate_lm_to_children(lm)
+      named_predictors.each do |(name, predictor)|
+        next if predictor == self # Skip self-references (Predict returns [['self', self]])
+
+        # Only propagate if child doesn't have explicit LM configured
+        unless predictor.config.lm
+          # Recursive: configure calls propagate_lm_to_children on the child too
+          predictor.configure { |c| c.lm = lm }
+        end
+      end
+    end
+
     def ensure_module_subscriptions!
       return if @module_subscriptions_registered
 

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/re_act.rb

@@ -9,23 +9,28 @@ require 'json'
 require_relative 'mixins/struct_builder'
 
 module DSPy
+  # Type alias for tool input parameters - provides semantic meaning in schemas
+  ToolInput = T.type_alias { T.nilable(T::Hash[String, T.untyped]) }
+
   # Define a simple struct for history entries with proper type annotations
   class HistoryEntry < T::Struct
     const :step, Integer
     prop :thought, T.nilable(String)
     prop :action, T.nilable(String)
-    prop :action_input, T.nilable(T.any(String, Numeric, T::Hash[T.untyped, T.untyped], T::Array[T.untyped]))
+    prop :tool_input, ToolInput
     prop :observation, T.untyped
 
     # Custom serialization to ensure compatibility with the rest of the code
+    # Note: We don't use .compact here to ensure tool_input is always present as a key,
+    # even when nil, for consistent history entry structure
     def to_h
       {
         step: step,
         thought: thought,
         action: action,
-        action_input: action_input,
+        tool_input: tool_input,
         observation: observation
-      }.compact
+      }
     end
   end
   # Base class for ReAct thought generation - will be customized per input type
@@ -37,8 +42,10 @@ module DSPy
         description: "Reasoning about what to do next, considering the history and observations."
       const :action, String,
         description: "The action to take. MUST be one of the tool names listed in `available_tools` input, or the literal string \"finish\" to provide the final answer."
-      const :action_input, T.untyped,
-        description: "Input for the chosen action. If action is a tool name, this MUST be a JSON object matching the tool's schema. If action is \"finish\", this field MUST contain the final result based on processing the input data. This result MUST be directly taken from the relevant Observation in the history if available."
+      const :tool_input, ToolInput,
+        description: "Input for the chosen tool action. Required when action is a tool name. MUST be a JSON object matching the tool's parameter schema. Set to null when action is \"finish\"."
+      const :final_answer, T.nilable(String),
+        description: "The final answer to return. Required when action is \"finish\". Must match the expected output type. Set to null when action is a tool name."
     end
   end
 
@@ -72,10 +79,12 @@ module DSPy
     class TypeMismatchError < StandardError; end
 
     # AvailableTool struct for better type safety in ReAct agents
+    # Schema is stored as a pre-serialized string (JSON or BAML) to avoid
+    # T.untyped issues during schema format conversion
     class AvailableTool < T::Struct
       const :name, String
       const :description, String
-      const :schema, T::Hash[Symbol, T.untyped]
+      const :schema, String
     end
 
     FINISH_ACTION = "finish"
@@ -211,7 +220,7 @@ module DSPy
           step: entry.step,
           thought: entry.thought,
           action: entry.action,
-          action_input: serialize_for_llm(entry.action_input),
+          tool_input: serialize_for_llm(entry.tool_input),
           observation: serialize_for_llm(entry.observation)
         }.compact
       end
@@ -244,22 +253,26 @@ module DSPy
     def create_action_enum_class
       tool_names = @tools.keys
       all_actions = tool_names + [FINISH_ACTION]
-      
+
       # Create a dynamic enum class using proper T::Enum pattern
       enum_class = Class.new(T::Enum)
-      
+
+      # Give the anonymous class a proper name for BAML schema rendering
+      # This overrides the default behavior that returns #<Class:0x...>
+      enum_class.define_singleton_method(:name) { 'ActionEnum' }
+
       # Build the enums block code dynamically
       enum_definitions = all_actions.map do |action_name|
         const_name = action_name.upcase.gsub(/[^A-Z0-9_]/, '_')
         "#{const_name} = new(#{action_name.inspect})"
       end.join("\n        ")
-      
+
       enum_class.class_eval <<~RUBY
         enums do
           #{enum_definitions}
         end
       RUBY
-      
+
       enum_class
     end
 
@@ -272,6 +285,11 @@ module DSPy
       else
         String
       end
+
+      # Get the output field type for the final_answer field
+      output_field_name = signature_class.output_struct_class.props.keys.first
+      output_field_type = signature_class.output_struct_class.props[output_field_name][:type_object]
+
       # Create new class that inherits from DSPy::Signature
       Class.new(DSPy::Signature) do
         # Set description
@@ -287,14 +305,16 @@ module DSPy
             description: "Array of available tools with their JSON schemas."
         end
 
-        # Define output fields (same as ThoughtBase)
+        # Define output fields with separate tool_input and final_answer
         output do
           const :thought, String,
             description: "Reasoning about what to do next, considering the history and observations."
           const :action, action_enum_class,
             description: "The action to take. MUST be one of the tool names listed in `available_tools` input, or the literal string \"finish\" to provide the final answer."
-          const :action_input, T.untyped,
-            description: "Input for the chosen action. If action is a tool name, this MUST be a JSON object matching the tool's schema. If action is \"finish\", this field MUST contain the final result based on processing the input data."
+          const :tool_input, ToolInput,
+            description: "Input for the chosen tool action. Required when action is a tool name. MUST be a JSON object matching the tool's parameter schema. Set to null when action is \"finish\"."
+          const :final_answer, T.nilable(output_field_type),
+            description: "The final answer to return. Required when action is \"finish\". Must match the expected output type. Set to null when action is a tool name."
         end
       end
     end
@@ -337,11 +357,10 @@ module DSPy
     def execute_react_reasoning_loop(input_struct)
       history = T.let([], T::Array[HistoryEntry])
       available_tools_desc = @tools.map { |name, tool|
-        schema = JSON.parse(tool.schema)
         AvailableTool.new(
           name: name,
           description: tool.description,
-          schema: schema.transform_keys(&:to_sym)
+          schema: tool.schema
         )
       }
       final_answer = T.let(nil, T.untyped)
@@ -399,7 +418,7 @@ module DSPy
         # Process thought result
         if finish_action?(thought_obj.action)
           final_answer = handle_finish_action(
-            thought_obj.action_input, last_observation, iteration,
+            thought_obj.final_answer, last_observation, iteration,
             thought_obj.thought, thought_obj.action, history
           )
           return { should_finish: true, final_answer: final_answer }
@@ -407,19 +426,19 @@ module DSPy
 
         # Execute tool action
         observation = execute_tool_with_instrumentation(
-          thought_obj.action, thought_obj.action_input, iteration
+          thought_obj.action, thought_obj.tool_input, iteration
         )
 
         # Convert action enum to string for processing and storage
         action_str = thought_obj.action.respond_to?(:serialize) ? thought_obj.action.serialize : thought_obj.action.to_s
-        
+
         # Track tools used
         tools_used << action_str.downcase if valid_tool?(thought_obj.action)
 
         # Add to history
         history << create_history_entry(
           iteration, thought_obj.thought, action_str,
-          thought_obj.action_input, observation
+          thought_obj.tool_input, observation
         )
 
         # Process observation and decide next step
@@ -433,7 +452,7 @@ module DSPy
 
         emit_iteration_complete_event(
           iteration, thought_obj.thought, action_str,
-          thought_obj.action_input, observation, tools_used
+          thought_obj.tool_input, observation, tools_used
         )
 
         {
@@ -613,8 +632,8 @@ module DSPy
       !!@tools[action_str.downcase]
     end
 
-    sig { params(action: T.nilable(T.any(String, T::Enum)), action_input: T.untyped, iteration: Integer).returns(T.untyped) }
-    def execute_tool_with_instrumentation(action, action_input, iteration)
+    sig { params(action: T.nilable(T.any(String, T::Enum)), tool_input: ToolInput, iteration: Integer).returns(T.untyped) }
+    def execute_tool_with_instrumentation(action, tool_input, iteration)
       raise InvalidActionError, "No action provided" unless action
 
       action_str = action.respond_to?(:serialize) ? action.serialize : action.to_s
@@ -630,19 +649,19 @@ module DSPy
         'dspy.module' => 'ReAct',
         'react.iteration' => iteration,
         'tool.name' => action_str.downcase,
-        'tool.input' => action_input
+        'tool.input' => tool_input
       ) do
-        execute_action(action_str, action_input)
+        execute_action(action_str, tool_input)
       end
     end
 
-    sig { params(step: Integer, thought: String, action: String, action_input: T.untyped, observation: T.untyped).returns(HistoryEntry) }
-    def create_history_entry(step, thought, action, action_input, observation)
+    sig { params(step: Integer, thought: String, action: String, tool_input: ToolInput, observation: T.untyped).returns(HistoryEntry) }
+    def create_history_entry(step, thought, action, tool_input, observation)
       HistoryEntry.new(
         step: step,
         thought: thought,
         action: action,
-        action_input: action_input,
+        tool_input: tool_input,
         observation: observation
       )
     end
@@ -684,17 +703,17 @@ module DSPy
                         end
         handle_finish_action(forced_answer, history.last&.observation, iteration + 1, final_thought.thought, FINISH_ACTION, history)
       else
-        handle_finish_action(final_thought.action_input, history.last&.observation, iteration + 1, final_thought.thought, final_thought.action, history)
+        handle_finish_action(final_thought.final_answer, history.last&.observation, iteration + 1, final_thought.thought, final_thought.action, history)
       end
     end
 
-    sig { params(iteration: Integer, thought: String, action: String, action_input: T.untyped, observation: T.untyped, tools_used: T::Array[String]).void }
-    def emit_iteration_complete_event(iteration, thought, action, action_input, observation, tools_used)
+    sig { params(iteration: Integer, thought: String, action: String, tool_input: ToolInput, observation: T.untyped, tools_used: T::Array[String]).void }
+    def emit_iteration_complete_event(iteration, thought, action, tool_input, observation, tools_used)
       DSPy.event('react.iteration_complete', {
         'react.iteration' => iteration,
         'react.thought' => thought,
         'react.action' => action,
-        'react.action_input' => action_input,
+        'react.tool_input' => tool_input,
         'react.observation' => observation,
         'react.tools_used' => tools_used.uniq
       })
@@ -820,8 +839,8 @@ module DSPy
     end
 
     # Tool execution method
-    sig { params(action: String, action_input: T.untyped).returns(T.untyped) }
-    def execute_action(action, action_input)
+    sig { params(action: String, tool_input: ToolInput).returns(T.untyped) }
+    def execute_action(action, tool_input)
       tool_name = action.downcase
       tool = @tools[tool_name]
 
@@ -829,10 +848,10 @@ module DSPy
       raise InvalidActionError, "Tool '#{action}' not found" unless tool
 
       # Execute tool - let errors propagate
-      if action_input.nil? || (action_input.is_a?(String) && action_input.strip.empty?)
+      if tool_input.nil? || tool_input.empty?
         tool.dynamic_call({})
       else
-        tool.dynamic_call(action_input)
+        tool.dynamic_call(tool_input)
       end
     end
 
@@ -872,7 +891,7 @@ module DSPy
           step: 1,
           thought: "I need to think about this question...",
           action: "some_tool",
-          action_input: "input for tool",
+          tool_input: { "param" => "value" },
           observation: "result from tool"
         }
       ]
@@ -881,9 +900,9 @@ module DSPy
       example
     end
 
-    sig { params(action_input: T.untyped, last_observation: T.untyped, step: Integer, thought: String, action: T.any(String, T::Enum), history: T::Array[HistoryEntry]).returns(T.untyped) }
-    def handle_finish_action(action_input, last_observation, step, thought, action, history)
-      final_answer = action_input
+    sig { params(final_answer_value: T.untyped, last_observation: T.untyped, step: Integer, thought: String, action: T.any(String, T::Enum), history: T::Array[HistoryEntry]).returns(T.untyped) }
+    def handle_finish_action(final_answer_value, last_observation, step, thought, action, history)
+      final_answer = final_answer_value
 
       # If final_answer is empty/nil but we have a last observation, use it
       if (final_answer.nil? || (final_answer.is_a?(String) && final_answer.empty?)) && last_observation
@@ -893,12 +912,12 @@ module DSPy
       # Convert action enum to string for storage in history
       action_str = action.respond_to?(:serialize) ? action.serialize : action.to_s
 
-      # Always add the finish action to history
+      # Always add the finish action to history (tool_input is nil for finish actions)
       history << HistoryEntry.new(
         step: step,
         thought: thought,
         action: action_str,
-        action_input: final_answer,
+        tool_input: nil,
         observation: nil  # No observation for finish action
       )
 

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_json_schema.rb

@@ -113,16 +113,17 @@ module DSPy
         elsif type.is_a?(T::Types::TypedHash)
           # Handle hashes as objects with additionalProperties
           # TypedHash has keys and values methods to access its key and value types
-          key_schema = self.type_to_json_schema(type.keys, visited)
+          # Note: propertyNames is NOT supported by OpenAI structured outputs, so we omit it
           value_schema = self.type_to_json_schema(type.values, visited)
-          
-          # Create a more descriptive schema for nested structures
+          key_type_desc = type.keys.respond_to?(:raw_type) ? type.keys.raw_type.to_s : "string"
+          value_type_desc = value_schema[:description] || value_schema[:type].to_s
+
+          # Create a schema compatible with OpenAI structured outputs
           {
             type: "object",
-            propertyNames: key_schema,  # Describe key constraints
             additionalProperties: value_schema,
-            # Add a more explicit description of the expected structure
-            description: "A mapping where keys are #{key_schema[:type]}s and values are #{value_schema[:description] || value_schema[:type]}s"
+            # Description explains the expected structure without using propertyNames
+            description: "A mapping where keys are #{key_type_desc}s and values are #{value_type_desc}s"
           }
         elsif type.is_a?(T::Types::FixedHash)
           # Handle fixed hashes (from type aliases like { "key" => Type })

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/tools/schema.rb

@@ -0,0 +1,39 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module DSPy
+  module Tools
+    # Represents a single parameter in a tool's schema
+    # Maps to JSON Schema property definitions used by LLM tool calling
+    class ToolParameterSchema < T::Struct
+      const :type, String
+      const :description, T.nilable(String), default: nil
+      const :enum, T.nilable(T::Array[String]), default: nil
+    end
+
+    # Represents the complete schema for a tool's parameters
+    # This is the "parameters" field in LLM tool definitions
+    class ToolSchema < T::Struct
+      const :type, String, default: 'object'
+      const :properties, T::Hash[Symbol, ToolParameterSchema], default: {}
+      const :required, T::Array[String], default: []
+
+      # Convert to hash format for JSON serialization
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h
+        {
+          type: type,
+          properties: properties.transform_values do |param|
+            h = { type: param.type }
+            h[:description] = param.description if param.description
+            h[:enum] = param.enum if param.enum
+            h
+          end,
+          required: required
+        }
+      end
+    end
+  end
+end

data/lib/dspy/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.31.1
+  version: 0.33.0
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
@@ -99,14 +99,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: sorbet-toon
   requirement: !ruby/object:Gem::Requirement
@@ -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
@@ -230,6 +234,7 @@ files:
 - lib/dspy/tools/base.rb
 - lib/dspy/tools/github_cli_toolset.rb
 - lib/dspy/tools/memory_toolset.rb
+- lib/dspy/tools/schema.rb
 - lib/dspy/tools/text_processing_toolset.rb
 - lib/dspy/tools/toolset.rb
 - lib/dspy/type_serializer.rb