lex-llm 0.7.3 → 0.8.0

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

@@ -6,23 +6,40 @@ module Legion
       # Documents the canonical public provider method signatures shared by provider gems.
       module ProviderContract
         REQUIRED_SIGNATURES = {
-          chat: [%i[keyreq messages], %i[keyreq model]],
-          stream_chat: [%i[keyreq messages], %i[keyreq model]],
+          chat: [%i[req messages], %i[keyreq model]],
+          stream_chat: [%i[req messages], %i[keyreq model]],
           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[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).
+        # H3: the tools half of the dispatch boundary contract. A non-empty
+        # `tools:` value must be Hash<name, Canonical::ToolDefinition>; the
+        # base funnel enforces it once (08 F2) and non-canonical tool values
+        # raise ArgumentError. Renderers consume Canonical::ToolDefinition
+        # only (schema access via Canonical::ToolSchema); Hash and legacy
+        # Lex::Llm::Tool tolerance is deleted from the contract.
         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
+          - chat and stream_chat accept keyword `tools:` (Hash<name, Canonical::ToolDefinition> or nil)
+          - the base funnel enforces the tool contract once (08 F2): a non-Hash or
+            non-ToolDefinition tool value raises ArgumentError before any rendering
           - Renderers must use Canonical::ToolSchema.extract(tool) for schema access
-          - discover_offerings(live: true, raise_on_unreachable: true) raises on transport failure
+        DOC
+
+        # H5: the read-path contract, stated as implemented. The two base
+        # read paths perform different amounts of transport and say so.
+        READ_PATH_CONTRACT = <<~DOC
+          - discover_offerings: the base read path serves the SSOT registry
+            snapshot for this provider instance — NO transport occurs.
+            `live:` and `raise_on_unreachable:` are accepted for signature
+            compatibility and have no effect in the base (there is nothing
+            that can become unreachable). `filters` select from the snapshot.
+          - Provider gems that override either path with a live fetch MUST
+            implement `live:` and (for discover_offerings)
+            `raise_on_unreachable:` for real — the base guarantees are not
+            inherited semantics.
         DOC
       end
     end

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

@@ -11,15 +11,15 @@ module Legion
                   **legacy_settings)
           validate_provider_defaults!(fleet:, gateways:, legacy_settings:)
 
-          deep_merge(
+          Utils.deep_merge(
             Legion::Extensions::Llm.default_settings,
             {
               enabled: enabled,
               provider_family: family,
-              discovery: deep_merge({ enabled: true, interval_seconds: 300 }, discovery || {}),
-              instances: deep_merge(
+              discovery: Utils.deep_merge({ enabled: true, interval_seconds: 300 }, discovery || {}),
+              instances: Utils.deep_merge(
                 {
-                  default: deep_merge(
+                  default: Utils.deep_merge(
                     { enabled: true, credentials: nil, fleet: { enabled: false, consumer_priority: 0, prefetch: 1 } },
                     instance || {}
                   )
@@ -44,31 +44,10 @@ module Legion
           raise ArgumentError, "Unsupported top-level provider settings: #{invalid_keys.join(', ')}"
         end
 
-        def deep_dup(value)
-          case value
-          when Hash
-            value.to_h { |key, inner_value| [key, deep_dup(inner_value)] }
-          when Array
-            value.map { |inner_value| deep_dup(inner_value) }
-          else
-            value
-          end
-        end
-
-        def deep_merge(left, right)
-          deep_dup(left || {}).merge(deep_dup(right || {})) do |_key, left_value, right_value|
-            left_value.is_a?(Hash) && right_value.is_a?(Hash) ? deep_merge(left_value, right_value) : right_value
-          end
-        end
-
         def infer_tier_from_endpoint(url)
           return :direct if url.nil? || url.to_s.empty?
 
-          require 'uri'
-          host = URI.parse(url.to_s).host.to_s.downcase
-          %w[localhost 127.0.0.1 ::1 [::1]].include?(host) ? :local : :direct
-        rescue URI::InvalidURIError
-          :direct
+          Legion::Extensions::Llm::Utils.localhost_url?(url) ? :local : :direct
         end
       end
     end

data/lib/legion/extensions/llm/responses/thinking_extractor.rb

@@ -156,6 +156,9 @@ module Legion
           end
           private_class_method :consume_open_think_segment
 
+          # The shared tag-segment matcher (10 U1): batch extraction and the
+          # streaming state machine both match tags through this one
+          # implementation.
           def next_tag_match(text, type)
             matches = THINK_TAG_PAIRS.filter_map do |open_tag, close_tag|
               tag = type == :open ? open_tag : close_tag
@@ -164,7 +167,11 @@ module Legion
             end
             matches.min_by { |match| match[:index] }
           end
-          private_class_method :next_tag_match
+
+          # All tag tokens (opens + closes) for cross-chunk boundary buffering.
+          def tag_tokens
+            THINK_TAG_PAIRS.flat_map { |open_tag, close_tag| [open_tag, close_tag] }
+          end
 
           def untagged_reasoning_preamble?(preamble)
             return false if preamble.length > UNTAGGED_PREAMBLE_MAX_LENGTH

data/lib/legion/extensions/llm/responses/tool_arguments.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Responses
+        # The ONE shared tool-arguments parser (10 U2). Streaming fragments are
+        # assembled into a complete JSON string before parsing; sync providers pass
+        # the provider wire string. One strict policy: invalid or non-object JSON
+        # raises — corrupted tool arguments never cross the boundary as a
+        # fabricated {} (04 L1/L7; the two old rescue-to-{} policies are deleted).
+        module ToolArguments
+          module_function
+
+          # Parse assembled tool-call arguments JSON into a Hash.
+          # nil / empty string means "no arguments" and returns {} (documented
+          # default, not tolerance).
+          def parse!(raw)
+            return {} if raw.nil?
+            return {} if raw.is_a?(::String) && raw.strip.empty?
+            raise ArgumentError, "tool call arguments expected JSON String, got #{raw.class}" unless raw.is_a?(::String)
+
+            parsed = ::Legion::JSON.parse(raw, symbolize_names: false)
+            raise ArgumentError, "tool call arguments must be a JSON object, got #{parsed.class}" unless parsed.is_a?(::Hash)
+
+            parsed
+          rescue ::Legion::JSON::ParseError => e
+            raise ArgumentError, "tool call arguments are not valid JSON: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -47,7 +47,32 @@ module Legion
             raise Legion::Extensions::Llm::Inventory::Errors::ValidationError,
                   'retry_after must be nil or a finite nonnegative Numeric'
           end
+
+          # The ONE error→kind base table (05 O6 / 08 E1). Providers override
+          # #normalize_dispatch_error only when their wire semantics supply
+          # stronger evidence; the table itself is frozen here and is also the
+          # source of fleet retryability (06 F6).
+          def self.kind_for(error)
+            case error
+            when OverloadedError then :overloaded
+            when RateLimitError then :rate_limited
+            when UnauthorizedError then :authentication
+            when PaymentRequiredError then :billing
+            when ForbiddenError then :authorization
+            when ContextLengthExceededError then :context_rejected
+            when BadRequestError then :invalid_request
+            when ModelNotFoundError then :model_missing
+            when ModelNotAllowedError then :policy
+            when Faraday::TimeoutError, Timeout::Error then :timeout
+            when Faraday::ConnectionFailed, Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError then :connection_failure
+            else :provider_error
+            end
+          end
         end
+
+        # 06 F6: the transient kinds that may be retried at the fleet edge.
+        # Classification/contract/auth/policy kinds never retry.
+        ProviderOutcome::RETRYABLE_KINDS = %i[overloaded rate_limited timeout connection_failure provider_error].freeze
       end
     end
   end

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

@@ -83,9 +83,13 @@ module Legion
 
         # An immutable selected target produced by legion-llm's selector and
         # consumed by dispatch. lex-llm validates cross-field identity only; it
-        # does not compute routing or choose a lane. See section 15.4.
+        # does not compute routing or choose a lane. lane_id is the 5 tuple
+        # tier:provider_family:instance_id:type:model; the tier part is not a
+        # Selection member, so cross-field validation covers the four parts the
+        # record does carry (family, instance, type-from-operation, model).
+        # See section 15.4.
         Selection = ::Data.define(
-          :inventory_generation, :lane_id, :instance_key, :offering_id, :provider_family, :instance_id,
+          :inventory_generation, :lane_id, :instance_key, :provider_family, :instance_id,
           :model, :operation, :callable_handle, :publisher_token_id, :capability_evidence, :context_evidence,
           :weight_inputs, :base_weight, :preference_ppm, :effective_weight, :rendezvous_score
         ) do
@@ -103,29 +107,44 @@ module Legion
             raise errors::ValidationError, 'callable_handle must be a CallableHandle' unless callable_handle.is_a?(Legion::Extensions::Llm::Inventory::CallableHandle)
 
             canonical_model = identity.normalize_text(value: kwargs[:model], field: :model)
-            canonical_operation = Legion::Extensions::Llm::Taxonomies.normalize_operation(value: kwargs[:operation], allow_aliases: false)
+            canonical_operation = Legion::Extensions::Llm::Taxonomies.normalize_operation(value: kwargs[:operation])
             family = Legion::Extensions::Llm::Inventory::RecordSupport.normalize_provider_family(value: kwargs[:provider_family])
             normalized_instance = identity.normalize_text(value: kwargs[:instance_id], field: :instance_id)
             unless family == instance_key.provider_family && normalized_instance == instance_key.instance_id
               raise errors::ValidationError, 'provider_family and instance_id must equal instance_key'
             end
 
-            offering_id = kwargs[:offering_id]
-            validate_offering_id_shape!(offering_id)
-            identity.validate_lane_id!(
-              value: kwargs[:lane_id], instance_key: instance_key, operation: canonical_operation,
-              model: canonical_model, offering_id: offering_id
-            )
+            identity.validate_lane_id!(value: kwargs[:lane_id])
+            validate_lane_id_fields!(kwargs[:lane_id], family, normalized_instance, canonical_operation, canonical_model)
             validate_publisher_token_id!(kwargs[:publisher_token_id])
 
             {
-              lane_id: kwargs[:lane_id].dup.freeze, instance_key: instance_key, offering_id: offering_id.dup.freeze,
+              lane_id: kwargs[:lane_id].to_s.dup.freeze, instance_key: instance_key,
               provider_family: family, instance_id: normalized_instance, model: canonical_model,
               operation: canonical_operation, callable_handle: callable_handle,
               publisher_token_id: kwargs[:publisher_token_id].dup.freeze
             }
           end
 
+          # Cross-field check of the 5 tuple against the parts the Selection
+          # carries: provider_family (part 2), instance_id (part 3), type from
+          # the operation (part 4), and model (part 5, colons preserved by the
+          # bounded parse). Part 1 (tier) is checked against Taxonomies::TIERS
+          # by validate_lane_id!.
+          def validate_lane_id_fields!(lane_id, family, instance_id, operation, model)
+            errors = Legion::Extensions::Llm::Inventory::Errors
+            identity = Legion::Extensions::Llm::Inventory::Identity
+            parts = identity.parse_lane_id(lane_id)
+            raise errors::ValidationError, 'lane_id provider_family does not match the selection' \
+              unless parts[1] == family.to_s
+            raise errors::ValidationError, 'lane_id instance_id does not match the selection' \
+              unless parts[2] == instance_id
+            raise errors::ValidationError, 'lane_id type does not match the selection operation' \
+              unless parts[3] == Legion::Extensions::Llm::Taxonomies.lane_type_for(operation: operation).to_s
+            raise errors::ValidationError, 'lane_id model does not match the selection' \
+              unless parts[4] == model
+          end
+
           def scoring_attributes(kwargs)
             support = Legion::Extensions::Llm::Inventory::RecordSupport
             base_weight = kwargs[:base_weight]
@@ -145,12 +164,6 @@ module Legion
             AttemptTargetKey.new(provider_family: provider_family, instance_id: instance_id, model: model)
           end
 
-          def validate_offering_id_shape!(offering_id)
-            return if offering_id.is_a?(::String) && offering_id.match?(/\Aoff:v1:[0-9a-f]{64}\z/)
-
-            raise Legion::Extensions::Llm::Inventory::Errors::ValidationError, 'offering_id must have the off:v1: shape'
-          end
-
           def validate_publisher_token_id!(publisher_token_id)
             return if publisher_token_id.is_a?(::String) && publisher_token_id.start_with?('ptok:v1:') &&
                       publisher_token_id.length > 'ptok:v1:'.length
@@ -158,12 +171,16 @@ module Legion
             raise Legion::Extensions::Llm::Inventory::Errors::ValidationError, 'publisher_token_id must be a ptok:v1: String'
           end
 
+          # U4: structural verification only — same semantics as
+          # RecordSupport.validated_weight_pair, never a second weight policy.
+          # 0 is a legal value (operator disable, 07 W3); base_weight must
+          # equal the product of the inputs.
           def validate_weight_inputs!(weight_inputs, base_weight)
             errors = Legion::Extensions::Llm::Inventory::Errors
             unless weight_inputs.is_a?(::Hash) && weight_inputs.keys.sort == %i[instance model_or_offering provider tier]
               raise errors::ValidationError, 'weight_inputs must have keys tier/provider/instance/model_or_offering'
             end
-            raise errors::ValidationError, 'weight_inputs values must be positive Integers' unless weight_inputs.values.all? { |value| value.is_a?(::Integer) && value.positive? }
+            raise errors::ValidationError, 'weight_inputs values must be nonnegative Integers' unless weight_inputs.values.all? { |value| value.is_a?(::Integer) && !value.negative? }
 
             product = weight_inputs.values.reduce(1, :*)
             raise errors::ValidationError, 'base_weight must equal the product of weight_inputs' unless base_weight == product