lex-llm 0.5.0 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ab0a51687719efbd7f048be70ff4ba57b6d81fafddfcaefb2f0d78f5f3721ae
-  data.tar.gz: 49e57ce1c99330d956cc92b6c6a75a283f078f5e0b8fb036ae7aad9579caccd0
+  metadata.gz: 97ce32819eeea5c69b1278c3bab36876fc420f7092d9428da4e801fe26073601
+  data.tar.gz: c91d281b0994aea741558c7ffacced69626da499c2bc7876a58c591b50f56137
 SHA512:
-  metadata.gz: 8d8fcea6f732dd4c5dfcd713024796a640941d18c8ef90f3c5b5ca0b3fcbc0094942f2cadabbdd78669ecabce8cd76f893488a92f15ec70c21ebec865fb0a531
-  data.tar.gz: 4a062635e491cb84b60117b1c28520a8fc5bb4d0775609ed1104639e549114c2a373e68461833008a234e33d7ac14a5fe1292cc2f37fe37b0f00818387cc4851
+  metadata.gz: 931eb07b958e676e014804e044c8da11dfc42c866345b6a187c08294da0070e88b2fb30dc569c577a99ee2de95a5f4d55572c8b05ce6d79f327f3ec4a48a8350
+  data.tar.gz: 78450fa24b76f759218776b30b80a4d693b0395f58828d79593cb1ce4e640c8ca281f423dcc83144220707e837fd00c76bfc9c600c6382e209e18966d92fc5e6

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.5.3 - 2026-06-16
+
+### Fixed
+- **Streaming error classification** — Partial non-2xx streaming responses now raise status-specific errors (`UnauthorizedError`, `ForbiddenError`, `RateLimitError`, `ServiceUnavailableError`, etc.) instead of always raising `ServerError`. This preserves auth failures for downstream escalation and circuit handling.
+
+## 0.5.2 - 2026-06-15
+
+### Added
+- **CapabilityPolicy module** — Shared capability resolution with 7-layer precedence chain (model_override > instance_override > provider_override > model_metadata > provider_catalog > probe > provider_envelope > default_false). All optional capabilities default false.
+- **Boolean aliases** — `enable_thinking`, `tools_flag`, `embedding_flag`, etc. map to canonical capability keys at any settings level.
+- **ModelOffering#capability_sources** — Per-capability source metadata preserved through offering serialization.
+- **Provider#offering_from_model** — Base class now generates `:model_metadata` source tags for capabilities from provider API responses.
+
+## 0.5.1 - 2026-06-12
+
+### Fixed
+- **ToolDefinition constants** — Move `OBJECT_SCHEMA_KEYWORDS` and `COMPOSITE_SCHEMA_KEYWORDS` out of `Data.define` block to satisfy `Lint/ConstantDefinitionInBlock`.
+- **ToolSchema documentation** — Add top-level module documentation comment.
+- **Conformance spec cleanup** — Remove unused block argument from shared examples, fix duplicate describe block and context wording in tool_definition_spec.
+- **RuboCop clean** — Zero offenses across 140 files.
+
 ## 0.5.0 - 2026-06-10
 
 ### Added

data/lib/legion/extensions/llm/canonical/message.rb

@@ -72,11 +72,24 @@ module Legion
               h[:content] = ContentBlock.from_hash(content)
             end
 
-            # Parse tool calls if they're an array of hashes
+            # Parse tool calls — Array is canonical; Hash is legacy lex-llm format (name → ToolCall)
             tool_calls = h[:tool_calls]
-            if tool_calls.is_a?(Array)
+            if tool_calls.is_a?(Hash)
+              h[:tool_calls] = tool_calls.values.map do |tc|
+                next tc if tc.is_a?(ToolCall)
+
+                raw = tc.respond_to?(:to_h) ? tc.to_h : tc
+                ToolCall.from_hash(raw)
+              end
+            elsif tool_calls.is_a?(Array)
               h[:tool_calls] = tool_calls.map do |tc|
-                tc.is_a?(ToolCall) ? tc : ToolCall.from_hash(tc)
+                next tc if tc.is_a?(ToolCall)
+
+                if tc.is_a?(Hash)
+                  ToolCall.from_hash(tc)
+                else
+                  ToolCall.from_hash(tc.respond_to?(:to_h) ? tc.to_h : tc)
+                end
               end
             end
 

data/lib/legion/extensions/llm/canonical/tool_definition.rb

@@ -5,16 +5,33 @@ module Legion
     module Llm
       module Canonical
         TOOL_NAME_MAX_LENGTH = 64
+        OBJECT_SCHEMA_KEYWORDS    = %i[properties required additionalProperties].freeze
+        COMPOSITE_SCHEMA_KEYWORDS = %i[oneOf anyOf allOf enum $ref $defs definitions].freeze
 
         # Canonical tool definition.
         # Ports field vocabulary from Legion::LLM::Types::ToolDefinition.
         ToolDefinition = ::Data.define(:name, :description, :parameters, :source) do
+          def self.normalize_parameters(parameters)
+            empty = { type: 'object', properties: {} }
+            return empty if parameters.nil?
+
+            schema = if parameters.respond_to?(:transform_keys)
+                       parameters.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+                     end
+            return empty if schema.nil? || schema.empty?
+            return schema if schema.key?(:type)
+            return schema.merge(type: 'object') if OBJECT_SCHEMA_KEYWORDS.any? { |k| schema.key?(k) }
+            return schema if COMPOSITE_SCHEMA_KEYWORDS.any? { |k| schema.key?(k) }
+
+            { type: 'object', properties: schema }
+          end
+
           # Build from keyword args (primary constructor).
           def self.build(name:, description: '', parameters: nil, source: nil)
             new(
               sanitize_tool_name(name),
               description.to_s,
-              parameters || {},
+              normalize_parameters(parameters),
               source || { type: :builtin }
             )
           end
@@ -58,6 +75,14 @@ module Legion
             name.empty? ? 'tool' : name
           end
 
+          def params_schema
+            parameters
+          end
+
+          def input_schema
+            parameters
+          end
+
           # Serialize to a Hash for AMQP/fleet/wire transport.
           def to_h
             {

data/lib/legion/extensions/llm/canonical/tool_schema.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Canonical
+        # Extracts and normalizes tool schemas from heterogeneous sources.
+        module ToolSchema
+          EMPTY_OBJECT = { type: 'object', properties: {} }.freeze
+
+          module_function
+
+          def extract(tool)
+            raw = raw_schema(tool)
+            ToolDefinition.normalize_parameters(raw)
+          end
+
+          def raw_schema(tool)
+            return nil if tool.nil?
+            return tool.params_schema if tool.respond_to?(:params_schema) && tool.params_schema
+            return tool.parameters if tool.respond_to?(:parameters) && tool.parameters
+
+            return unless tool.respond_to?(:[])
+
+            tool[:parameters] || tool['parameters'] || tool[:input_schema] || tool['input_schema'] ||
+              tool[:params_schema] || tool['params_schema']
+          end
+
+          def tool_name(tool)
+            return tool.name if tool.respond_to?(:name) && !tool.is_a?(Hash)
+            return tool[:name] || tool['name'] if tool.respond_to?(:[])
+
+            'unknown'
+          end
+
+          def tool_description(tool)
+            return tool.description if tool.respond_to?(:description) && !tool.is_a?(Hash)
+            return (tool[:description] || tool['description'] || '').to_s if tool.respond_to?(:[])
+
+            ''
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/canonical/usage.rb

@@ -30,6 +30,12 @@ module Legion
             h[:cache_write_tokens] ||= h.delete(:cache_creation) || h.delete(:cache_write)
             h[:thinking_tokens] ||= h.delete(:thinking) || h.delete(:reasoning)
 
+            # Extract nested details (OpenAI prompt_tokens_details / input_tokens_details)
+            h[:cache_read_tokens] ||= dig_nested(h, :prompt_tokens_details, :cached_tokens) ||
+                                      dig_nested(h, :input_tokens_details, :cached_tokens)
+            h[:thinking_tokens] ||= dig_nested(h, :completion_tokens_details, :reasoning_tokens) ||
+                                    dig_nested(h, :output_tokens_details, :reasoning_tokens)
+
             # Extract units (non-token extension point — G20b)
             units = h.delete(:units) || {}
 
@@ -43,6 +49,13 @@ module Legion
             )
           end
 
+          def self.dig_nested(hash, details_key, value_key)
+            details = hash[details_key]
+            return nil unless details.is_a?(Hash)
+
+            details[value_key] || details[value_key.to_s]
+          end
+
           # Serialize to a Hash for AMQP/fleet/wire transport.
           def to_h
             super.compact

data/lib/legion/extensions/llm/canonical.rb

@@ -5,6 +5,7 @@ require_relative 'canonical/usage'
 require_relative 'canonical/params'
 require_relative 'canonical/content_block'
 require_relative 'canonical/tool_definition'
+require_relative 'canonical/tool_schema'
 require_relative 'canonical/tool_call'
 require_relative 'canonical/message'
 require_relative 'canonical/request'

data/lib/legion/extensions/llm/capability_policy.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Resolves capability truth from multiple sources with explicit precedence.
+      # Returns both a flat capability list and per-capability source metadata.
+      module CapabilityPolicy
+        OPTIONAL_CAPABILITIES = %i[
+          streaming tools vision embeddings thinking structured_output image audio_transcription audio_speech
+        ].freeze
+
+        BOOLEAN_ALIASES = {
+          enable_streaming: :streaming,
+          enable_tools: :tools,
+          enable_thinking: :thinking,
+          enable_vision: :vision,
+          enable_embeddings: :embeddings,
+          enable_images: :image,
+          streaming_flag: :streaming,
+          tool_flag: :tools,
+          tools_flag: :tools,
+          thinking_flag: :thinking,
+          vision_flag: :vision,
+          embedding_flag: :embeddings,
+          embeddings_flag: :embeddings,
+          image_flag: :image,
+          images_flag: :image
+        }.freeze
+
+        module_function
+
+        def resolve(real:, provider_catalog:, probe:, provider_envelope:, provider_config:, instance_config:, model_config:) # rubocop:disable Metrics/ParameterLists
+          sources = {}
+          OPTIONAL_CAPABILITIES.each do |capability|
+            sources[capability] = resolve_one(
+              capability,
+              real:, provider_catalog:, probe:, provider_envelope:,
+              provider_config:, instance_config:, model_config:
+            )
+          end
+
+          {
+            capabilities: sources.filter_map { |capability, data| capability if data[:value] == true },
+            sources: sources
+          }
+        end
+
+        def resolve_one(capability, real:, provider_catalog:, probe:, provider_envelope:, provider_config:, instance_config:, model_config:) # rubocop:disable Metrics/ParameterLists
+          model_overrides = normalized_overrides(model_config)
+          return { value: model_overrides[capability], source: :model_override } if model_overrides.key?(capability)
+
+          instance_overrides = normalized_overrides(instance_config)
+          return { value: instance_overrides[capability], source: :instance_override } if instance_overrides.key?(capability)
+
+          provider_overrides = normalized_overrides(provider_config)
+          return { value: provider_overrides[capability], source: :provider_override } if provider_overrides.key?(capability)
+
+          real_caps = normalized_booleans(real)
+          return { value: real_caps[capability], source: :model_metadata } if real_caps.key?(capability)
+
+          catalog_caps = normalized_booleans(provider_catalog)
+          return { value: catalog_caps[capability], source: :provider_catalog } if catalog_caps.key?(capability)
+
+          probe_caps = normalized_booleans(probe)
+          return { value: probe_caps[capability], source: :probe } if probe_caps.key?(capability)
+
+          provider_caps = normalized_booleans(provider_envelope)
+          return { value: provider_caps[capability], source: :provider_envelope } if provider_caps.key?(capability)
+
+          { value: false, source: :default_false }
+        end
+
+        def normalized_overrides(config)
+          config = normalize_hash(config)
+          caps_key = config.key?(:capabilities) ? :capabilities : 'capabilities'
+          overrides = normalized_booleans(config[caps_key])
+          BOOLEAN_ALIASES.each do |key, capability|
+            value = config[key]
+            value = config[key.to_s] if value.nil?
+            next unless [true, false].include?(value)
+            next if overrides.key?(capability)
+
+            overrides[capability] = value
+          end
+          overrides
+        end
+
+        def normalized_booleans(value)
+          normalize_hash(value).each_with_object({}) do |(key, raw), result|
+            capability = key.to_s.downcase.tr('-', '_').to_sym
+            next unless OPTIONAL_CAPABILITIES.include?(capability)
+            next unless [true, false].include?(raw)
+
+            result[capability] = raw
+          end
+        end
+
+        def normalize_hash(value)
+          return {} unless value.respond_to?(:to_h)
+
+          value.to_h.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/configuration.rb

@@ -22,6 +22,10 @@ module Legion
             option_keys.dup
           end
 
+          def register_provider_options(keys)
+            Array(keys).each { |key| option(key.to_sym) }
+          end
+
           private
 
           def option_keys = @option_keys ||= []

data/lib/legion/extensions/llm/error.rb

@@ -54,6 +54,8 @@ module Legion
 
       # Faraday middleware that maps provider-specific API errors to Legion::Extensions::Llm errors.
       class ErrorMiddleware < Faraday::Middleware
+        extend Legion::Logging::Helper
+
         STREAM_ERROR_BODY_KEY = :legion_llm_stream_error_body
 
         def initialize(app, options = {})

data/lib/legion/extensions/llm/provider/open_ai_compatible.rb

@@ -76,7 +76,12 @@ module Legion
           def format_openai_tool_calls(tool_calls)
             return nil unless tool_calls&.any?
 
-            tool_calls.values.map do |tool_call|
+            # Array is the canonical shape (per canonical/message.rb); Hash
+            # is the legacy lex-llm shape (id => ToolCall). Both flow through
+            # this renderer depending on caller.
+            calls = tool_calls.is_a?(Hash) ? tool_calls.values : Array(tool_calls)
+
+            calls.map do |tool_call|
               {
                 id: tool_call.id,
                 type: 'function',
@@ -92,16 +97,12 @@ module Legion
             return nil if tools.empty?
 
             tools.values.map do |tool|
-              # Tools can be ToolDefinition objects or plain Hashes from native_dispatch.
-              tool_name = tool.respond_to?(:name) ? tool.name : (tool[:name] || tool['name'])
-              tool_desc = tool.respond_to?(:description) ? tool.description : (tool[:description] || tool['description'] || '')
-              tool_params = tool.respond_to?(:params_schema) ? tool.params_schema : (tool[:parameters] || tool['parameters'] || {})
               {
                 type: 'function',
                 function: {
-                  name: tool_name,
-                  description: tool_desc,
-                  parameters: tool_params || { type: 'object', properties: {} }
+                  name: Canonical::ToolSchema.tool_name(tool),
+                  description: Canonical::ToolSchema.tool_description(tool),
+                  parameters: Canonical::ToolSchema.extract(tool)
                 }
               }
             end

data/lib/legion/extensions/llm/provider.rb

@@ -30,6 +30,8 @@ module Legion
         include Legion::Logging::Helper
         include Legion::Cache::Helper
 
+        MODEL_DETAIL_CACHE_SCHEMA_VERSION = 2
+
         attr_reader :config, :connection
 
         def initialize(config)
@@ -137,7 +139,7 @@ module Legion
           parse_list_models_response response, slug, capabilities
         end
 
-        def discover_offerings(live: false, **filters)
+        def discover_offerings(live: false, raise_on_unreachable: false, **filters)
           return filter_cached_offerings(Array(@cached_offerings), filters) unless live
 
           provider_health = health(live:)
@@ -148,8 +150,10 @@ module Legion
             offering_from_model(model, health: provider_health)
           end
           @cached_offerings
-        rescue Faraday::ConnectionFailed => e
+        rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
           log.warn("[#{slug}] instance=#{provider_instance_id} unreachable: #{e.message}")
+          raise if raise_on_unreachable
+
           []
         end
 
@@ -224,9 +228,16 @@ module Legion
         end
 
         def cache_enabled?
-          return false unless config.respond_to?(:llm_cache_enabled)
+          explicit = config.llm_cache_enabled if config.respond_to?(:llm_cache_enabled)
+
+          unless explicit.nil?
+            log.debug { "[#{slug}] cache_enabled? source=per_provider value=#{explicit}" }
+            return explicit == true
+          end
 
-          config.llm_cache_enabled == true
+          global = global_prompt_caching_enabled?
+          log.debug { "[#{slug}] cache_enabled? source=global value=#{global}" }
+          global
         end
 
         def cache_control_prefix_tokens
@@ -528,11 +539,23 @@ module Legion
 
         private
 
+        def global_prompt_caching_enabled?
+          return false unless defined?(Legion::Settings)
+
+          Legion::Settings.dig(:llm, :prompt_caching, :enabled) == true
+        rescue StandardError
+          false
+        end
+
         def model_detail_cache_key(model_name)
           tier = offering_tier
           instance_key = cache_instance_key
           cred_fp = credential_cache_fragment
-          key_parts = ['model_info', tier, slug, instance_key, cred_fp, model_name].compact
+          key_parts = [
+            'model_info',
+            "schema#{MODEL_DETAIL_CACHE_SCHEMA_VERSION}",
+            tier, slug, instance_key, cred_fp, model_name
+          ].compact
           key_parts.join('.')
         end
 
@@ -555,6 +578,10 @@ module Legion
         end
 
         def offering_from_model(model, health: {})
+          capability_sources = Array(model.capabilities).to_h do |cap|
+            [cap.to_sym, { value: true, source: :model_metadata }]
+          end
+
           Routing::ModelOffering.new(
             provider_family: slug.to_sym,
             provider_instance: model.instance || provider_instance_id,
@@ -565,6 +592,7 @@ module Legion
             model_family: model.family,
             usage_type: offering_usage_type(model),
             capabilities: model.capabilities,
+            capability_sources: capability_sources,
             limits: offering_limits(model),
             health:,
             metadata: offering_metadata(model)

data/lib/legion/extensions/llm/provider_contract.rb

@@ -11,10 +11,19 @@ module Legion
           embed: [%i[keyreq text], %i[keyreq model]],
           image: [%i[keyreq prompt], %i[keyreq model]],
           list_models: [%i[key live], %i[keyrest filters]],
-          discover_offerings: [%i[key live], %i[keyrest filters]],
+          discover_offerings: [%i[key live], %i[key raise_on_unreachable], %i[keyrest filters]],
           health: [%i[key live]],
           count_tokens: [%i[keyreq messages], %i[keyreq model], %i[key params]]
         }.freeze
+
+        # Tools passed to chat/stream_chat must support Canonical::ToolDefinition objects.
+        # Providers must not crash on Data.define instances (not Hashes).
+        TOOL_SUPPORT_CONTRACT = <<~DOC
+          - chat and stream_chat accept keyword `tools:` (Hash<name, tool_object>)
+          - tools may be Canonical::ToolDefinition, Hash, or legacy Lex::Llm::Tool
+          - Renderers must use Canonical::ToolSchema.extract(tool) for schema access
+          - discover_offerings(live: true, raise_on_unreachable: true) raises on transport failure
+        DOC
       end
     end
   end

data/lib/legion/extensions/llm/routing/model_offering.rb

@@ -16,8 +16,8 @@ module Legion
           }.freeze
 
           attr_reader :offering_id, :provider_family, :model_family, :provider_instance, :instance_id, :transport,
-                      :tier, :model, :canonical_model_alias, :routing_metadata, :usage_type, :capabilities, :limits,
-                      :credentials, :health, :cost, :policy_tags, :metadata
+                      :tier, :model, :canonical_model_alias, :routing_metadata, :usage_type, :capabilities,
+                      :capability_sources, :limits, :credentials, :health, :cost, :policy_tags, :metadata
 
           def initialize(data)
             @metadata = normalize_hash(fetch_value(data, :metadata))
@@ -37,6 +37,7 @@ module Legion
                                                            fetch_value(data, :kind) ||
                                                            infer_usage_type(data)))
             @capabilities = normalize_capabilities(fetch_value(data, :capabilities))
+            @capability_sources = normalize_capability_sources(fetch_value(data, :capability_sources))
             @limits = normalize_hash(fetch_value(data, :limits))
             @credentials = fetch_value(data, :credentials)
             @health = normalize_hash(fetch_value(data, :health))
@@ -106,6 +107,7 @@ module Legion
               routing_metadata: routing_metadata,
               usage_type: usage_type,
               capabilities: capabilities,
+              capability_sources: capability_sources,
               limits: limits,
               credentials: credentials,
               health: health,
@@ -167,6 +169,16 @@ module Legion
             end.uniq
           end
 
+          def normalize_capability_sources(value)
+            normalize_hash(value).to_h do |capability, source_data|
+              normalized_source = normalize_hash(source_data)
+              [
+                capability.to_s.downcase.tr('-', '_').to_sym,
+                { value: normalized_source[:value], source: normalized_source[:source]&.to_sym }.compact
+              ]
+            end
+          end
+
           def normalize_hash(value)
             (value || {}).to_h.transform_keys(&:to_sym)
           end

data/lib/legion/extensions/llm/stream_accumulator.rb

@@ -57,6 +57,27 @@ module Legion
           )
         end
 
+        # Flush any text still held in the untagged-preamble buffer as a final
+        # streamed chunk. Without this, short responses that match the
+        # untagged-reasoning heuristic (e.g. starting with "I", "The", "Let me")
+        # and never hit a double newline are buffered for the entire stream and
+        # the caller's block never receives a single delta.
+        def flush_pending_chunk
+          return nil if @untagged_preamble_buffer.empty?
+
+          @last_content_delta = +''
+          @last_thinking_delta = +''
+          flush_pending_untagged_preamble_into_deltas
+          return nil if @last_content_delta.empty? && @last_thinking_delta.empty?
+
+          Chunk.new(
+            role: :assistant,
+            content: @last_content_delta.empty? ? nil : @last_content_delta,
+            thinking: @last_thinking_delta.empty? ? nil : Thinking.build(text: @last_thinking_delta),
+            model_id: model_id
+          )
+        end
+
         def to_message(response)
           flush_pending_untagged_preamble
 
@@ -233,6 +254,24 @@ module Legion
           @untagged_preamble_pending = false
         end
 
+        # Same as flush_pending_untagged_preamble, but also records the flushed
+        # text in the per-chunk delta accumulators so flush_pending_chunk can
+        # surface it to the streaming block.
+        def flush_pending_untagged_preamble_into_deltas
+          content, thinking = Responses::ThinkingExtractor.extract_untagged_preamble(@untagged_preamble_buffer)
+          if thinking
+            @content << content
+            @last_content_delta << content
+            @thinking_text << thinking
+            @last_thinking_delta << thinking
+          else
+            @content << @untagged_preamble_buffer
+            @last_content_delta << @untagged_preamble_buffer
+          end
+          @untagged_preamble_buffer = +''
+          @untagged_preamble_pending = false
+        end
+
         def append_thinking_from_chunk(chunk)
           thinking = chunk.thinking
           return unless thinking

data/lib/legion/extensions/llm/streaming.rb

@@ -24,6 +24,11 @@ module Legion
             end
           end
 
+          # Release any text held by the untagged-preamble heuristic so short
+          # responses still stream at least one delta to the caller.
+          final_chunk = accumulator.flush_pending_chunk
+          block&.call(final_chunk) if final_chunk
+
           message = accumulator.to_message(response)
           log.debug { "Stream completed: #{message.content}" }
           message
@@ -31,6 +36,8 @@ module Legion
 
         def build_stream_callback(accumulator, block)
           proc do |chunk|
+            next unless chunk
+
             accumulator.add chunk
             filtered = accumulator.filtered_chunk(chunk)
             block.call(filtered) if filtered
@@ -39,7 +46,10 @@ module Legion
 
         def handle_stream(&block)
           build_on_data_handler do |data|
-            block.call(build_chunk(data)) if data.is_a?(Hash)
+            next unless data.is_a?(Hash)
+
+            chunk = build_chunk(data)
+            block.call(chunk) if chunk
           end
         end
 
@@ -132,7 +142,30 @@ module Legion
                     end
           log.warn "[llm][streaming] action=handle_failed_response status=#{status} " \
                    "partial_body=#{buffer.length}b msg=#{partial.inspect}"
-          raise Legion::Extensions::Llm::ServerError, msg
+          raise_streaming_status_error(status, msg)
+        end
+
+        def raise_streaming_status_error(status, message)
+          response = Struct.new(:body, :status).new({ 'error' => { 'message' => message } }, status)
+          case status
+          when 400
+            raise Legion::Extensions::Llm::BadRequestError.new(response, message)
+          when 401
+            raise Legion::Extensions::Llm::UnauthorizedError.new(response, message)
+          when 403
+            raise Legion::Extensions::Llm::ForbiddenError.new(response, message)
+          when 429
+            raise Legion::Extensions::Llm::RateLimitError.new(response, message)
+          when 500
+            raise Legion::Extensions::Llm::ServerError.new(response, message)
+          when 502..504
+            raise Legion::Extensions::Llm::ServiceUnavailableError.new(response, message)
+          when 529
+            raise Legion::Extensions::Llm::OverloadedError.new(response, message)
+          else
+            provider = respond_to?(:parse_error) ? self : nil
+            Legion::Extensions::Llm::ErrorMiddleware.parse_error(provider: provider, response: response)
+          end
         end
 
         def handle_sse(chunk, parser, env, &)
@@ -183,7 +216,7 @@ module Legion
         def build_stream_error_response(parsed_data, env, status)
           error_status = status || env&.status || 500
 
-          if faraday_1?
+          if faraday_1? || env.nil?
             Struct.new(:body, :status).new(parsed_data, error_status)
           else
             env.merge(body: parsed_data, status: error_status)

data/lib/legion/extensions/llm/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.5.0'
+      VERSION = '0.5.3'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -36,6 +36,9 @@ module Legion
       #  unqualified constant lookups resolve via Ruby scope.               #
       # ------------------------------------------------------------------ #
 
+      # --- Capability resolution policy (no internal deps) ---
+      require_relative 'llm/capability_policy'
+
       # --- Base value objects (no internal deps) ---
       require_relative 'llm/mime_type'
       require_relative 'llm/model/info'