lex-llm-anthropic 0.3.5 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37a7bf28c47d62711e925d75c0717bf45c952d4b899a5c84794f7544a395ad21
-  data.tar.gz: caad53642cf6b4123b41a30a0941dae91c587b7c79e89f16c49d737fb76aae13
+  metadata.gz: 2ee85fd86d41029ba981f01d33cce9ad7f390f65b61cdd02b2fc15193b718d11
+  data.tar.gz: eeec4dfe3bb5d4f0815de6fefc733fa36e7cefed795d2c78462cf8283f44fa0c
 SHA512:
-  metadata.gz: 217cbbf2136c44b3a362c78a8d787c646ac6a93746a3bd967a279301023cc5050e39fef902c38e624c1f7080806785784c1df93432c469c96221dbfb059c66b9
-  data.tar.gz: d6677021c2251c507705c6ada10d5378f54d97e20ea7176b0b00099ca62269063d593fce722c3d051dae53294eca1a8797769b7bf4edb18fb519fea485ef8b5b
+  metadata.gz: d7b39fcd77411152616451c234f1994a1ddf42f6278d22ff3fbeb34580fb215130e9035a72944dc5e566fbe3a158f58a6cfaddde3bb6ac81ceba91b6e58508a3
+  data.tar.gz: 93f22be2a6a885ead678affd737ca6c0eae9582f341b5eaf278b876fea6bd9f145281a1892f5c5f8139a9bbe612d4609b77ea29eb70eca9c54ee89be9f39ba12

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.3.7] - 2026-08-25
+
+### Fixed
+- **Thinking budget reconciliation (SSOT bridge)** — `render_thinking_config` now uses `Canonical::Thinking::Config#resolved_budget` as the single source for the Anthropic wire `budget_tokens`, correctly deriving budget from effort-only clients (e.g. OpenAI effort → Anthropic budget). Removed references to deleted `Canonical::Params#max_thinking_tokens` (NoMethodError on lex-llm 0.8.x) and removed the fabricated `default_thinking_budget` config key fallback.
+- **Budget/max_tokens clamp** — The Anthropic API 400s when `budget_tokens >= max_tokens`. The translator now clamps budget to `max_tokens - OUTPUT_RESERVE` when the resolved budget would violate this constraint, with a floor at `MINIMUM_BUDGET_TOKENS` (1024).
+- **`thinking_enabled?` tightened** — Only gates on `Canonical::Thinking::Config#enabled?`; the Hash truthy branch (dead code since tc is always a Config) is removed.
+- **Stale spec migration** — Removed `max_thinking_tokens: nil` from `Params.new` calls in translator specs (member deleted in lex-llm 0.8.x).
+
+### Added
+- `translator_thinking_spec.rb` — effort-only → budget derivation, budget >= max_tokens clamping (including floor at 1024), disabled/absent thinking suppression, and source-level contract assertions (no `max_thinking_tokens` or `default_thinking_budget` references).
+
+## [0.3.6] - 2026-08-20
+
+### Changed
+- **lex-llm 0.8.0 conformance (complete contract cut)** — The provider is migrated off the deleted legacy type set to Canonical end-to-end. The sync parse returns the translator's `Canonical::Response` directly (the `to_legacy_message` / `to_legacy_chunk` re-canonicalizing bridges are ripped); the streaming parse yields `Canonical::Chunk` objects (asserted by type, kit B2); the render seam renders the Anthropic wire payload FROM canonical values only — `Canonical::Message` content (`String` / `ContentBlock` / `Array<ContentBlock>`, thinking as a content block with the signature in block metadata, images as `:image` blocks), `Canonical::Params` (temperature lives only there — the `temperature:` kwarg is gone from the render boundary per 05 O4), and `Canonical::Thinking::Config` (`enabled?` + `resolved_budget`, no fabricated default). The provider-side `build_canonical_messages` re-implementation is ripped — central enforcement is the base funnel's job (08 F2). The fleet callable stays canonical-only: `chat` / `stream_chat` call `Provider#enforce_canonical_messages!` (the one shared helper at the exact-execution boundary) and take messages as the 0.8.0 funnel positional; the fleet wire's Hash `params` / `thinking` are normalized to `Canonical::Params` / `Canonical::Thinking::Config` at the boundary, and in-process canonical values pass through — the render path sees canonical only.
+- **Legacy coordinator wiring removed** — The `LegacyCoordinatorAdapter` compatibility adapter and the `scoped_refresher` require are gone from the discovery actor (the file is deleted in lex-llm 0.8.0); the `Inventory::Publisher` is constructed with the provider family only.
+- **discover_offerings served from the Registry snapshot** — The legacy `offering_from_model` read path (live model listing + filter helpers) is removed with the base; the discovery actor remains the sole publication path (07 C5 / 08 D3).
+- **Streaming tool-call fragments** — `content_block_start` and `input_json_delta` events emit the canonical delta-fragment Hash (`id` / `name` / `arguments` / `index`) the shared `StreamAccumulator` correlates by wire index; `message_start` carries the wire model in chunk metadata (the accumulator's `metadata[:model]` read), so the response model is wire-reported.
+- **lex-llm floor raised to 0.8.0** — Requires the complete 0.8.0 contract cut. A local-tree `lex-llm` path dependency in the test group resolves the adjacent checkout during development.
+
+### Added
+- **Boundary regression coverage (kit B1/B2)** — The dispatch-boundary conformance block asserts the loud reject through the real callable: plain-Hash input and the deleted legacy Message shape (replayed as a plain object with the old interface) raise `ArgumentError` on `chat` and `stream_chat`; `Canonical::Message` input renders through the full dispatch path and returns a `Canonical::Response` asserted by type.
+
 ## [0.3.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 local 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-anthropic.gemspec

@@ -27,5 +27,8 @@ 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'
+  # 0.8.0 is the complete contract cut: Canonical is the only internal language,
+  # the legacy type set and the LegacyCoordinatorAdapter wiring are deleted, and
+  # the provider funnel enforces canonical messages centrally.
+  spec.add_dependency 'lex-llm', '>= 0.8.0'
 end

data/lib/legion/extensions/llm/anthropic/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 Anthropic
+        module Actor
+          # Anthropic discovery actor: an EMPTY subclass of the shared base. The
+          # timer, dispatch, and runner-resolution convention are inherited — this
+          # class redefines nothing. The Anthropic-specific work lives in
+          # Anthropic::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/anthropic/helpers/callable.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+require 'legion/extensions/llm/routing/provider_outcome'
+require 'legion/extensions/llm/canonical'
+require 'legion/extensions/llm/anthropic/provider'
+
+module Legion
+  module Extensions
+    module Llm
+      module Anthropic
+        module Helpers
+          # Callable wrapper for an Anthropic provider instance. Implements the
+          # fleet dispatch operations (chat, stream_chat, embed, count_tokens) by
+          # delegating to a per-instance Anthropic::Provider, plus the
+          # `disconnect` and `normalize_dispatch_error(error:)` contracts required
+          # by Inventory::CallableHandle and Routing::ProviderOutcome.
+          #
+          # Dispatch errors propagate unmodified so the coordinator can classify
+          # them through normalize_dispatch_error.
+          #
+          # CRITICAL: Anthropic 529 overloaded_error is ALWAYS :overloaded.
+          # It is NEVER :instance_unavailable. Only explicit connection failures
+          # at the transport layer map to :connection_failure (which the
+          # discovery harness may escalate to :instance_unavailable).
+          class Callable
+            # Provider dispatch kwargs the 0.8.0 base funnel accepts by name.
+            # temperature is not one of them (05 O4) — it lives only in
+            # Canonical::Params. Any other fleet param is merged into the
+            # provider `params:` passthrough as canonical Params.
+            CHAT_PROVIDER_KEYS = %i[tools params headers schema thinking tool_prefs].freeze
+            EMBED_PROVIDER_KEYS = %i[dimensions params headers].freeze
+
+            def initialize(instance_cfg:, logger:)
+              @instance_cfg = instance_cfg
+              @logger = logger
+              @provider_mutex = Mutex.new
+              @disconnected = false
+            end
+
+            # The wrapped per-instance provider (built lazily on first dispatch).
+            def provider
+              @provider_mutex.synchronize do
+                @provider ||= build_provider
+              end
+            end
+
+            def disconnected?
+              @disconnected
+            end
+
+            def chat(messages, model:, **rest)
+              # Canonical boundary (N x N law): fleet dispatch delivers
+              # Canonical::Message objects only. Native/Hash shapes are the
+              # bypass class (the 2026-08-19 incident) — reject loudly, never coerce.
+              provider.enforce_canonical_messages!(messages)
+              provider.chat(messages, model:,
+                                      **dispatch_kwargs(rest, known: CHAT_PROVIDER_KEYS))
+            end
+
+            def stream_chat(messages, model:, **rest, &)
+              provider.enforce_canonical_messages!(messages)
+              provider.stream_chat(messages, model:,
+                                             **dispatch_kwargs(rest, known: CHAT_PROVIDER_KEYS), &)
+            end
+
+            def embed(text:, model:, **rest)
+              provider.embed(text: text, model:,
+                                       **dispatch_kwargs(rest, known: EMBED_PROVIDER_KEYS))
+            end
+
+            def count_tokens(messages:, model:, **rest)
+              provider.count_tokens(messages: messages, model:, params: rest)
+            end
+
+            def disconnect
+              @provider_mutex.synchronize do
+                @disconnected = true
+                @provider&.disconnect
+                @provider = nil
+              end
+              @logger.debug { '[anthropic][callable] disconnected' }
+            end
+
+            def normalize_dispatch_error(error:)
+              reason = error.message.to_s[0, 512]
+
+              kind = case error
+                     when Faraday::ConnectionFailed
+                       :connection_failure
+                     when Faraday::TimeoutError
+                       :timeout
+                     when Faraday::ClientError
+                       classify_client_error(error: error)
+                     when Faraday::ServerError
+                       classify_server_error(error: error)
+                     when Legion::Extensions::Llm::OverloadedError
+                       :overloaded
+                     else
+                       :provider_error
+                     end
+
+              Legion::Extensions::Llm::Routing::ProviderOutcome.new(
+                kind:   kind,
+                reason: reason.empty? ? 'unknown dispatch error' : reason
+              )
+            end
+
+            private
+
+            def build_provider
+              Legion::Extensions::Llm::Anthropic::Provider.new(@instance_cfg)
+            end
+
+            # The 0.8.0 completion funnel receives canonical values only
+            # (08 F3): the folded wire params become a Canonical::Params at
+            # the dispatch boundary — temperature is a params member (05 O4),
+            # never a kwarg. In-process dispatch already passes canonical
+            # values; they converge here.
+            def dispatch_kwargs(rest, known:)
+              known_part = rest.slice(*known)
+              extra = rest.except(*known)
+              known_part[:params] = canonical_params(known_part[:params], extra)
+              known_part
+            end
+
+            def canonical_params(params, extra)
+              base = case params
+                     when Legion::Extensions::Llm::Canonical::Params then params.to_h
+                     when Hash then params.transform_keys(&:to_sym)
+                     else {}
+                     end
+              base = base.merge(extra.transform_keys(&:to_sym)) unless extra.empty?
+              return nil if base.empty?
+
+              Legion::Extensions::Llm::Canonical::Params.from_hash(base)
+            end
+
+            def classify_client_error(error:)
+              status = error.respond_to?(:response_status) ? error.response_status : nil
+              case status
+              when 401 then :authentication
+              when 403 then :authorization
+              when 404 then :model_missing
+              when 429 then :rate_limited
+              else :invalid_request
+              end
+            end
+
+            def classify_server_error(error:)
+              # 529 is Anthropic's overloaded_error status — ALWAYS :overloaded, NEVER :instance_unavailable.
+              # 503 from Anthropic also indicates transient overload, not instance loss.
+              # Only explicit transport-layer connection failures (classified above as
+              # Faraday::ConnectionFailed) can escalate to :instance_unavailable at the harness layer.
+              status = error.respond_to?(:response_status) ? error.response_status : nil
+              case status
+              when 503, 529 then :overloaded
+              else :provider_error
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end