dspy 0.34.3 → 0.34.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01f38786c88d525a1031cf41931f578c3d2dcbfa29ee6a8dac1a381cafe47edf
-  data.tar.gz: 6334bfb483b3011fa91e163f688127be763a126ea7cd0edc44f07b0557dc2a30
+  metadata.gz: 5d5296e0130d0550156345659e6703451bd6ca6fb9ffbac33d8584ee203f2a84
+  data.tar.gz: 339772eb768a2babbb8b700b868fc772183473b7cf4f8a6867e55945f75a3655
 SHA512:
-  metadata.gz: 744087dd87e936b247d194539407f2a74b29d5e6a28b4ba872c4aa0ef77103c4a6957c97b6bed3ee7e8ef899824f3e6e0f40c2b429c47312aa10924bb1fbca3c
-  data.tar.gz: 4e343687e84570d199ce9c7695d19d0a0a551cac66693fda131fe03268d3907e2d20f4648530d1e6a5de0a73092b03f3ec7bcec877d9c23662332193aaee0e31
+  metadata.gz: 827360cba1ad8d03373d40d9b1b9ce3acf966e896261b918537150568cf4635904e591c238cdea7d8e8bf45980851ce3c581f709639215c8d7e4c7e1ea78dc08
+  data.tar.gz: e8d91df3e7204ac0d0db830c5839a4cbdd9683a00be2a77dec38de156052f0a0b3956e25c8b7026fcce23880e9806fc9af023fc2a4fe830926f288f82474a85b

data/README.md

@@ -137,26 +137,18 @@ result.answer     # => "60 km/h"
 Build agents that use tools to accomplish tasks:
 
 ```ruby
-class SearchTool < DSPy::Tools::Tool
+class SearchTool < DSPy::Tools::Base
   tool_name "search"
-  description "Search for information"
-
-  input do
-    const :query, String
-  end
-
-  output do
-    const :results, T::Array[String]
-  end
+  tool_description "Search for information"
 
+  sig { params(query: String).returns(String) }
   def call(query:)
     # Your search implementation
-    { results: ["Result 1", "Result 2"] }
+    "Result 1, Result 2"
   end
 end
 
-toolset = DSPy::Tools::Toolset.new(tools: [SearchTool.new])
-agent = DSPy::ReAct.new(signature: ResearchTask, tools: toolset, max_iterations: 5)
+agent = DSPy::ReAct.new(ResearchTask, tools: [SearchTool.new], max_iterations: 5)
 result = agent.call(question: "What's the latest on Ruby 3.4?")
 ```
 
@@ -185,8 +177,8 @@ result = agent.call(question: "What's the latest on Ruby 3.4?")
 A [Claude Skill](https://github.com/vicentereig/dspy-rb-skill) is available to help you build DSPy.rb applications:
 
 ```bash
-# Claude Code
-git clone https://github.com/vicentereig/dspy-rb-skill ~/.claude/skills/dspy-rb
+# Claude Code — install from the vicentereig/engineering marketplace
+claude install-skill vicentereig/engineering --skill dspy-rb
 ```
 
 For Claude.ai Pro/Max, download the [skill ZIP](https://github.com/vicentereig/dspy-rb-skill/archive/refs/heads/main.zip) and upload via Settings > Skills.
@@ -201,7 +193,7 @@ The [examples/](examples/) directory has runnable code for common patterns:
 - Prompt optimization
 
 ```bash
-bundle exec ruby examples/first_predictor.rb
+bundle exec ruby examples/basic_search_agent.rb
 ```
 
 ## Optional Gems

data/lib/dspy/context.rb

@@ -74,8 +74,9 @@ module DSPy
             # Prepare attributes and add trace name for root spans
             span_attributes = sanitized_attributes.transform_keys(&:to_s).reject { |k, v| v.nil? }
             
-            # Set trace name if this is likely a root span (no parent in our stack)
-            if current[:span_stack].length == 1  # This will be the first span
+            # Set trace name if this is likely a root span (no parent in our stack),
+            # unless callers already specified one explicitly.
+            if current[:span_stack].length == 1 && !span_attributes.key?('langfuse.trace.name')
               span_attributes['langfuse.trace.name'] = operation
             end
             
@@ -84,6 +85,12 @@ module DSPy
             
             # Get parent OpenTelemetry span for proper context propagation
             parent_otel_span = current[:otel_span_stack].last
+            if !parent_otel_span && defined?(OpenTelemetry::Trace)
+              current_span = OpenTelemetry::Trace.current_span
+              if current_span && current_span != OpenTelemetry::Trace::Span::INVALID
+                parent_otel_span = current_span
+              end
+            end
             
             # Create span with proper parent context
             if parent_otel_span
@@ -96,20 +103,18 @@ module DSPy
                 ) do |span|
                   # Add to our OpenTelemetry span stack
                   current[:otel_span_stack].push(span)
+                  succeeded = false
                   
                   begin
                     result = yield(span)
-                    
-                    # Add explicit timing information to help Langfuse
-                    if span
-                      duration_ms = ((Time.now - otel_start_time) * 1000).round(3)
-                      span.set_attribute('duration.ms', duration_ms)
-                      span.set_attribute('langfuse.observation.startTime', otel_start_time.iso8601(3))
-                      span.set_attribute('langfuse.observation.endTime', Time.now.iso8601(3))
-                    end
-                    
+                    succeeded = true
                     result
+                  rescue StandardError => e
+                    set_span_error_attributes(span, e)
+                    raise
                   ensure
+                    set_span_status_attribute(span, succeeded)
+                    set_span_timing_attributes(span, otel_start_time)
                     # Remove from our OpenTelemetry span stack
                     current[:otel_span_stack].pop
                   end
@@ -124,20 +129,18 @@ module DSPy
               ) do |span|
                 # Add to our OpenTelemetry span stack
                 current[:otel_span_stack].push(span)
+                succeeded = false
                 
                 begin
                   result = yield(span)
-                  
-                  # Add explicit timing information to help Langfuse
-                  if span
-                    duration_ms = ((Time.now - otel_start_time) * 1000).round(3)
-                    span.set_attribute('duration.ms', duration_ms)
-                    span.set_attribute('langfuse.observation.startTime', otel_start_time.iso8601(3))
-                    span.set_attribute('langfuse.observation.endTime', Time.now.iso8601(3))
-                  end
-                  
+                  succeeded = true
                   result
+                rescue StandardError => e
+                  set_span_error_attributes(span, e)
+                  raise
                 ensure
+                  set_span_status_attribute(span, succeeded)
+                  set_span_timing_attributes(span, otel_start_time)
                   # Remove from our OpenTelemetry span stack
                   current[:otel_span_stack].pop
                 end
@@ -296,6 +299,36 @@ module DSPy
           label: explicit_label || (module_instance.respond_to?(:module_scope_label) ? module_instance.module_scope_label : nil)
         }
       end
+
+      def set_span_timing_attributes(span, otel_start_time)
+        return unless span
+
+        now = Time.now
+        duration_ms = ((now - otel_start_time) * 1000).round(3)
+        span.set_attribute('duration.ms', duration_ms)
+        span.set_attribute('langfuse.observation.startTime', otel_start_time.iso8601(3))
+        span.set_attribute('langfuse.observation.endTime', now.iso8601(3))
+      rescue StandardError
+        nil
+      end
+
+      def set_span_error_attributes(span, error)
+        return unless span
+
+        span.set_attribute('error', true)
+        span.set_attribute('error.type', error.class.name)
+        span.set_attribute('error.message', error.message.to_s[0, 2000]) if error.message
+      rescue StandardError
+        nil
+      end
+
+      def set_span_status_attribute(span, succeeded)
+        return unless span
+
+        span.set_attribute('dspy.status', succeeded ? 'completed' : 'error')
+      rescue StandardError
+        nil
+      end
     end
   end
 end

data/lib/dspy/lm/json_strategy.rb

@@ -38,17 +38,8 @@ module DSPy
           # OpenAI/Ollama: try to extract JSON from various formats
           extract_json_from_content(response.content)
         elsif adapter_class_name.include?('AnthropicAdapter')
-          # Anthropic: try tool use first if structured_outputs enabled, else use content extraction
-          structured_outputs_enabled = adapter.instance_variable_get(:@structured_outputs_enabled)
-          structured_outputs_enabled = true if structured_outputs_enabled.nil?  # Default to true
-
-          if structured_outputs_enabled
-            extracted = extract_anthropic_tool_json(response)
-            extracted || extract_json_from_content(response.content)
-          else
-            # Skip tool extraction, use enhanced prompting extraction
-            extract_json_from_content(response.content)
-          end
+          # Anthropic: Beta API returns JSON in content, same as OpenAI/Gemini
+          extract_json_from_content(response.content)
         elsif adapter_class_name.include?('GeminiAdapter')
           # Gemini: try to extract JSON from various formats
           extract_json_from_content(response.content)
@@ -90,25 +81,30 @@ module DSPy
       # Anthropic preparation
       sig { params(messages: T::Array[T::Hash[Symbol, T.untyped]], request_params: T::Hash[Symbol, T.untyped]).void }
       def prepare_anthropic_request(messages, request_params)
-        # Only use tool-based extraction if structured_outputs is enabled (default: true)
-        structured_outputs_enabled = adapter.instance_variable_get(:@structured_outputs_enabled)
+        begin
+          require "dspy/anthropic/lm/schema_converter"
+        rescue LoadError
+          msg = <<~MSG
+            Anthropic adapter is optional; structured output helpers will be unavailable until the gem is installed.
+            Add `gem 'dspy-anthropic'` to your Gemfile and run `bundle install`.
+          MSG
+          raise DSPy::LM::MissingAdapterError, msg
+        end
 
-        # Default to true if not set (backward compatibility)
+        # Only use Beta API structured outputs if enabled (default: true)
+        structured_outputs_enabled = adapter.instance_variable_get(:@structured_outputs_enabled)
         structured_outputs_enabled = true if structured_outputs_enabled.nil?
 
         return unless structured_outputs_enabled
 
-        # Convert signature to tool schema
-        tool_schema = convert_to_anthropic_tool_schema
-
-        # Add tool definition
-        request_params[:tools] = [tool_schema]
+        # Use Anthropic Beta API structured outputs
+        schema = DSPy::Anthropic::LM::SchemaConverter.to_beta_format(signature_class)
 
-        # Force tool use
-        request_params[:tool_choice] = {
-          type: "tool",
-          name: "json_output"
-        }
+        request_params[:output_format] = ::Anthropic::Models::Beta::BetaJSONOutputFormat.new(
+          type: :json_schema,
+          schema: schema
+        )
+        request_params[:betas] = ["structured-outputs-2025-11-13"]
       end
 
       # Gemini preparation
@@ -135,89 +131,19 @@ module DSPy
         end
       end
 
-      # Convert signature to Anthropic tool schema
-      # Uses strict: true for constrained decoding (Anthropic structured outputs)
-      # Anthropic strict mode requires ALL properties in required at every level.
-      sig { returns(T::Hash[Symbol, T.untyped]) }
-      def convert_to_anthropic_tool_schema
-        output_fields = signature_class.output_field_descriptors
-
-        schema = {
-          name: "json_output",
-          description: "Output the result in the required JSON format",
-          strict: true,
-          input_schema: {
-            type: "object",
-            properties: build_properties_from_fields(output_fields),
-            required: build_required_from_fields(output_fields),
-            additionalProperties: false
-          }
-        }
-
-        # Anthropic strict mode: ALL properties must be in required at every level.
-        # Non-required properties get auto-wrapped in null unions by the grammar compiler,
-        # which counts against the 16-union-parameter limit.
-        enforce_all_required(schema[:input_schema])
-
-        schema
-      end
-
-      # Build required field list, excluding fields that have defaults
-      sig { params(fields: T::Hash[Symbol, T.untyped]).returns(T::Array[String]) }
-      def build_required_from_fields(fields)
-        fields.reject { |_name, descriptor| descriptor.has_default }.keys.map(&:to_s)
-      end
-
-      # Recursively enforce that all properties are in required and
-      # additionalProperties is false, as required by Anthropic strict mode.
-      sig { params(schema: T::Hash[Symbol, T.untyped]).void }
-      def enforce_all_required(schema)
-        return unless schema.is_a?(Hash)
-
-        if schema[:type] == "object" && schema[:properties]
-          schema[:required] = schema[:properties].keys.map(&:to_s)
-          schema[:additionalProperties] = false
-          schema[:properties].each_value { |v| enforce_all_required(v) }
-        elsif schema[:type] == "array" && schema[:items]
-          enforce_all_required(schema[:items])
-        elsif schema[:type].is_a?(Array)
-          # type: ["array", "null"] — check items if present
-          enforce_all_required(schema[:items]) if schema[:items]
-        end
-      end
-
-      # Build JSON schema properties from output fields
-      sig { params(fields: T::Hash[Symbol, T.untyped]).returns(T::Hash[String, T.untyped]) }
-      def build_properties_from_fields(fields)
-        properties = {}
-        fields.each do |field_name, descriptor|
-          properties[field_name.to_s] = DSPy::TypeSystem::SorbetJsonSchema.type_to_json_schema(descriptor.type)
-        end
-        properties
-      end
-
-      # Extract JSON from Anthropic tool use response
-      sig { params(response: DSPy::LM::Response).returns(T.nilable(String)) }
-      def extract_anthropic_tool_json(response)
-        # Check for tool calls in metadata
-        if response.metadata.respond_to?(:tool_calls) && response.metadata.tool_calls
-          tool_calls = response.metadata.tool_calls
-          if tool_calls.is_a?(Array) && !tool_calls.empty?
-            first_call = tool_calls.first
-            if first_call[:name] == "json_output" && first_call[:input]
-              return JSON.generate(first_call[:input])
-            end
-          end
-        end
-
-        nil
-      end
-
       # Extract JSON from content that may contain markdown or plain JSON
       sig { params(content: String).returns(String) }
       def extract_json_from_content(content)
         return content if content.nil? || content.empty?
 
+        # Fix Anthropic Beta API bug with optional fields producing invalid JSON
+        # When some output fields are optional and not returned, Anthropic's structured outputs
+        # can produce trailing comma+brace: {"field1": {...},} instead of {"field1": {...}}
+        # This workaround removes the invalid trailing syntax before JSON parsing
+        if content =~ /,\s*\}\s*$/
+          content = content.sub(/,(\s*\}\s*)$/, '\1')
+        end
+
         # Try 1: Check for ```json code block (with or without preceding text)
         if content.include?('```json')
           json_match = content.match(/```json\s*\n(.*?)\n```/m)

data/lib/dspy/lm/response.rb

@@ -118,7 +118,7 @@ module DSPy
       extend T::Sig
       
       const :content, String
-      const :usage, T.nilable(T.any(Usage, OpenAIUsage)), default: nil
+      const :usage, T.nilable(T.any(Usage, OpenAIUsage, AnthropicUsage)), default: nil
       const :metadata, T.any(ResponseMetadata, OpenAIResponseMetadata, AnthropicResponseMetadata, GeminiResponseMetadata, T::Hash[Symbol, T.untyped])
       
       sig { returns(String) }

data/lib/dspy/lm/usage.rb

@@ -45,11 +45,34 @@ module DSPy
       end
     end
     
+    # Anthropic-specific usage information with cache token fields
+    class AnthropicUsage < T::Struct
+      extend T::Sig
+
+      const :input_tokens, Integer
+      const :output_tokens, Integer
+      const :total_tokens, Integer
+      const :cache_creation_input_tokens, T.nilable(Integer), default: nil
+      const :cache_read_input_tokens, T.nilable(Integer), default: nil
+
+      sig { returns(Hash) }
+      def to_h
+        base = {
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          total_tokens: total_tokens
+        }
+        base[:cache_creation_input_tokens] = cache_creation_input_tokens unless cache_creation_input_tokens.nil?
+        base[:cache_read_input_tokens] = cache_read_input_tokens unless cache_read_input_tokens.nil?
+        base
+      end
+    end
+
     # Factory for creating appropriate usage objects
     module UsageFactory
       extend T::Sig
       
-      sig { params(provider: String, usage_data: T.untyped).returns(T.nilable(T.any(Usage, OpenAIUsage))) }
+      sig { params(provider: String, usage_data: T.untyped).returns(T.nilable(T.any(Usage, OpenAIUsage, AnthropicUsage))) }
       def self.create(provider, usage_data)
         return nil if usage_data.nil?
         
@@ -121,17 +144,19 @@ module DSPy
         nil
       end
       
-      sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.nilable(Usage)) }
+      sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.nilable(AnthropicUsage)) }
       def self.create_anthropic_usage(data)
         # Anthropic uses input_tokens/output_tokens
         input_tokens = data[:input_tokens] || 0
         output_tokens = data[:output_tokens] || 0
         total_tokens = data[:total_tokens] || (input_tokens + output_tokens)
-        
-        Usage.new(
+
+        AnthropicUsage.new(
           input_tokens: input_tokens,
           output_tokens: output_tokens,
-          total_tokens: total_tokens
+          total_tokens: total_tokens,
+          cache_creation_input_tokens: data[:cache_creation_input_tokens],
+          cache_read_input_tokens: data[:cache_read_input_tokens]
         )
       rescue StandardError => e
         DSPy.logger.debug("Failed to create Anthropic usage: #{e.message}")
@@ -173,4 +198,4 @@ module DSPy
       end
     end
   end
-end
+end

data/lib/dspy/lm.rb

@@ -305,6 +305,12 @@ module DSPy
             span.set_attribute('gen_ai.usage.prompt_tokens', usage.input_tokens) if usage.input_tokens
             span.set_attribute('gen_ai.usage.completion_tokens', usage.output_tokens) if usage.output_tokens
             span.set_attribute('gen_ai.usage.total_tokens', usage.total_tokens) if usage.total_tokens
+            if usage.respond_to?(:cache_creation_input_tokens) && !usage.cache_creation_input_tokens.nil?
+              span.set_attribute('gen_ai.usage.cache_creation_input_tokens', usage.cache_creation_input_tokens)
+            end
+            if usage.respond_to?(:cache_read_input_tokens) && !usage.cache_read_input_tokens.nil?
+              span.set_attribute('gen_ai.usage.cache_read_input_tokens', usage.cache_read_input_tokens)
+            end
           end
         end
 
@@ -356,11 +362,16 @@ module DSPy
       
       # Handle Usage struct objects
       if response.usage.respond_to?(:input_tokens)
-        return {
+        result = {
           input_tokens: response.usage.input_tokens,
           output_tokens: response.usage.output_tokens,
           total_tokens: response.usage.total_tokens
-        }.compact
+        }
+        if response.usage.respond_to?(:cache_creation_input_tokens)
+          result[:cache_creation_input_tokens] = response.usage.cache_creation_input_tokens
+          result[:cache_read_input_tokens] = response.usage.cache_read_input_tokens
+        end
+        return result.compact
       end
       
       # Handle hash-based usage (for VCR compatibility)

data/lib/dspy/mixins/type_coercion.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require 'sorbet-runtime'
+require 'yaml'
 
 module DSPy
   module Mixins
@@ -88,6 +89,15 @@ module DSPy
         case prop_type
         when ->(type) { union_type?(type) }
           coerce_union_value(value, prop_type)
+        when ->(type) { nilable_type?(type) }
+          # Unwrap T.nilable(X) to coerce as X (nil already handled above)
+          non_nil_types = prop_type.types.reject { |t| t == T::Utils.coerce(NilClass) }
+          if non_nil_types.size == 1
+            coerce_value_to_type(value, non_nil_types.first)
+          else
+            # T.any(A, B, NilClass) — rebuild as T.any(A, B) and coerce as union
+            coerce_union_value(value, T::Types::Union.new(non_nil_types))
+          end
         when ->(type) { array_type?(type) }
           coerce_array_value(value, prop_type)
         when ->(type) { hash_type?(type) }
@@ -161,15 +171,31 @@ module DSPy
       # Checks if a type is a union type (T.any)
       sig { params(type: T.untyped).returns(T::Boolean) }
       def union_type?(type)
-        type.is_a?(T::Types::Union) && !is_nilable_type?(type)
+        type.is_a?(T::Types::Union) && !nilable_type?(type)
       end
 
       # Checks if a type is nilable (contains NilClass)
       sig { params(type: T.untyped).returns(T::Boolean) }
-      def is_nilable_type?(type)
+      def nilable_type?(type)
         type.is_a?(T::Types::Union) && type.types.any? { |t| t == T::Utils.coerce(NilClass) }
       end
 
+      # Checks if a union type is a simple nilable struct (T.nilable(SomeStruct))
+      # Returns true only if the union has exactly 2 types: NilClass and a Struct
+      sig { params(union_type: T.untyped).returns(T::Boolean) }
+      def nilable_struct_union?(union_type)
+        return false unless union_type.is_a?(T::Types::Union)
+
+        types = union_type.types
+        return false unless types.size == 2
+
+        # One type must be NilClass, the other must be a struct
+        has_nil = types.any? { |t| t == T::Utils.coerce(NilClass) }
+        struct_type = types.find { |t| t != T::Utils.coerce(NilClass) && struct_type?(t) }
+
+        has_nil && !struct_type.nil?
+      end
+
       # Checks if a type is a scalar (primitives that don't need special serialization)
       sig { params(type_object: T.untyped).returns(T::Boolean) }
       def scalar_type?(type_object)
@@ -283,9 +309,11 @@ module DSPy
       # Coerces a hash value, converting keys and values as needed
       sig { params(value: T.untyped, prop_type: T.untyped).returns(T.untyped) }
       def coerce_hash_value(value, prop_type)
-        return value unless value.is_a?(Hash)
         return value unless prop_type.is_a?(T::Types::TypedHash)
-        
+
+        value = try_parse_string_to_hash(value)
+        return value unless value.is_a?(Hash)
+
         key_type = prop_type.keys
         value_type = prop_type.values
         
@@ -302,9 +330,41 @@ module DSPy
         result.transform_values { |v| coerce_value_to_type(v, value_type) }
       end
 
+      # Attempts to parse a string into a Hash.
+      # Returns the parsed Hash on success, or the original value otherwise.
+      sig { params(value: T.untyped).returns(T.untyped) }
+      def try_parse_string_to_hash(value)
+        return value unless value.is_a?(String)
+
+        parsed = begin
+          JSON.parse(value)
+        rescue JSON::ParserError
+          YAML.safe_load(value, permitted_classes: [Symbol, Date, Time])
+        end
+
+        parsed.is_a?(Hash) ? parsed : value
+      rescue Psych::SyntaxError
+        value
+      end
+
+      # Attempts to parse a JSON string into a Hash.
+      # Returns the parsed Hash on success, or the original value otherwise.
+      sig { params(value: T.untyped).returns(T.untyped) }
+      def try_parse_json_to_hash(value)
+        return value unless value.is_a?(String)
+
+        parsed = JSON.parse(value)
+        parsed.is_a?(Hash) ? parsed : value
+      rescue JSON::ParserError
+        value
+      end
+
       # Coerces a struct value from a hash
       sig { params(value: T.untyped, prop_type: T.untyped).returns(T.untyped) }
       def coerce_struct_value(value, prop_type)
+        # Anthropic tool use may return struct fields as JSON strings
+        value = try_parse_json_to_hash(value)
+
         return value unless value.is_a?(Hash)
 
         struct_class = if prop_type.is_a?(Class)
@@ -347,7 +407,7 @@ module DSPy
           next false unless prop_info
           prop_type = prop_info[:type_object] || prop_info[:type]
           has_default = prop_info.key?(:default) || prop_info[:fully_optional]
-          !is_nilable_type?(prop_type) && has_default
+          !nilable_type?(prop_type) && has_default
         end
 
         # Create the struct instance
@@ -363,18 +423,20 @@ module DSPy
       def coerce_union_value(value, union_type)
         # Anthropic tool use may return complex oneOf union fields as JSON strings
         # instead of nested objects. Parse them back into Hashes for coercion.
-        if value.is_a?(String)
-          begin
-            parsed = JSON.parse(value)
-            value = parsed if parsed.is_a?(Hash)
-          rescue JSON::ParserError
-            # Not JSON — fall through
-          end
-        end
+        value = try_parse_json_to_hash(value)
 
         return value unless value.is_a?(Hash)
 
-        # Check for _type discriminator field
+        # Handle nilable struct unions (T.nilable(SomeStruct)) without _type discriminator
+        # LLMs don't provide _type for simple nilable structs, so we can directly coerce
+        if nilable_struct_union?(union_type)
+          struct_type = union_type.types.find { |t|
+            t != T::Utils.coerce(NilClass) && struct_type?(t)
+          }
+          return coerce_struct_value(value, struct_type) if struct_type
+        end
+
+        # Check for _type discriminator field (required for true multi-type unions)
         type_name = value[:_type] || value["_type"]
         return value unless type_name