lex-llm 0.7.3 → 0.8.0

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

@@ -4,33 +4,43 @@ module Legion
   module Extensions
     module Llm
       # Handles streaming responses from AI providers.
+      # The provider's build_chunk yields Canonical::Chunk objects; the caller's
+      # block receives Canonical::Chunk objects and the sequence ends in exactly
+      # one done chunk (or an error chunk followed by the raise, 05 O5).
+      # FaradayHandlers / SSE parsing / error paths are unchanged plumbing; the
+      # status→error mapping delegates to the ONE mapper (ErrorMiddleware, 10 U8).
       module Streaming
         include Legion::Logging::Helper
         extend Legion::Logging::Helper
 
         module_function
 
-        def stream_response(connection, payload, additional_headers = {}, &block)
+        def stream_response(connection, payload, additional_headers = {}, model: nil, &block)
           accumulator = StreamAccumulator.new
 
-          response = connection.post stream_url, payload do |req|
-            req.headers = additional_headers.merge(req.headers) unless additional_headers.empty?
-            on_chunk = build_stream_callback(accumulator, block)
-            log.debug { "Stream callback prepared: #{on_chunk.inspect}" } if Legion::Extensions::Llm.config.log_stream_debug
-            if faraday_1?
-              req.options[:on_data] = handle_stream(&on_chunk)
-            else
-              req.options.on_data = handle_stream(&on_chunk)
+          begin
+            connection.post stream_url, payload do |req|
+              req.headers = additional_headers.merge(req.headers) unless additional_headers.empty?
+              on_chunk = build_stream_callback(accumulator, block)
+              log.debug { "Stream callback prepared: #{on_chunk.inspect}" } if Legion::Extensions::Llm.config.log_stream_debug
+              if faraday_1?
+                req.options[:on_data] = handle_stream(&on_chunk)
+              else
+                req.options.on_data = handle_stream(&on_chunk)
+              end
             end
+          rescue StandardError => e
+            block&.call(Canonical::Chunk.error_chunk(error: e, request_id: nil))
+            raise
           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
+          accumulator.flush_pending_chunk.each { |chunk| block&.call(chunk) }
 
-          message = accumulator.to_message(response)
-          log.debug { "Stream completed: #{message.content}" }
+          message = accumulator.to_response(model:)
+          log.debug { "Stream completed: #{message.text}" }
+          block&.call(Canonical::Chunk.done(request_id: nil, usage: message.usage, stop_reason: message.stop_reason))
           message
         end
 
@@ -38,9 +48,7 @@ module Legion
           proc do |chunk|
             next unless chunk
 
-            accumulator.add chunk
-            filtered = accumulator.filtered_chunk(chunk)
-            block.call(filtered) if filtered
+            accumulator.add(chunk).each { |emitted| block&.call(emitted) }
           end
         end
 
@@ -151,27 +159,13 @@ module Legion
           raise_streaming_status_error(status, msg)
         end
 
+        # 10 U8: the streaming path delegates to the ONE status→error mapper
+        # (ErrorMiddleware.parse_error) — the inlined case table is deleted.
+        # The provider's parse_error extracts the message from the synthesized
+        # body.
         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
+          ErrorMiddleware.parse_error(provider: respond_to?(:parse_error) ? self : nil, response:)
         end
 
         def handle_sse(chunk, parser, env, &)
@@ -186,12 +180,19 @@ module Legion
         end
 
         def handle_data(data, env)
+          # An empty data frame carries nothing — it is not a parse failure.
+          return if data.to_s.strip.empty?
+
           parsed = Legion::JSON.parse(data, symbolize_names: false)
           return parsed unless parsed.is_a?(Hash) && parsed.key?('error')
 
           handle_parsed_error(parsed, env)
         rescue Legion::JSON::ParseError => e
+          # M1: an unparseable mid-stream data frame is still a provider
+          # error — a classified failure through the one mapper, never a
+          # silent drop (the stream must not complete "successfully").
           handle_exception(e, level: :warn, handled: true, operation: 'llm.streaming.handle_data')
+          raise_unparseable_streaming_error(env, data, 'data frame')
         end
 
         def handle_error_event(data, env)
@@ -216,7 +217,21 @@ module Legion
           parsed_data = Legion::JSON.parse(data, symbolize_names: false)
           handle_parsed_error(parsed_data, env)
         rescue Legion::JSON::ParseError => e
+          # M1: an error event that cannot be parsed is STILL an error event
+          # — a classified failure, never a silent nil (the pre-M1 fail-open
+          # completed the stream "successfully" on the provider's explicit
+          # error signal).
           handle_exception(e, level: :warn, handled: true, operation: 'llm.streaming.parse_error_from_json')
+          raise_unparseable_streaming_error(env, data, 'error event')
+        end
+
+        # One classified failure for unparseable stream error content — the
+        # same 500 classification the PARSEABLE in-band error path uses
+        # (parse_streaming_error): an in-band provider error event is a
+        # failure regardless of the stream's HTTP status. The raw payload is
+        # bounded (200 chars) — never the full body.
+        def raise_unparseable_streaming_error(_env, data, kind)
+          raise_streaming_status_error(500, "Provider error: unparseable #{kind} (#{data.to_s[0, 200].inspect})")
         end
 
         def build_stream_error_response(parsed_data, env, status)

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

@@ -11,8 +11,24 @@ module Legion
       module Taxonomies
         TIERS           = %i[direct local fleet cloud frontier].freeze
         TYPES           = %i[inference embedding image audio].freeze
-        CIRCUIT_STATES  = %i[closed half_open open].freeze
-        HEALTH_KEYS     = %i[circuit_state denied available adjustment].freeze
+
+        # The authoritative operation → Inventory lane-type mapping (the 4th
+        # field of the 5-tuple lane id). Single home for the mapping: the
+        # identity composer consumes `lane_type_for` below; no layer retains a
+        # second table. moderate/count_tokens are non-generative inference
+        # operations — no moderation/count type exists in TYPES, so they map to
+        # :inference.
+        OPERATION_TO_LANE_TYPE = {
+          chat: :inference,
+          stream_chat: :inference,
+          embed: :embedding,
+          image: :image,
+          transcribe: :audio,
+          translate: :audio,
+          speak: :audio,
+          moderate: :inference,
+          count_tokens: :inference
+        }.freeze
 
         # --- SSOT v3 runtime-contract enums (phase-1-lex-llm-additive.md section 6) ---
         OPERATIONS = %i[
@@ -68,22 +84,19 @@ module Legion
           failed_probe inconclusive_probe
         ].freeze
 
-        # Only these aliases are accepted, and only when allow_aliases: true.
-        OPERATION_ALIASES = {
-          stream: :stream_chat,
-          embedding: :embed,
-          moderation: :moderate,
-          audio_translation: :translate,
-          speech: :speak
-        }.freeze
-
         module_function
 
-        # Normalize an operation to one of OPERATIONS. Ingress and protocol-v2
-        # compatibility adapters pass allow_aliases: true; registry records and
-        # exact-execution envelopes pass false. Unknown, empty, or invalid UTF-8
-        # input always raises Inventory::Errors::ValidationError.
-        def normalize_operation(value:, allow_aliases: false)
+        # The one operation → lane-type resolution: canonicalizes the operation,
+        # then reads the single OPERATION_TO_LANE_TYPE table. Unknown operations
+        # raise via normalize_operation.
+        def lane_type_for(operation:)
+          OPERATION_TO_LANE_TYPE.fetch(normalize_operation(value: operation))
+        end
+
+        # The one operation spelling (06 P5): canonical operations only, no
+        # aliases. Unknown, empty, or invalid UTF-8 input always raises
+        # Inventory::Errors::ValidationError.
+        def normalize_operation(value:)
           raise Inventory::Errors::ValidationError, 'operation must be a String or Symbol' unless value.is_a?(::String) || value.is_a?(::Symbol)
 
           string = value.to_s
@@ -94,7 +107,6 @@ module Legion
 
           candidate = trimmed.to_sym
           return candidate if OPERATIONS.include?(candidate)
-          return OPERATION_ALIASES[candidate] if allow_aliases && OPERATION_ALIASES.key?(candidate)
 
           raise Inventory::Errors::ValidationError, "operation is not a canonical operation (#{candidate})"
         end

data/lib/legion/extensions/llm/transport/fleet_lane.rb

@@ -4,20 +4,18 @@ module Legion
   module Extensions
     module Llm
       module Transport
-        # Shared RabbitMQ live-work lane defaults for provider fleet workers.
+        # Shared RabbitMQ live-work lane construction for provider fleet
+        # workers. The queue defaults live in ONE home — Llm.default_settings
+        # (10 U10: no inline literal defaults).
         module FleetLane
-          DEFAULTS = {
-            queue_expires_ms: 60_000,
-            message_ttl_ms: 120_000,
-            queue_max_length: 100,
-            delivery_limit: 3,
-            consumer_ack_timeout_ms: 300_000
-          }.freeze
-
           module_function
 
+          def queue_defaults
+            Legion::Extensions::Llm.default_settings.dig(:fleet, :consumer) || {}
+          end
+
           def queue_options(settings = {})
-            config = DEFAULTS.merge((settings || {}).compact.transform_keys(&:to_sym))
+            config = queue_defaults.merge((settings || {}).compact.transform_keys(&:to_sym))
             {
               durable: true,
               auto_delete: false,

data/lib/legion/extensions/llm/transport/messages/fleet_error.rb

@@ -11,7 +11,8 @@ module Legion
     module Llm
       module Transport
         module Messages
-          # Correlated protocol-v2 error envelope for fleet reply queues.
+          # Correlated protocol-v3 error envelope for fleet reply queues (E6).
+          # E5: no aliases — provider_instance only.
           class FleetError < ::Legion::Transport::Message
             include Fleet::DefaultExchangeReply
             include Fleet::EnvelopeValidation
@@ -45,7 +46,7 @@ module Legion
                 idempotency_key: @options[:idempotency_key],
                 operation: @options[:operation],
                 provider: @options[:provider],
-                provider_instance: @options[:provider_instance] || @options[:instance],
+                provider_instance: @options[:provider_instance],
                 model: @options[:model],
                 reply_to: reply_to,
                 message_context: @options[:message_context],

data/lib/legion/extensions/llm/transport/messages/fleet_request.rb

@@ -11,7 +11,8 @@ module Legion
     module Llm
       module Transport
         module Messages
-          # Strict protocol-v2 request envelope for outbound fleet work.
+          # Strict protocol-v3 request envelope for outbound fleet work.
+          # E2: required fields come from the one Fleet::Protocol::REQUIRED_FIELDS list.
           class FleetRequest < ::Legion::Transport::Message
             include Fleet::EnvelopeValidation
             include Fleet::PublishSafety
@@ -23,11 +24,6 @@ module Legion
               spool: false,
               return_result: true
             }.freeze
-            REQUIRED_OPTIONS = %i[
-              request_id correlation_id operation provider provider_instance model params reply_to
-              message_context caller trace_context signed_token timeout_seconds expires_at protocol_version
-              idempotency_key
-            ].freeze
 
             def exchange = Exchanges::Fleet
             def type = Fleet::Protocol::REQUEST_TYPE
@@ -78,7 +74,7 @@ module Legion
             def validate
               reject_legacy_options!
               require_option!(:routing_key)
-              REQUIRED_OPTIONS.each { |key| require_option!(key) }
+              Fleet::Protocol::REQUIRED_FIELDS.each { |key| require_option!(key) }
               require_protocol_version!
               @valid = true
             end
@@ -100,7 +96,9 @@ module Legion
                 trace_context: @options[:trace_context],
                 signed_token: @options[:signed_token],
                 timeout_seconds: @options[:timeout_seconds],
-                expires_at: @options[:expires_at]
+                expires_at: @options[:expires_at],
+                execution_contract: @options[:execution_contract],
+                offering_id: @options[:offering_id]
               ).compact
             end
 

data/lib/legion/extensions/llm/transport/messages/fleet_response.rb

@@ -11,7 +11,11 @@ module Legion
     module Llm
       module Transport
         module Messages
-          # Correlated protocol-v2 response envelope for fleet reply queues.
+          # Correlated protocol-v3 response envelope for fleet reply queues.
+          # E3: carries the serialized Canonical::Response under :response.
+          # E4: thinking exclusion happens exactly once at the responder
+          # (ProviderResponder#publish_response); this envelope is a pass-through.
+          # E5: no aliases — provider_instance only.
           class FleetResponse < ::Legion::Transport::Message
             include Fleet::DefaultExchangeReply
             include Fleet::EnvelopeValidation
@@ -32,28 +36,25 @@ module Legion
               require_option!(:request_id)
               require_option!(:correlation_id)
               require_option!(:reply_to)
+              require_option!(:response)
               require_protocol_version!
               @valid = true
             end
 
             def message
-              super.except(:thinking).merge(
-                protocol_version: @options[:protocol_version] || Fleet::Protocol::VERSION,
+              super.merge(
+                protocol_version: @options[:protocol_version],
                 request_id: @options[:request_id],
                 correlation_id: correlation_id,
                 idempotency_key: @options[:idempotency_key],
                 operation: @options[:operation],
                 provider: @options[:provider],
-                provider_instance: @options[:provider_instance] || @options[:instance],
+                provider_instance: @options[:provider_instance],
                 model: @options[:model],
                 reply_to: reply_to,
                 message_context: @options[:message_context],
                 trace_context: @options[:trace_context],
-                content: @options[:content],
-                tool_calls: @options[:tool_calls],
-                usage: @options[:usage] || {},
-                finish_reason: @options[:finish_reason],
-                metadata: @options[:metadata] || {},
+                response: @options[:response],
                 execution_contract: @options[:execution_contract],
                 offering_id: @options[:offering_id]
               ).compact

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

@@ -7,10 +7,6 @@ module Legion
       module Utils
         module_function
 
-        def hash_get(hash, key)
-          hash[key.to_sym] || hash[key.to_s]
-        end
-
         def to_safe_array(item)
           case item
           when Array
@@ -34,8 +30,10 @@ module Legion
           value.is_a?(Date) ? value : Date.parse(value.to_s)
         end
 
+        # Recursive merge with the safer dup-before-merge policy (10 U7):
+        # neither input is mutated.
         def deep_merge(original, overrides)
-          original.merge(overrides) do |_key, original_value, overrides_value|
+          deep_dup(original || {}).merge(deep_dup(overrides || {})) do |_key, original_value, overrides_value|
             if original_value.is_a?(Hash) && overrides_value.is_a?(Hash)
               deep_merge(original_value, overrides_value)
             else
@@ -44,6 +42,26 @@ module Legion
           end
         end
 
+        # The one host-locality detector (10 §1E): localhost/loopback by host,
+        # accepting full URLs and bare host[:port] values.
+        def localhost_url?(url)
+          require 'uri'
+          text = url.to_s.strip
+          return false if text.empty?
+
+          host =
+            begin
+              parsed = text.match?(%r{\A[a-z][a-z0-9+.-]*://}) ? URI.parse(text) : URI.parse("http://#{text}")
+              parsed.host
+            rescue URI::InvalidURIError
+              text.split(%r{[:/\s]}, 2).first
+            end
+          return false if host.nil? || host.empty?
+
+          normalized = host.delete_prefix('[').delete_suffix(']').downcase
+          %w[localhost 127.0.0.1 ::1].include?(normalized)
+        end
+
         def deep_dup(value)
           case value
           when Hash

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.7.3'
+      VERSION = '0.8.0'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -36,11 +36,9 @@ module Legion
       #  unqualified constant lookups resolve via Ruby scope.               #
       # ------------------------------------------------------------------ #
 
-      # --- P1 SSOT: taxonomy enums, capability normalization, inventory writer mixin ---
+      # --- P1 SSOT: taxonomy enums, capability normalization ---
       require_relative 'llm/taxonomies'
       require_relative 'llm/capabilities'
-      require_relative 'llm/inventory/scoped_refresher'
-      require_relative 'llm/inventory/capabilities'
 
       # --- Capability resolution policy (no internal deps) ---
       require_relative 'llm/capability_policy'
@@ -52,6 +50,8 @@ module Legion
       require_relative 'llm/inventory/errors'
       require_relative 'llm/inventory/immutable_value'
       require_relative 'llm/inventory/identity'
+      require_relative 'llm/inventory/weight_schema'
+      require_relative 'llm/inventory/weight_reconciler'
       require_relative 'llm/inventory/evidence'
       require_relative 'llm/inventory/callable_handle'
       require_relative 'llm/inventory/probe_token'
@@ -64,40 +64,19 @@ module Legion
       require_relative 'llm/routing/provider_outcome'
 
       # --- Base value objects (no internal deps) ---
-      require_relative 'llm/mime_type'
-      require_relative 'llm/model/info'
-      require_relative 'llm/model/modalities'
-      require_relative 'llm/model/pricing_category'
-      require_relative 'llm/model/pricing_tier'
-      require_relative 'llm/model/pricing'
       require_relative 'llm/configuration'
-      require_relative 'llm/thinking'
-      require_relative 'llm/tokens'
-      require_relative 'llm/message'
-      require_relative 'llm/tool_call'
-      require_relative 'llm/content'
       require_relative 'llm/errors/unsupported_capability'
       require_relative 'llm/error'
 
-      # --- Build on message/base types ---
-      require_relative 'llm/chunk'
-      require_relative 'llm/model'
-      require_relative 'llm/attachment'
-
       # --- Streaming fundamentals (must load before streaming/provider) ---
+      require_relative 'llm/responses/thinking_extractor'
+      require_relative 'llm/responses/tool_arguments'
       require_relative 'llm/stream_accumulator'
-      require_relative 'llm/responses/stream_chunk'
       require_relative 'llm/streaming'
 
-      # --- Context, Connection ---
-      require_relative 'llm/context'
+      # --- Connection ---
       require_relative 'llm/connection'
 
-      # --- Response normalizers ---
-      require_relative 'llm/responses/chat_response'
-      require_relative 'llm/responses/embedding_response'
-      require_relative 'llm/responses/thinking_extractor'
-
       # --- Provider base & allied modules ---
       require_relative 'llm/provider_contract'
       require_relative 'llm/stop_reason_mapping'
@@ -109,37 +88,19 @@ module Legion
 
       # --- Routing ---
       require_relative 'llm/routing'
-      require_relative 'llm/routing/lane_key'
-      require_relative 'llm/routing/offering_registry'
-      require_relative 'llm/routing/registry_event'
-      require_relative 'llm/routing/model_offering'
-
-      # --- Models (scans for Provider subclasses) ---
-      require_relative 'llm/models'
-
-      # --- Agent & Chat (reference Provider, Context, Chat at method-time) ---
-      require_relative 'llm/agent'
-      require_relative 'llm/chat'
-
-      # --- Domain services ---
-      require_relative 'llm/embedding'
-      require_relative 'llm/moderation'
-      require_relative 'llm/image'
-      require_relative 'llm/transcription'
 
-      # --- Registry & misc support ---
-      require_relative 'llm/registry_event_builder'
-      require_relative 'llm/registry_publisher'
+      # --- Misc support ---
       require_relative 'llm/auto_registration'
       require_relative 'llm/credential_sources'
       require_relative 'llm/tool'
       require_relative 'llm/utils'
-      require_relative 'llm/aliases'
 
-      # --- Fleet protocol (depends on Provider, Models) ---
+      # --- Fleet protocol (depends on Provider) ---
       require_relative 'llm/fleet/protocol'
       require_relative 'llm/fleet/settings'
       require_relative 'llm/fleet/token_error'
+      require_relative 'llm/fleet/contract_error'
+      require_relative 'llm/fleet/fleet_envelope'
       require_relative 'llm/fleet/envelope_validation'
       require_relative 'llm/fleet/publish_safety'
       require_relative 'llm/fleet/default_exchange_reply'
@@ -173,58 +134,9 @@ module Legion
 
       Schema = ::RubyLLM::Schema unless const_defined?(:Schema, false)
 
-      # Provider-neutral value objects exposed under the Legion extension namespace.
-      module Types
-        ModelOffering = Routing::ModelOffering unless const_defined?(:ModelOffering, false)
-        OfferingRegistry = Routing::OfferingRegistry unless const_defined?(:OfferingRegistry, false)
-        RegistryEvent = Routing::RegistryEvent unless const_defined?(:RegistryEvent, false)
-      end
-
-      # Shared routing helpers exposed under the Legion extension namespace.
-      module Routing
-        LaneKey = ::Legion::Extensions::Llm::Routing::LaneKey unless const_defined?(:LaneKey, false)
-        OfferingRegistry = ::Legion::Extensions::Llm::Routing::OfferingRegistry unless const_defined?(:OfferingRegistry,
-                                                                                                      false)
-        RegistryEvent = ::Legion::Extensions::Llm::Routing::RegistryEvent unless const_defined?(:RegistryEvent, false)
-      end
-
       class << self
         def remote_invocable? = false
 
-        def context
-          context_config = config.dup
-          yield context_config if block_given?
-          Context.new(context_config)
-        end
-
-        def chat(...)
-          Chat.new(...)
-        end
-
-        def embed(...)
-          Embedding.embed(...)
-        end
-
-        def moderate(...)
-          Moderation.moderate(...)
-        end
-
-        def paint(...)
-          Image.paint(...)
-        end
-
-        def transcribe(...)
-          Transcription.transcribe(...)
-        end
-
-        def models
-          Models.instance
-        end
-
-        def providers
-          Models.scan_provider_classes.values
-        end
-
         def configure
           yield config
         end

data/spec/legion/extensions/llm/auto_registration_spec.rb

@@ -19,15 +19,10 @@ RSpec.describe Legion::Extensions::Llm::AutoRegistration do
     mod
   end
 
-  describe '#discover_instances' do
-    it 'returns an empty hash by default' do
-      expect(provider_module.discover_instances).to eq({})
-    end
-  end
-
-  describe '#provider_aliases' do
-    it 'returns an empty alias list by default' do
-      expect(provider_module.provider_aliases).to eq([])
+  describe '0.8.0 rip — legacy defaults deleted' do
+    it 'provides no discover_instances or provider_aliases defaults' do
+      expect(provider_module).not_to respond_to(:discover_instances)
+      expect(provider_module).not_to respond_to(:provider_aliases)
     end
   end