dspy 0.30.1 → 0.31.1

data/lib/dspy/prompt.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'sorbet-runtime'
+require 'sorbet/toon'
+
 require_relative 'few_shot_example'
+require_relative 'schema/sorbet_toon_adapter'
 
 module DSPy
   class Prompt
@@ -33,6 +37,15 @@ module DSPy
       DSPy.config.lm&.schema_format || @schema_format || :json
     end
 
+    sig { returns(Symbol) }
+    def data_format
+      return @data_format if @data_format && @data_format != :json
+
+      lm = DSPy.config.lm
+      lm_format = lm&.respond_to?(:data_format) ? lm.data_format : nil
+      lm_format || @data_format || :json
+    end
+
     sig { returns(T.nilable(T.class_of(Signature))) }
     attr_reader :signature_class
 
@@ -44,10 +57,11 @@ module DSPy
         few_shot_examples: T::Array[FewShotExample],
         signature_class_name: T.nilable(String),
         schema_format: Symbol,
-        signature_class: T.nilable(T.class_of(Signature))
+        signature_class: T.nilable(T.class_of(Signature)),
+        data_format: Symbol
       ).void
     end
-    def initialize(instruction:, input_schema:, output_schema:, few_shot_examples: [], signature_class_name: nil, schema_format: :json, signature_class: nil)
+    def initialize(instruction:, input_schema:, output_schema:, few_shot_examples: [], signature_class_name: nil, schema_format: :json, signature_class: nil, data_format: :json)
       @instruction = instruction
       @few_shot_examples = few_shot_examples.freeze
       @input_schema = input_schema.freeze
@@ -55,6 +69,7 @@ module DSPy
       @signature_class_name = signature_class_name
       @schema_format = schema_format
       @signature_class = signature_class
+      @data_format = data_format
     end
 
     # Immutable update methods for optimization
@@ -67,7 +82,8 @@ module DSPy
         few_shot_examples: @few_shot_examples,
         signature_class_name: @signature_class_name,
         schema_format: @schema_format,
-        signature_class: @signature_class
+        signature_class: @signature_class,
+        data_format: @data_format
       )
     end
 
@@ -80,7 +96,8 @@ module DSPy
         few_shot_examples: new_examples,
         signature_class_name: @signature_class_name,
         schema_format: @schema_format,
-        signature_class: @signature_class
+        signature_class: @signature_class,
+        data_format: @data_format
       )
     end
 
@@ -106,7 +123,13 @@ module DSPy
         sections << "```baml"
         sections << render_baml_schema(@output_schema, :output)
         sections << "```"
-      else  # :json (default)
+      when :toon
+        sections << "Your input schema fields (TOON order) are:"
+        sections << Sorbet::Toon::SignatureFormatter.describe_signature(@signature_class, :input)
+        sections << ""
+        sections << "Your output schema fields (TOON order) are:"
+        sections << Sorbet::Toon::SignatureFormatter.describe_signature(@signature_class, :output)
+      else
         sections << "Your input schema fields are:"
         sections << "```json"
         sections << JSON.pretty_generate(@input_schema)
@@ -117,11 +140,10 @@ module DSPy
         sections << JSON.pretty_generate(@output_schema)
         sections << "```"
       end
-      
+
       sections << ""
       sections << "All interactions will be structured in the following way, with the appropriate values filled in."
-      
-      # Add few-shot examples if present
+
       if @few_shot_examples.any?
         sections << ""
         sections << "Here are some examples:"
@@ -133,36 +155,81 @@ module DSPy
         end
       end
 
-      sections << "## Input values"
-      sections << "```json"
-      sections << "{input_values}"
-      sections << "```"
-      
-      sections << "## Output values"
-      sections << "Respond exclusively with the output schema fields in the json block below."
-      sections << "```json"
-      sections << "{output_values}"
-      sections << "```"
-      
+      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 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"
+        sections << "{input_values}"
+        sections << "```"
+
+        sections << "## Output values"
+        sections << "Respond exclusively with the output schema fields in the json block below."
+        sections << "```json"
+        sections << "{output_values}"
+        sections << "```"
+      end
+
       sections << ""
       sections << "In adhering to this structure, your objective is: #{@instruction}"
-      
+
       sections.join("\n")
     end
 
     sig { params(input_values: T::Hash[Symbol, T.untyped]).returns(String) }
     def render_user_prompt(input_values)
       sections = []
-      
-      sections << "## Input Values"
-      sections << "```json"
-      sections << JSON.pretty_generate(serialize_for_json(input_values))
-      sections << "```"
-      
-      sections << ""
-      sections << "Respond with the corresponding output schema fields wrapped in a ```json ``` block,"
-      sections << "starting with the heading `## Output values`."
-      
+
+      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`. Do not include any JSON."
+      else
+        sections << "## Input Values"
+        sections << "```json"
+        sections << JSON.pretty_generate(serialize_for_json(input_values))
+        sections << "```"
+        sections << ""
+        sections << "Respond with the corresponding output schema fields wrapped in a ```json ``` block,"
+        sections << "starting with the heading `## Output values`."
+      end
+
       sections.join("\n")
     end
 
@@ -184,7 +251,8 @@ module DSPy
         input_schema: @input_schema,
         output_schema: @output_schema,
         signature_class_name: @signature_class_name,
-        schema_format: @schema_format
+        schema_format: @schema_format,
+        data_format: @data_format
       }
     end
 
@@ -198,13 +266,24 @@ module DSPy
         output_schema: hash[:output_schema] || {},
         few_shot_examples: examples,
         signature_class_name: hash[:signature_class_name],
-        schema_format: hash[:schema_format] || :json
+        schema_format: hash[:schema_format] || :json,
+        data_format: hash[:data_format] || :json
       )
     end
 
     # Create prompt from signature class
-    sig { params(signature_class: T.class_of(Signature), schema_format: Symbol).returns(Prompt) }
-    def self.from_signature(signature_class, schema_format: :json)
+    sig do
+      params(
+        signature_class: T.class_of(Signature),
+        schema_format: T.nilable(Symbol),
+        data_format: T.nilable(Symbol)
+      ).returns(Prompt)
+    end
+    def self.from_signature(signature_class, schema_format: nil, data_format: nil)
+      lm = DSPy.config.lm
+      schema_format ||= lm&.schema_format || :json
+      data_format ||= (lm&.respond_to?(:data_format) ? lm.data_format : nil) || :json
+
       new(
         instruction: signature_class.description || "Complete this task.",
         input_schema: signature_class.input_json_schema,
@@ -212,7 +291,8 @@ module DSPy
         few_shot_examples: [],
         signature_class_name: signature_class.name,
         schema_format: schema_format,
-        signature_class: signature_class
+        signature_class: signature_class,
+        data_format: data_format
       )
     end
 
@@ -335,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
+end

data/lib/dspy/re_act.rb

@@ -98,13 +98,14 @@ module DSPy
       @tools = T.let({}, T::Hash[String, T.untyped])
       tools.each { |tool| @tools[tool.name.downcase] = tool }
       @max_iterations = max_iterations
+      @data_format = T.let(DSPy.config.lm&.data_format || :json, Symbol)
 
       # Create dynamic ActionEnum class with tool names + finish
       @action_enum_class = create_action_enum_class
 
       # Create dynamic signature classes that include the original input fields
-      thought_signature = create_thought_signature(signature_class)
-      observation_signature = create_observation_signature(signature_class)
+      thought_signature = create_thought_signature(signature_class, @data_format)
+      observation_signature = create_observation_signature(signature_class, @data_format)
 
       # Create thought generator using Predict to preserve field descriptions
       @thought_generator = T.let(DSPy::Predict.new(thought_signature), DSPy::Predict)
@@ -216,6 +217,28 @@ module DSPy
       end
     end
 
+    sig { params(input_struct: T.untyped).returns(T.untyped) }
+    def format_input_context(input_struct)
+      return input_struct if toon_data_format?
+
+      DSPy::TypeSerializer.serialize(input_struct).to_json
+    end
+
+    sig { params(history: T::Array[HistoryEntry]).returns(T.untyped) }
+    def format_history(history)
+      toon_data_format? ? history : serialize_history_for_llm(history)
+    end
+
+    sig { params(observation: T.untyped).returns(T.untyped) }
+    def format_observation(observation)
+      toon_data_format? ? observation : serialize_for_llm(observation)
+    end
+
+    sig { returns(T::Boolean) }
+    def toon_data_format?
+      @data_format == :toon
+    end
+
     # Creates a dynamic ActionEnum class with tool names and "finish"
     sig { returns(T.class_of(T::Enum)) }
     def create_action_enum_class
@@ -241,9 +264,14 @@ module DSPy
     end
 
     # Creates a dynamic Thought signature that includes the original input fields
-    sig { params(signature_class: T.class_of(DSPy::Signature)).returns(T.class_of(DSPy::Signature)) }
-    def create_thought_signature(signature_class)
+    sig { params(signature_class: T.class_of(DSPy::Signature), data_format: Symbol).returns(T.class_of(DSPy::Signature)) }
+    def create_thought_signature(signature_class, data_format)
       action_enum_class = @action_enum_class
+      input_context_type = if data_format == :toon
+        signature_class.input_struct_class || String
+      else
+        String
+      end
       # Create new class that inherits from DSPy::Signature
       Class.new(DSPy::Signature) do
         # Set description
@@ -251,8 +279,8 @@ module DSPy
 
         # Define input fields
         input do
-          const :input_context, String,
-            description: "Serialized representation of all input fields"
+          const :input_context, input_context_type,
+            description: data_format == :toon ? "All original input fields with their typed values" : "Serialized representation of all input fields"
           const :history, T::Array[HistoryEntry],
             description: "Previous thoughts and actions, including observations from tools."
           const :available_tools, T::Array[AvailableTool],
@@ -272,8 +300,13 @@ module DSPy
     end
 
     # Creates a dynamic observation signature that includes the original input fields
-    sig { params(signature_class: T.class_of(DSPy::Signature)).returns(T.class_of(DSPy::Signature)) }
-    def create_observation_signature(signature_class)
+    sig { params(signature_class: T.class_of(DSPy::Signature), data_format: Symbol).returns(T.class_of(DSPy::Signature)) }
+    def create_observation_signature(signature_class, data_format)
+      input_context_type = if data_format == :toon
+        signature_class.input_struct_class || String
+      else
+        String
+      end
       # Create new class that inherits from DSPy::Signature
       Class.new(DSPy::Signature) do
         # Set description
@@ -281,8 +314,8 @@ module DSPy
 
         # Define input fields
         input do
-          const :input_context, String,
-            description: "Serialized representation of all input fields"
+          const :input_context, input_context_type,
+            description: data_format == :toon ? "All original input fields with their typed values" : "Serialized representation of all input fields"
           const :history, T::Array[HistoryEntry],
             description: "Previous thoughts, actions, and observations."
           const :observation, T.untyped,
@@ -358,8 +391,8 @@ module DSPy
       ) do
         # Generate thought and action
         thought_obj = @thought_generator.forward(
-          input_context: DSPy::TypeSerializer.serialize(input_struct).to_json,
-          history: serialize_history_for_llm(history),
+          input_context: format_input_context(input_struct),
+          history: format_history(history),
           available_tools: available_tools_desc
         )
 
@@ -617,9 +650,9 @@ module DSPy
     sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], observation: T.untyped, available_tools_desc: T::Array[AvailableTool], iteration: Integer).returns(T::Hash[Symbol, T.untyped]) }
     def process_observation_and_decide_next_step(input_struct, history, observation, available_tools_desc, iteration)
       observation_result = @observation_processor.forward(
-        input_context: DSPy::TypeSerializer.serialize(input_struct).to_json,
-        history: serialize_history_for_llm(history),
-        observation: serialize_for_llm(observation)
+        input_context: format_input_context(input_struct),
+        history: format_history(history),
+        observation: format_observation(observation)
       )
 
       return { should_finish: false } unless observation_result.next_step == NextStep::Finish
@@ -634,8 +667,8 @@ module DSPy
     sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], available_tools_desc: T::Array[AvailableTool], observation_result: T.untyped, iteration: Integer).returns(T.untyped) }
     def generate_forced_final_answer(input_struct, history, available_tools_desc, observation_result, iteration)
       final_thought = @thought_generator.forward(
-        input_context: DSPy::TypeSerializer.serialize(input_struct).to_json,
-        history: serialize_history_for_llm(history),
+        input_context: format_input_context(input_struct),
+        history: format_history(history),
         available_tools: available_tools_desc
       )
 

data/lib/dspy/schema/sorbet_json_schema.rb

@@ -254,10 +254,13 @@ module DSPy
                                        "DSPy uses _type for automatic type detection in union types."
         end
 
+        struct_name = struct_class.name || "Struct#{format('%x', struct_class.object_id)}"
+        simple_name = struct_name.split('::').last || struct_name
+
         # Add automatic _type field for type detection
         properties[:_type] = {
           type: "string",
-          const: struct_class.name.split('::').last  # Use the simple class name
+          const: simple_name  # Use the simple class name
         }
         required << "_type"
 
@@ -280,7 +283,7 @@ module DSPy
           type: "object",
           properties: properties,
           required: required,
-          description: "#{struct_class.name} struct"
+          description: "#{struct_name} struct"
         }
       end
 

data/lib/dspy/schema/sorbet_toon_adapter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require 'sorbet/toon'
+
+require_relative '../lm/errors'
+
+module DSPy
+  module Schema
+    module SorbetToonAdapter
+      extend T::Sig
+
+      module_function
+
+      sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), values: T::Hash[Symbol, T.untyped]).returns(String) }
+      def render_input(signature_class, values)
+        Sorbet::Toon.encode(
+          values,
+          signature: signature_class,
+          role: :input
+        )
+      end
+
+      sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), values: T::Hash[Symbol, T.untyped]).returns(String) }
+      def render_expected_output(signature_class, values)
+        Sorbet::Toon.encode(
+          values,
+          signature: signature_class,
+          role: :output
+        )
+      end
+
+      sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), toon_string: String).returns(T.untyped) }
+      def parse_output(signature_class, toon_string)
+        payload = strip_code_fences(toon_string)
+
+        Sorbet::Toon.decode(
+          payload,
+          signature: signature_class,
+          role: :output,
+          strict: false
+        )
+      rescue Sorbet::Toon::DecodeError => e
+        log_decode_error(payload, e)
+        raise DSPy::LM::AdapterError,
+              "Failed to parse TOON response: #{e.message}. Ensure the model replies with a ```toon``` block using the schema described in the system prompt."
+      end
+
+      sig { params(text: T.nilable(String)).returns(String) }
+      def strip_code_fences(text)
+        return '' if text.nil?
+
+        match = text.match(/```(?:toon)?\s*(.*?)```/m)
+        return match[1].strip if match
+
+        text.strip
+      end
+
+      sig { params(payload: String, error: StandardError).void }
+      def log_decode_error(payload, error)
+        logger = DSPy.logger if DSPy.respond_to?(:logger)
+        return unless logger.respond_to?(:warn)
+
+        preview = payload.to_s.lines.first(5).join
+        logger.warn(
+          event: 'toon.decode_error',
+          error: error.message,
+          preview: preview,
+          length: payload.to_s.length
+        )
+      end
+
+      sig { params(signature_class: T.nilable(T.class_of(DSPy::Signature)), role: Symbol).returns(String) }
+      def field_guidance(signature_class, role)
+        return '' unless signature_class
+
+        Sorbet::Toon::SignatureFormatter.describe_signature(signature_class, role)
+      end
+    end
+  end
+end

data/lib/dspy/structured_outputs_prompt.rb

@@ -17,10 +17,11 @@ module DSPy
         few_shot_examples: T::Array[T.untyped],
         signature_class_name: T.nilable(String),
         schema_format: Symbol,
-        signature_class: T.nilable(T.class_of(Signature))
+        signature_class: T.nilable(T.class_of(Signature)),
+        data_format: Symbol
       ).void
     end
-    def initialize(instruction:, input_schema:, output_schema:, few_shot_examples: [], signature_class_name: nil, schema_format: :json, signature_class: nil)
+    def initialize(instruction:, input_schema:, output_schema:, few_shot_examples: [], signature_class_name: nil, schema_format: :json, signature_class: nil, data_format: :json)
       normalized_examples = few_shot_examples.map do |example|
         case example
         when FewShotExample
@@ -39,7 +40,8 @@ module DSPy
         few_shot_examples: normalized_examples,
         signature_class_name: signature_class_name,
         schema_format: schema_format,
-        signature_class: signature_class
+        signature_class: signature_class,
+        data_format: data_format
       )
     end
 

data/lib/dspy/type_serializer.rb

@@ -17,6 +17,7 @@ module DSPy
       when Hash
         value.transform_values { |v| serialize(v) }
       else
+        return serialize(value.serialize) if value.respond_to?(:serialize)
         value
       end
     end
@@ -52,4 +53,4 @@ module DSPy
       result
     end
   end
-end
+end

data/lib/dspy/version.rb

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