lex-llm-anthropic 0.2.13 → 0.2.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ea542d2f08da7b03e8f42e683dca5638bdaf07966f3389cdfcccfa22f8581b0
-  data.tar.gz: b0e902241e5dd1c94c3742f9cee76d4aa2a41516829ce5c481084e70378826cc
+  metadata.gz: b5592d5457b4e1cc4b1b64b4133ca43f99a6de148044d70606c4dfa794b724e0
+  data.tar.gz: b05ebe4ac3373d36e6fd2ad71716c372a50ac9c50641e88ac710cdb66ba6c261
 SHA512:
-  metadata.gz: 333cff908f11b23fe522c2bb79743d879b5adf0d7ce952e0b989becb9da775b58a528ba7f52ec42b7f7ef188d4d7b3db29db9700df4b17e0435c0e4de0087b1c
-  data.tar.gz: 57ad771fb6b041d74e1459bb46e5cd471f8f37f416b014bcc6873f97aca3fe0aea74c7a943ddfb3d8418bbf6ade69a0cda8fa6cc755134df53eabf9abeaaf1f1
+  metadata.gz: a123eae076f23634c8ce0437bbdc382b53e7cdecfec5357441bf4b92b73285959911076a525bf584c726f30aceb35b4d3f9fb275039adfb7c2bd02f5fc721a50
+  data.tar.gz: 131feec5dbb20ec692f3f2e5f8bf83b1b777e16ae7c6798e8931410449eb31be9008b89e0f3ba5f8e27da6d72003de0bf639b2f37b3525b67f5fa72f3f3fb992

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.15 - 2026-06-05
+
+- **Fix RuboCop cyclomatic complexity** — Extract `extract_hash_budget` helper to reduce `thinking_budget` cyclomatic complexity from 8 to 6, meeting the 7-line threshold.
+- **Add budget_tokens support** — `extract_hash_budget` now checks `:budget_tokens` and `'budget_tokens'` keys (Anthropic API canonical) in addition to legacy `:budget`/`'budget'`.
+- **Spec and RuboCop compliance** — All 28 specs passing, 0 RuboCop offenses.
+
+## 0.2.14 - 2026-06-05
+
+- **Fix RuboCop cyclomatic complexity** — Extract `extract_hash_budget` helper to reduce `thinking_budget` complexity from 8 to 6, meeting the 7-line threshold.
+- **Fix Style/IfUnlessModifier** — Split conditional return in `thinking_budget` to avoid modifier form exceeding max line length.
+
 ## 0.2.13 - 2026-06-02
 
 - **Fix invalid anthropic-version header** — Default `api_version` was `'2023-10-02'` (typo), which Anthropic rejects. Changed to `'2023-10-16'` (anthropic.rb)

data/README.md

@@ -1,10 +1,36 @@
 # lex-llm-anthropic
 
-LegionIO LLM provider extension for Anthropic.
+LegionIO LLM provider extension for **Anthropic Claude** models.
 
-This gem lives under `Legion::Extensions::Llm::Anthropic` and depends on `lex-llm >= 0.4.3` for shared provider contracts, response normalization, fleet responder helpers, and schema primitives. It does not require `legion-llm` at runtime.
+This gem provides the `:anthropic` provider family for LegionIO's LLM routing layer, connecting to the [Anthropic Messages API](https://docs.anthropic.com/en/docs/api/messages). It handles chat completions, streaming, tool use, extended thinking, model discovery, and fleet request consumption.
 
-Load it with `require 'legion/extensions/llm/anthropic'`.
+**Namespace:** `Legion::Extensions::Llm::Anthropic`
+**Provider family:** `:anthropic`
+**Default model:** `claude-sonnet-4-6`
+**Dependency:** `lex-llm >= 0.4.3` (shared provider contracts, response normalization, fleet responders)
+
+```ruby
+require 'legion/extensions/llm/anthropic'
+```
+
+---
+
+## File Index
+
+| File | Role |
+|------|------|
+| `anthropic.rb` | Entry point; namespace, `PROVIDER_FAMILY`, default settings, instance discovery |
+| `anthropic/provider.rb` | `Provider` class — chat, stream, list_models, format/parse payloads |
+| `anthropic/registry_event_builder.rb` | Builds registry event envelopes for model availability |
+| `anthropic/registry_publisher.rb` | Publishes model events to `llm.registry` exchange (async, best-effort) |
+| `anthropic/version.rb` | `VERSION` constant |
+| `anthropic/actors/discovery_refresh.rb` | Periodic actor that refreshes Anthropic model list |
+| `anthropic/actors/fleet_worker.rb` | Subscription actor for fleet request consumption |
+| `anthropic/runners/fleet_worker.rb` | Runner entrypoint for fleet request execution |
+| `anthropic/transport/exchanges/llm_registry.rb` | Topic exchange definition for `llm.registry` |
+| `anthropic/transport/messages/registry_event.rb` | Transport message wrapper for registry events |
+
+---
 
 ## Installation
 
@@ -12,36 +38,83 @@ Load it with `require 'legion/extensions/llm/anthropic'`.
 gem 'lex-llm-anthropic', '~> 0.2'
 ```
 
-Anthropic credentials are discovered from `ANTHROPIC_API_KEY`, Claude config, configured provider instances, or an identity broker when one is available.
+---
 
-## Provider
+## Architecture
 
-`Legion::Extensions::Llm::Anthropic::Provider` registers with `Legion::Extensions::Llm::Provider` as `:anthropic` and uses Anthropic's Messages API:
+### Provider (`Provider`)
 
-- chat and streaming: `/v1/messages`
-- model discovery: `/v1/models`
-- authentication headers: `x-api-key` and `anthropic-version`
-- tools: Anthropic `tools` and `tool_choice` payload fields
-- extended thinking: Anthropic `thinking` request field and returned thinking blocks
+The `Provider` class extends the `lex-llm` base provider contract and implements:
 
-Anthropic embeddings are intentionally not exposed by this provider.
+| Method | Description |
+|--------|-------------|
+| `chat(**kwargs)` | Synchronous chat completion via `/v1/messages` |
+| `stream_chat(**kwargs)` | Streaming chat via `/v1/messages?stream=true` |
+| `list_models` | Fetches available models from `/v1/models` |
+| `format_payload(**)` | Builds Anthropic Messages API request body |
+| `parse_response(response)` | Normalizes API response to Legion envelope |
+| `parse_stream(response)` | Parses SSE stream into chunk events |
+| `build_chunk(event, state)` | Accumulates streaming state (content, tool calls, thinking) |
 
-## Configuration
+**Supported capabilities:** `:completion`, `:streaming`, `:vision`, `:tools`
+
+**API endpoints:**
+- Chat & streaming: `POST /v1/messages`
+- Model discovery: `GET /v1/models`
+
+**Authentication headers:** `x-api-key`, `anthropic-version`
+
+### Instance Discovery (`discover_instances`)
+
+The extension discovers and normalizes Anthropic credentials from four sources, in priority order:
+
+1. **Environment** — `ANTHROPIC_API_KEY`
+2. **Claude config** — `~/.claude/settings.json` under `anthropicApiKey`
+3. **Extension settings** — `Legion::Settings` at `extensions.llm.anthropic`
+4. **Identity broker** — `Legion::Identity::Broker.credential_for(:anthropic)`
+
+Named instances are supported under `extensions.llm.anthropic.instances.<name>`. Generic keys (`api_key`, `endpoint`, `version`) are normalized to Anthropic-specific keys (`anthropic_api_key`, `anthropic_api_base`, `anthropic_version`). Duplicate credentials are deduplicated by fingerprint.
+
+### Default Settings
 
 ```ruby
-Legion::Extensions::Llm.configure do |config|
-  config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY')
-  config.anthropic_version = '2023-06-01'
-end
+{
+  default_model: 'claude-sonnet-4-6',
+  endpoint: 'https://api.anthropic.com',
+  api_version: '2023-10-16',
+  default_max_tokens: 4096,
+  tier: :frontier,
+  transport: :http,
+  credentials: { api_key: 'env://ANTHROPIC_API_KEY' },
+  usage: { inference: true, embedding: false, image: false },
+  limits: { concurrency: 4 },
+  fleet: {
+    enabled: false,
+    respond_to_requests: false,
+    capabilities: %i[chat stream_chat],
+    lanes: [],
+    concurrency: 4,
+    queue_suffix: nil
+  }
+}
 ```
 
-`anthropic_api_base` can override the default `https://api.anthropic.com` endpoint for tests or compatible Anthropic gateways.
+### Registry Events (Availability Publishing)
+
+After model discovery, discovered models are published to the `llm.registry` topic exchange so other LegionIO nodes can discover Anthropic availability.
+
+| Class | Role |
+|-------|------|
+| `RegistryEventBuilder` | Builds the event envelope with model offering, health, and metadata |
+| `RegistryPublisher` | Schedules async publish; checks transport readiness before sending |
+| `Transport::Messages::RegistryEvent` | Message wrapper targeting the `llm.registry` exchange |
+| `Transport::Exchanges::LlmRegistry` | Topic exchange definition (`llm.registry`) |
 
-Named instances can use generic provider keys such as `api_key`, `endpoint`, and `version`; the extension normalizes them to Anthropic-specific provider options during discovery.
+Publishing is **best-effort** and requires transport to be loaded. Failures are logged at `debug` level and silently absorbed.
 
-## Fleet Responder
+### Fleet Responder
 
-Provider instances can opt in to consuming Legion LLM fleet requests. The provider-owned fleet actor only starts when at least one configured instance enables `respond_to_requests`.
+Provider instances can consume Legion LLM fleet requests. The fleet actor only starts when at least one configured instance enables `respond_to_requests`.
 
 ```yaml
 extensions:
@@ -57,4 +130,103 @@ extensions:
               - stream_chat
 ```
 
-Fleet execution is delegated to `Legion::Extensions::Llm::Fleet::ProviderResponder` from `lex-llm`. The responder owns provider invocation for this gem; routing and fleet request publication remain outside this provider extension.
+| Component | Role |
+|-----------|------|
+| `Actor::FleetWorker` | Subscription actor; checks if any instance enables fleet responding |
+| `Runners::FleetWorker` | Runner entrypoint; delegates to `lex-llm` `ProviderResponder` |
+
+Fleet execution is delegated to `Legion::Extensions::Llm::Fleet::ProviderResponder` from `lex-llm`. Routing and fleet request publication are handled outside this extension.
+
+### Model Discovery Refresh
+
+A periodic actor (`Actor::DiscoveryRefresh`) refreshes the Anthropic model list every 30 minutes (configurable via `extensions.llm.anthropic.discovery_interval`). It calls `Legion::LLM::Discovery.refresh_discovered_models!(provider: :anthropic)`.
+
+---
+
+## Configuration
+
+```ruby
+Legion::Extensions::Llm.configure do |config|
+  config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY')
+  config.anthropic_version = '2023-10-16'
+end
+```
+
+**Configurable options:**
+
+| Setting | Key | Description |
+|---------|-----|-------------|
+| API key | `anthropic_api_key` / `ANTHROPIC_API_KEY` | Required; API authentication |
+| API version | `anthropic_version` | Defaults to `2023-10-16` |
+| Endpoint | `anthropic_api_base` | Override `https://api.anthropic.com` |
+| Max tokens | `default_max_tokens` | Defaults to `4096` |
+| Discovery interval | `discovery_interval` (seconds) | Defaults to `1800` |
+
+---
+
+## Usage Examples
+
+### Chat (synchronous)
+
+```ruby
+provider = Legion::Extensions::Llm::Anthropic::Provider.new(api_key: 'sk-ant-...')
+response = provider.chat(model: 'claude-sonnet-4-6', messages: [{ role: 'user', content: 'Hello' }])
+```
+
+### Chat (streaming)
+
+```ruby
+provider.stream_chat(model: 'claude-sonnet-4-6', messages: [{ role: 'user', content: 'Hello' }]) do |chunk|
+  print chunk[:content] if chunk[:content]
+end
+```
+
+### With tools
+
+```ruby
+response = provider.chat(
+  model: 'claude-sonnet-4-6',
+  messages: [{ role: 'user', content: 'What is the weather in SF?' }],
+  tools: [{ name: 'get_weather', description: '...', input_schema: { ... } }]
+)
+```
+
+### Extended thinking
+
+```ruby
+response = provider.chat(
+  model: 'claude-sonnet-4-6',
+  messages: [{ role: 'user', content: 'Solve this math problem...' }],
+  thinking: { budget_tokens: 4096, enabled: true }
+)
+```
+
+---
+
+## Dependencies
+
+| Gem | Minimum version | Role |
+|-----|-----------------|------|
+| `lex-llm` | `>= 0.4.3` | Base provider contract, response normalization, fleet responder, auto-registration |
+| `legion-logging` | (via lex-llm) | Logging helper for diagnostics |
+| `legion-settings` | (via lex-llm) | Configuration access |
+| `legion-transport` | (via lex-llm) | Message exchange for registry events |
+
+---
+
+## Testing
+
+```bash
+bundle exec rspec    # 28 examples
+bundle exec rubocop  # 0 offenses
+```
+
+---
+
+## Design Notes
+
+- **No embeddings** — Anthropic embeddings are intentionally not exposed.
+- **No `:claude` alias** — `provider_aliases` returns `[]`; only `:anthropic` is registered.
+- **Prompt caching** — When `cache_enabled?` is true, system content and tool definitions are marked as cache breakpoints; early conversation turns are cacheable, the final message is never cached.
+- **Thinking budget** — Supports `Integer`, `Hash` (with `:budget_tokens` or legacy `:budget`), and objects responding to `#budget`. Defaults to `1024`.
+- **Context windows** — Static `CONTEXT_WINDOWS` map covers known Claude model families; `fetch_model_detail` and `infer_context_window` provide fallback inference.

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

@@ -231,12 +231,17 @@ module Legion
 
           def thinking_budget(thinking)
             return thinking if thinking.is_a?(Integer)
-            return thinking[:budget] || thinking['budget'] if thinking.is_a?(Hash)
+            return extract_hash_budget(thinking) if thinking.is_a?(Hash)
             return thinking.budget if thinking.respond_to?(:budget) && thinking.budget
 
             1024
           end
 
+          # Anthropic API uses :budget_tokens, but legacy config may use :budget
+          def extract_hash_budget(thinking)
+            thinking[:budget_tokens] || thinking['budget_tokens'] || thinking[:budget] || thinking['budget']
+          end
+
           def thinking_block(thinking)
             return nil unless thinking
 

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Anthropic
-        VERSION = '0.2.13'
+        VERSION = '0.2.15'
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-anthropic
 version: !ruby/object:Gem::Version
-  version: 0.2.13
+  version: 0.2.15
 platform: ruby
 authors:
 - LegionIO