lex-llm-gemini 0.4.5 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fc6c5255eae71b411f35c57a052ac77bb3d9aecdb2855672472f8b1a4f4f514
-  data.tar.gz: af8645870657d5f743b398c88f96cb2a74cb849eb15afa3553b723c0d02c2f58
+  metadata.gz: 20a06f104a1d3428d0bde0a55989136dfc492468eaf348ce943f3d7d33f1d868
+  data.tar.gz: f673546dad910895150994e33e4e9ccec4c268fd88720d9ce7788be6c7baadbd
 SHA512:
-  metadata.gz: cbdc6a0ff9351f061590beedecfaeba3ccd78666aa97db675e9ff2a528834a22ba5542afd3b63bb143f8d34cd7756b0bc3719a48a84cc4423997d9dd0e07fb3e
-  data.tar.gz: 5cfcce92073c6e27a86e20b5200ae0b0babf5eec1061c20c43928c9dd34e63b0fce8311f57d7637ca4d70d49c6134d69b5b45950e415604ad3ee77e6597097c9
+  metadata.gz: 23aee8f67392983feb3676cc3075da064dc4a05c5cedbba071ba886e8ba1e7517a5c4d2f531c20efe7b28d5efceeeefa696709f9b3e65daa7f6d7cb4a90c82f4
+  data.tar.gz: 68d4afe2632f44ddc092733825ba26200ee207c7655ae2819efe1384896acb04abaa64f7ebcc06571a3b533da27a2c8eec5882cfbf13fe447b9e442f4e4c5bae

data/.rubocop.yml

@@ -14,6 +14,11 @@ Metrics/BlockLength:
     - spec/**/*
 Metrics/MethodLength:
   Enabled: false
+# Aligned with the sibling lex-llm-* providers (vllm/anthropic): the rubocop
+# default ModuleLength (100) is too strict for a discovery runner carrying the
+# full evidence-building surface. Length is still bounded (Max 350).
+Metrics/ModuleLength:
+  Max: 350
 RSpec/ExampleLength:
   Enabled: false
 RSpec/MultipleExpectations:

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.4.6] - 2026-08-20
+
+### Changed
+- **lex-llm 0.8.0 conformance (SSOT v4 contract cut):** the Gemini provider's parse/build paths migrate from the deleted legacy types to Canonical. `parse_completion_response` returns `Canonical::Response`, `build_chunk` yields `Canonical::Chunk` (text_delta / thinking_delta / tool_call_delta / usage), tool calls parse to `Array<Canonical::ToolCall>`, usage translates from `usageMetadata` to `Canonical::Usage`, and `finishReason` maps through the shared `StopReasonMapping` with the Gemini vocabulary additions (STOP, MAX_TOKENS, SAFETY, RECITATION, PROHIBITED_CONTENT, SPII, IMAGE_SAFETY). Wire-dialect tolerance (thought parts, thoughtSignature, JSON-object vs JSON-string tool arguments, Gemini finishReason spelling) lives only in the Gemini renderer/parser, per the 08 R1-R4 law.
+- The `embed` operation returns the documented artifact shape `{ text:, model:, embedding:, usage: Canonical::Usage }` (05 section 3 / O07) in place of the deleted `Llm::Embedding` type.
+- Rip the legacy `offering_from_model` -> `Routing::ModelOffering` production path from the provider: offering construction is the discovery writer's job (`OfferingDraft` + Registry publication, v3.1), and the base read path serves inventory offerings from the registry snapshot (07 C5).
+- Enforce the canonical dispatch boundary end to end (N x N law): the base funnel's central `enforce_canonical_messages!` covers chat/stream_chat, the fleet callable invokes the same shared helper at every operation entry, and the provider no longer re-implements the check (08 F2 / O05). Plain Hash/String/nil messages raise a typed `ArgumentError` at both entry forms. The callable's chat/stream_chat accept the canonical messages positionally, as the 0.8.0 funnel and fleet `WorkerExecution` hand them, and temperature travels only in `Canonical::Params` (05 O4).
+- Rip the `ScopedRefresher::LegacyCoordinatorAdapter` wiring from the discovery actor: the `Publisher` is built without a compatibility adapter and the deleted `scoped_refresher` require goes with it.
+- Raise the `lex-llm` floor from `>= 0.7.6` to `>= 0.8.0`.
+- Keep the local-tree `lex-llm` path dependency in the test group so the adjacent checkout resolves against the 0.8.x contract cut during development.
+
+### Added
+- Run the conformance kit B1 (central canonical enforcement) and B2 (canonical outputs, asserted by type) shared examples against the REAL callable boundary - the production `GeminiCallable` over the production `Gemini::Provider`, with only the HTTP transport stubbed.
+- Cover the canonical pipeline in the provider spec: `Canonical::Response` / `Canonical::Chunk` / `Canonical::ToolCall` / `Canonical::Thinking` / `Canonical::Usage` outputs asserted by type, a full streaming exchange driven through the real funnel ending in exactly one done chunk, and the Gemini wire format unchanged.
+
+### Removed
+- `provider_capability_policy_spec.rb` - it tested the deleted legacy offering production path; in 0.8.0 the SSOT data plane expresses capabilities as the writer's `capability_evidence`, and the capability-flag cascade has no provider home.
+
 ## [0.4.5] - 2026-08-19
 
 ### Changed

data/Gemfile

@@ -2,10 +2,15 @@
 
 source 'https://rubygems.org'
 
-gem 'lex-llm'
-
 gemspec
 
+# Local-tree resolution: use the adjacent lex-llm checkout when present so the
+# 0.8.0 conformance work resolves against the 0.8.x contract cut.
+group :test do
+  lex_llm_path = File.expand_path('../lex-llm', __dir__)
+  gem 'lex-llm', path: lex_llm_path if Dir.exist?(lex_llm_path)
+end
+
 group :development do
   gem 'bundler', '>= 2.0'
   gem 'rake', '>= 13.0'

data/RULES.md

@@ -0,0 +1,97 @@
+RULES.md — Legion LLM Architecture Law
+These rules apply to every task, file, repository, agent, model, session, test, refactor, migration, incident, and release.
+The requested task defines what may change. These rules define how the system ALWAYS works.
+Every rule remains active 100% of the time. If requested work conflicts with these rules, stop and surface the conflict before changing code.
+These are architecture laws. Scope, compatibility, urgency, convenience, tests, existing behavior, and model judgment do not change them.
+1. Canonical is the only internal language.
+Every client translates client wire -> Canonical before shared execution.
+Shared execution carries Canonical through context, tools, routing, direct dispatch, fleet dispatch, and response handling.
+Every provider translates Canonical -> provider wire at the provider boundary, then provider wire -> Canonical before returning to shared execution.
+Every internal boundary validates the Canonical type it is defined to receive and raises immediately when that contract is violated.
+Client Wire -> Client Translator -> Canonical -> Shared Execution -> Canonical -> Provider Translator -> Provider Wire.
+2. Serialization preserves Canonical.
+Transport may serialize Canonical state. The receiving transport boundary ALWAYS rehydrates the exact Canonical type before execution continues.
+Fleet follows Canonical -> serialize -> wire -> deserialize -> rehydrate Canonical -> Canonical.
+Serialization changes encoding only. Ownership, identity, model, operation, capability, selection, and meaning remain exactly the same.
+After rehydration, shared execution continues only with Canonical objects.
+3. Every authoritative fact has exactly one owner.
+The owner creates the fact once. Every downstream layer carries, projects, serializes, rehydrates, verifies, or executes that exact fact.
+A downstream layer receiving missing or contradictory authoritative state raises and returns the defect to the owning layer.
+Authority ALWAYS moves forward by preservation.
+Authority is created once and is never recreated downstream.
+4. Requirements describe the request. Inventory describes reality. Router chooses. Dispatch executes.
+Canonical request construction owns request semantics. RequestRequirements expresses operation, capabilities, modality, context, output, tools, and explicit pins.
+Providers publish exact executable facts into Inventory. Inventory owns canonical instance, offering, lane, capability, context, quota, health, and published weight state.
+Router.next_lane consumes Requirements plus one immutable Inventory snapshot and produces one authoritative Selection.
+Dispatch executes that Selection exactly. Once Selection exists, routing is finished.
+5. Inventory facts are immutable executable facts.
+Providers publish exact instances and complete offering snapshots through the Inventory publication contract.
+Identity, capability evidence, context evidence, quota domains, availability, and write-time weights are consumed from published Inventory state.
+A changed fact becomes authoritative only through the owning publication or reconciliation path and a new Inventory snapshot.
+Routing reads Inventory. Dispatch verifies and executes Inventory-backed Selection.
+6. Identity, capabilities, weights, and context policy retain exact ownership.
+Inventory::Identity owns instance, offering, and lane identity; canonical instance identity is provider family plus the operator/configured instance name; physical endpoint data remains secondary.
+Providers publish capability evidence. Requirements state required capabilities. Candidate evaluation compares the two and determines capability eligibility.
+The weight owner computes lane weight at publication time; Inventory stores it; ranking consumes that stored weight; a stored zero disables the lane.
+Preferred-context binning orders eligible candidates into preference bands and preserves eligibility. Capability, health, binning, and weight ALWAYS retain distinct meanings.
+7. Routing chooses exactly once.
+Router.next_lane is the sole routing authority.
+Candidate evaluation determines eligibility from Requirements and Inventory. Ranking orders eligible candidates from published routing facts.
+Selection freezes the exact provider, instance, offering, lane, model, operation, and routing identity required for execution.
+Every downstream component consumes the Selection it receives.
+Selection is preserved, not reconstructed.
+8. Exact execution stays exact through every boundary.
+Direct dispatch executes the exact Selection-derived binding it receives.
+Fleet dispatch serializes and signs that exact binding; fleet validation verifies it; fleet rehydration restores it; worker resolution verifies it against authoritative Inventory.
+The selected provider, instance, offering, lane, model, and operation remain identical through projection, signing, transport, validation, rehydration, resolution, and callable invocation.
+A mismatch raises before provider execution.
+An exact execution request ALWAYS remains exact execution.
+9. Health and errors preserve one authoritative meaning.
+Inventory owns exact-instance availability. An authoritative instance-unavailable result removes that exact instance; readiness probing owns recovery; successful readiness republish re-admits it.
+Overload, timeout, rate limit, model-not-ready, and transient provider failures remain request-local according to ProviderOutcome semantics.
+The first layer that can authoritatively classify an error performs that classification once. Every downstream layer preserves it.
+Programming errors remain programming errors. Contract violations remain contract violations. Routing exhaustion remains the defined typed Rejection.
+10. Compatibility exists only at explicit edges.
+Supported legacy clients and protocols are translated into the current Canonical and SSOT architecture at explicit compatibility boundaries.
+Shared execution remains Canonical. Routing remains SSOT-driven. Exact execution remains exact.
+Compatibility code adapts an external contract to the current internal architecture.
+The current internal architecture ALWAYS has one representation, one routing authority, one identity system, and one execution truth.
+11. Fix every defect at its owner.
+Trace the incorrect value to the layer that owns it, then fix that owner.
+Fix client wire in the client translator; Canonical shape in Canonical construction; Requirements in Requirements construction; provider facts in publication; identity in Inventory identity; weights in publication/reconciliation.
+Fix eligibility in candidate evaluation; ordering in ranking; choice in Router.next_lane; execution preservation in dispatch; provider wire in the provider translator.
+The layer where a defect becomes visible is evidence. The owning layer is where the correction belongs.
+12. A discovered issue remains in its owning domain.
+Complete the requested task inside its stated scope.
+When investigation exposes a separate defect owned by another architectural domain, record and surface it as separate work unless the requested task is explicitly expanded.
+Routing work consumes existing Canonical Requirements and Inventory facts. Canonical work changes Canonical contracts. Provider work changes publication or translation. Transport work changes transport.
+Nearby code never changes ownership. “While we are here” never changes architecture.
+13. N x N ALWAYS converges through Canonical.
+Equivalent client semantics produce equivalent Canonical state before shared execution. Every provider consumes the same Canonical semantics for the same request.
+When two paths disagree, capture the state at every involved boundary and locate the FIRST point where Canonical meaning diverges.
+Fix that first divergent boundary, then run the exact failing path again.
+Client behavior is proven at client-wire <-> Canonical. Provider behavior is proven at Canonical <-> provider-wire. Shared execution is proven with Canonical throughout.
+14. Debug from captured authoritative state.
+Capture the actual input at the failing boundary before reasoning from symptoms.
+For translation or transport defects, capture Canonical immediately before and after every involved boundary.
+For routing or dispatch defects, capture Requirements, relevant Inventory facts, Selection, execution binding, and ProviderOutcome.
+Compare each captured value to the contract owned by that layer. Find the first divergence. Fix its owner. Re-run the exact path.
+Then inspect sibling implementations for the same defect class.
+15. Tests prove the real boundary and the invariant.
+A boundary test exercises the real boundary it claims to protect.
+Fleet tests exercise real serialization, deserialization, Canonical rehydration, signing, validation, exact resolution, and callable dispatch.
+Provider tests exercise the real callable boundary and provider translator. Routing tests exercise real Requirements, Inventory records, candidate evaluation, ranking, and Selection.
+Regression tests prove the violated invariant, not only the observed symptom.
+A green suite is release evidence only when the tested path traverses the real architecture.
+16. Shared contracts are consumed directly.
+Shared Canonical types own execution representation. Shared Inventory types own inventory state. Shared Routing types own routing state.
+Shared taxonomy owns canonical mappings. Shared ProviderOutcome owns provider-neutral outcomes. Shared fleet protocol owns exact execution claims.
+Every repository consumes these shared owners directly.
+A defect in one shared boundary triggers an audit of every sibling implementation of that boundary. Fix the shared owner centrally whenever the defect belongs to a shared contract.
+17. Architecture is the release gate.
+Every change preserves every rule in this file.
+Tests, compatibility, historical behavior, migration phase, patch urgency, nearby code, task wording, and model judgment are evaluated UNDER these rules.
+A contradiction between existing behavior and these rules is surfaced as an architecture conflict and resolved at the owning boundary before release.
+Limited scope means do less. Limited scope NEVER means fewer rules apply.
+These rules apply 100% of the time.
+These are the law.

data/lex-llm-gemini.gemspec

@@ -27,5 +27,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-logging', '>= 1.3.2'
   spec.add_dependency 'legion-settings', '>= 1.4.2'
   spec.add_dependency 'legion-transport', '>= 1.4.14'
-  spec.add_dependency 'lex-llm', '>= 0.7.6'
+  spec.add_dependency 'lex-llm', '>= 0.8.0'
 end

data/lib/legion/extensions/llm/gemini/actors/discovery.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/discovery/actor'
+
+# The base discovery actor only exists inside the daemon (it inherits the
+# LegionIO time-based Every actor). In a standalone load, define nothing.
+return unless defined?(Legion::Extensions::Llm::Discovery::Actor)
+
+module Legion
+  module Extensions
+    module Llm
+      module Gemini
+        module Actor
+          # Gemini discovery actor: an EMPTY subclass of the shared base. The
+          # timer, dispatch, and runner-resolution convention are inherited —
+          # this class redefines nothing. The Gemini-specific work lives in
+          # Gemini::Runners::Discovery, resolved by the base from this
+          # namespace.
+          class Discovery < Legion::Extensions::Llm::Discovery::Actor; end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/gemini/helpers/callable.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'faraday'
+
+require 'legion/extensions/llm/error'
+require 'legion/extensions/llm/routing/provider_outcome'
+require 'legion/extensions/llm/canonical'
+require 'legion/extensions/llm/gemini/provider'
+
+module Legion
+  module Extensions
+    module Llm
+      module Gemini
+        module Helpers
+          # Dispatch-error classification for the Gemini callable (mixed into
+          # Callable). Pure functions of the error — no instance state.
+          # §8 health firewall: only the explicit Gemini UNAVAILABLE body maps
+          # to :instance_unavailable; status codes alone (503/529) are
+          # request-local overload conditions.
+          module DispatchErrorClassification
+            private
+
+            def classify_dispatch_error(error:)
+              return :connection_failure if error.is_a?(Faraday::ConnectionFailed)
+              return :timeout if error.is_a?(Faraday::TimeoutError)
+              return :overloaded if error.is_a?(Legion::Extensions::Llm::OverloadedError)
+              return classify_by_status(error: error) if http_status_error?(error)
+
+              :provider_error
+            end
+
+            def http_status_error?(error)
+              error.is_a?(Faraday::ClientError) || error.is_a?(Faraday::ServerError) ||
+                error.is_a?(Legion::Extensions::Llm::Error)
+            end
+
+            def classify_by_status(error:)
+              return :instance_unavailable if explicit_service_unavailable?(error: error)
+
+              status = dispatch_status(error)
+              return :model_not_ready if status.is_a?(::Integer) && status >= 500 &&
+                                         model_not_ready_signal?(error: error)
+
+              status_kind(status)
+            end
+
+            def status_kind(status)
+              case status
+              when 401 then :authentication
+              when 403 then :authorization
+              when 404 then :model_missing
+              when 429 then :rate_limited
+              when 503, 529 then :overloaded
+              when 400...500 then :invalid_request
+              else :provider_error
+              end
+            end
+
+            # Returns true only when the Gemini API response body explicitly
+            # carries "status":"UNAVAILABLE" — the flat service-level
+            # unavailability signal distinct from throttling
+            # (RESOURCE_EXHAUSTED) or model loading.
+            def explicit_service_unavailable?(error:)
+              body = response_body_string(error)
+              return false if body.nil?
+
+              (body.include?('"status":"UNAVAILABLE"') || body.include?('"status": "UNAVAILABLE"')) &&
+                !body.include?('RESOURCE_EXHAUSTED')
+            end
+
+            def model_not_ready_signal?(error:)
+              body = response_body_string(error)&.downcase
+              body.to_s.include?('model not ready') || body.to_s.include?('model is still loading')
+            end
+
+            # Reads the body from every real Faraday error shape: Faraday::Env
+            # (Faraday 2.x — a Struct, NOT a Hash, which is why an
+            # is_a?(Hash) gate here is dead in production), Faraday::Response
+            # (lex-llm ErrorMiddleware), or the plain response Hash (Faraday
+            # RaiseError middleware / Faraday 1.x).
+            def response_body_string(error)
+              response = error.respond_to?(:response) ? error.response : nil
+              return nil unless response
+
+              body = response.respond_to?(:body) ? response.body : (response[:body] if response.respond_to?(:[]))
+              return body if body.is_a?(String)
+
+              body && ::JSON.generate(body)
+            end
+
+            def dispatch_status(error)
+              return error.response_status if error.respond_to?(:response_status) && error.response_status
+
+              response = error.respond_to?(:response) ? error.response : nil
+              response.respond_to?(:status) ? response.status : nil
+            end
+          end
+
+          # Callable wrapper for a Gemini provider instance. Implements the
+          # fleet dispatch ops (chat/stream_chat/embed/count_tokens) by
+          # delegating to a per-instance Gemini::Provider, plus the
+          # disconnect and normalize_dispatch_error contracts required by
+          # Inventory::CallableHandle and Routing::ProviderOutcome. Dispatch
+          # errors propagate untouched so normalize_dispatch_error can
+          # classify them.
+          class Callable
+            include DispatchErrorClassification
+
+            def initialize(instance_cfg:, logger:, provider: nil)
+              @instance_cfg  = instance_cfg
+              @logger        = logger
+              @provider      = provider
+              @disconnected  = false
+            end
+
+            def disconnected? = @disconnected
+
+            def disconnect
+              @disconnected = true
+              @provider&.disconnect
+              @logger.debug { '[gemini][callable] disconnected' }
+            end
+
+            # Named completion kwargs the base Provider funnel accepts
+            # directly (08 F3); everything else in the fleet's **rest is
+            # folded wire params that become a Canonical::Params at the
+            # boundary (05 O4 — temperature is a params member, never a kwarg).
+            COMPLETION_NAMED_KEYS = %i[tools schema thinking tool_prefs headers].freeze
+            EMBED_NAMED_KEYS = %i[dimensions headers].freeze
+
+            # Fleet and SelectionDispatch pass model as a RAW STRING (the
+            # offering's model id). It passes through untranslated to the
+            # provider funnel — the base model_identity and the Gemini
+            # renderer both accept the bare string (0.8.0 contract).
+            # messages is positional — the 0.8.0 funnel and fleet WorkerExecution
+            # both hand the canonical Array<Canonical::Message> positionally.
+            def chat(messages, model:, **rest)
+              # Canonical boundary (N x N law): pipeline dispatch delivers
+              # Canonical::Message objects only. Hash/legacy shapes are the
+              # bypass class — reject loudly, never coerce.
+              provider.enforce_canonical_messages!(messages)
+              named, params = split_fleet_kwargs(rest, COMPLETION_NAMED_KEYS)
+              provider.chat(messages, model: model, params: canonical_params(params), **named)
+            end
+
+            def stream_chat(messages, model:, **rest, &)
+              provider.enforce_canonical_messages!(messages)
+              named, params = split_fleet_kwargs(rest, COMPLETION_NAMED_KEYS)
+              provider.stream_chat(messages, model: model, params: canonical_params(params), **named, &)
+            end
+
+            def embed(text:, model:, **rest)
+              named, params = split_fleet_kwargs(rest, EMBED_NAMED_KEYS)
+              provider.embed(text: text, model: model, params: params, **named)
+            end
+
+            def count_tokens(messages:, model:, **rest)
+              provider.enforce_canonical_messages!(messages)
+              _named, params = split_fleet_kwargs(rest, [])
+              provider.count_tokens(messages: messages, model: model, params: params)
+            end
+
+            def normalize_dispatch_error(error:)
+              reason = error.message.to_s[0, 512]
+              Legion::Extensions::Llm::Routing::ProviderOutcome.new(
+                kind: classify_dispatch_error(error: error), reason: reason.empty? ? 'unknown dispatch error' : reason
+              )
+            end
+
+            private
+
+            # The 0.8.0 completion funnel receives canonical values only
+            # (08 F3): the folded wire params become a Canonical::Params at
+            # the dispatch boundary — the renderer reads params.temperature /
+            # params.max_tokens, a raw Hash would NoMethodError.
+            def canonical_params(params)
+              Legion::Extensions::Llm::Canonical::Params.from_hash(params)
+            end
+
+            # Split the fleet's **rest into the base Provider's named kwargs
+            # and a payload params hash (any passed :params merged with the
+            # remaining unknown keys). Mirrors the shared callable boundary.
+            def split_fleet_kwargs(rest, named_keys)
+              named = rest.slice(*named_keys)
+              extra = rest.reject { |key, _| named.key?(key) }
+              params = (extra.delete(:params) || {}).to_h.merge(extra)
+              [named, params]
+            end
+
+            def provider = @provider ||= build_provider
+
+            def build_provider
+              Legion::Extensions::Llm::Gemini::Provider.new(
+                {
+                  gemini_api_key: @instance_cfg[:gemini_api_key] || @instance_cfg[:api_key] ||
+                                  @instance_cfg.dig(:credentials, :api_key),
+                  gemini_api_base: @instance_cfg[:gemini_api_base] || @instance_cfg[:endpoint]
+                }.compact
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end