lex-claude 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8c5c2b51600c9ad2055444792e52f9e283c0bf5ebf32fedf04ac257f27adaed
-  data.tar.gz: d9d22feccce327d9c0de5e785241fe655d6f722d4f4d8f251932dccea30992d4
+  metadata.gz: 0b422c38d51391b457e88f4760b941afe22a835be9ba5405812a89024e082bb4
+  data.tar.gz: 23c95a1d66de519a7f24d9bdf86d522d13cc53b47732bdce3709dcee09df20bd
 SHA512:
-  metadata.gz: fbe826ba9a0c958abbbc84fb394016d3b96fef65938531847c9f6da1861757b7a66fa1eab2931fd36c158cd1db2a0fd002b6f095f104ec374add77e8b45c300a
-  data.tar.gz: d69483be77a939199f0db0e018c057eb76a33d56c972e067647d66d86217608676fab4f74dbd19dc9ea49e0ff78376dc9d3d2b69360603d24c2478f577b254ca
+  metadata.gz: aa72850dab4628a3fcf6e6f6bd479ec5e3d4c9518710f05ab28f695c3f4b6834bb3615fbb79630b111d66317b13938a0145f281b93b6e0edab3a2e3e91f48c14
+  data.tar.gz: a0a9cff50d0bbd456f5eb2fd0270132721ddfad15d60d140aa63277bbb80a604c27aafb1e56ddacfdd89e85d573aec8dc755fa58a8f7fcb907f672f543eb5cec

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.3.0] - 2026-03-31
+
+### Added
+- `Helpers::Errors` — structured exception hierarchy (`ApiError`, `RateLimitError`, `OverloadedError`, `AuthenticationError`, `PermissionError`, `NotFoundError`, `InvalidRequestError`, `ServerError`, `StreamingError`); `from_response` factory; `retryable?` predicate
+- `Helpers::Retry` — exponential backoff retry wrapper (`with_retry`) with configurable `max_attempts`, `base_delay`, `max_delay`
+- `Helpers::Sse` — SSE event stream parser (`parse_stream`), text assembler (`collect_text`), usage merger (`collect_usage`)
+- `Helpers::Response` — `handle_response` raises typed exceptions on non-2xx, parses 9 Anthropic rate limit headers, `parse_usage` extracts standard + cache token counts
+- `Helpers::Client::BETA_HEADERS` — registry of 18 named beta identifiers; `client` factory accepts `betas:` array
+- `Helpers::Client.streaming_client` — Faraday connection for SSE responses
+- `Helpers::Tools` — `web_search` factory, `cache_control` helper, `required_betas_for` inspector
+- `Helpers::Models` — registry of 11 canonical Claude model IDs with Symbol alias resolution; `adaptive_thinking?` predicate
+- `Runners::Messages#create_stream` — streaming message creation with SSE event yielding
+- `cache_system:` wraps system prompt in ephemeral cache_control block
+- `cache_scope: :global` auto-injects `prompt-caching-scope-2026-01-05` beta
+- `thinking:` for extended thinking with temperature auto-omission and beta auto-injection
+- `output_config:` for structured output (JSON schema), effort control, task budgets with auto-beta
+- `fast_mode: true` sends `speed: 'fast'` with `fast-mode-2026-02-01` beta
+- `context_management:` with `context-management-2025-06-27` beta auto-injection
+- `:usage` key in all `create` results with `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`
+- All new helpers wired into main `require 'legion/extensions/claude'` tree
+- Updated README with comprehensive examples for all new features
+
+### Changed
+- All runners raise typed `Helpers::Errors::*` exceptions instead of returning raw status codes
+- `Messages#create` and `#create_stream` refactored to use shared `build_message_body` and `resolve_feature_betas` helpers
+- `Messages#count_tokens` now accepts `thinking:`, `cache_system:` keywords
+- Added `rubocop-legion` for consistent linting
+
 ## [0.1.3] - 2026-03-30
 
 ### Changed

data/README.md

@@ -1,10 +1,10 @@
 # lex-claude
 
-Claude Anthropic API integration for LegionIO. Provides runners for creating messages, listing models, counting tokens, and managing message batches.
+Production-grade Claude Anthropic API integration for LegionIO. Provides runners for creating messages (streaming and batch), counting tokens, listing models, managing message batches, and accessing all modern Anthropic API features.
 
 ## Purpose
 
-Wraps the Anthropic Claude REST API as named runners consumable by any LegionIO task chain. Use this extension when you need direct access to the full Anthropic API surface (including async Batches) within the LEX runner/actor lifecycle. For simple chat/embed workflows, consider `legion-llm` instead.
+Wraps the Anthropic Claude REST API as named runners consumable by any LegionIO task chain. Supports streaming, prompt caching, extended thinking, structured output, web search, effort control, fast mode, and all beta API features. For simple chat/embed workflows, consider `legion-llm` instead.
 
 ## Installation
 
@@ -21,23 +21,27 @@ gem 'lex-claude'
 ## Functions
 
 ### Messages
-- `create` - Create a message (chat completion) with Claude
-- `count_tokens` - Count input tokens for a message request
+- `create` — Create a message (supports caching, thinking, tools, structured output)
+- `create_stream` — Streaming message creation with SSE event yielding
+- `count_tokens` — Count input tokens (supports tools, thinking, caching)
 
 ### Models
-- `list` - List available Claude models
-- `retrieve` - Get details for a specific model
+- `list` — List available Claude models
+- `retrieve` — Get details for a specific model
 
 ### Batches
-- `create_batch` - Create an asynchronous message batch
-- `list_batches` - List message batches
-- `retrieve_batch` - Get details for a specific batch
-- `cancel_batch` - Cancel an in-progress batch
-- `batch_results` - Retrieve results for a completed batch
+- `create_batch` — Create an asynchronous message batch
+- `list_batches` — List message batches
+- `retrieve_batch` — Get details for a specific batch
+- `cancel_batch` — Cancel an in-progress batch
+- `batch_results` — Retrieve results for a completed batch
 
-## Configuration
+### Helpers
+- `Helpers::Tools.web_search` — Build web search tool descriptor
+- `Helpers::Models.resolve` — Resolve model Symbol aliases to canonical IDs
+- `Helpers::Errors` — Structured exception hierarchy
 
-Set your API key in your LegionIO settings:
+## Configuration
 
 ```json
 {
@@ -47,47 +51,150 @@ Set your API key in your LegionIO settings:
 }
 ```
 
-## Standalone Usage
+## Usage
+
+### Basic message
 
 ```ruby
 require 'legion/extensions/claude/client'
 
 client = Legion::Extensions::Claude::Client.new(api_key: ENV['ANTHROPIC_API_KEY'])
 
-# Create a message
 result = client.create(
-  model: 'claude-opus-4-6',
-  messages: [{ role: 'user', content: 'Hello, Claude!' }],
+  model: 'claude-sonnet-4-6',
+  messages: [{ role: 'user', content: 'Hello!' }],
   max_tokens: 1024
 )
 puts result[:result]['content'].first['text']
+puts result[:usage].inspect
+```
+
+### Streaming
+
+```ruby
+client.create_stream(
+  model: 'claude-sonnet-4-6',
+  messages: [{ role: 'user', content: 'Tell me a story.' }],
+  max_tokens: 2048
+) do |event|
+  print event[:data].dig('delta', 'text') if event[:event] == 'content_block_delta'
+end
+```
 
-# List models
-models = client.list
-puts models[:result]['data'].map { |m| m['id'] }
+### Prompt caching
+
+```ruby
+result = client.create(
+  model: 'claude-sonnet-4-6',
+  messages: [{ role: 'user', content: 'Summarize this.' }],
+  system: 'You are a helpful assistant with deep context about...',
+  cache_system: true,
+  cache_scope: :global,
+  max_tokens: 512
+)
+puts result[:usage][:cache_read_tokens]
+```
 
-# Count tokens
-tokens = client.count_tokens(
+### Extended thinking
+
+```ruby
+result = client.create(
   model: 'claude-opus-4-6',
-  messages: [{ role: 'user', content: 'How many tokens is this?' }]
+  messages: [{ role: 'user', content: 'Solve this complex problem...' }],
+  thinking: { type: 'adaptive' },
+  max_tokens: 8192
+)
+```
+
+### Structured output
+
+```ruby
+result = client.create(
+  model: 'claude-sonnet-4-6',
+  messages: [{ role: 'user', content: 'Extract the name and age.' }],
+  max_tokens: 256,
+  output_config: {
+    format: {
+      type: 'json_schema',
+      json_schema: {
+        type: 'object',
+        properties: { name: { type: 'string' }, age: { type: 'integer' } },
+        required: %w[name age]
+      }
+    }
+  }
+)
+```
+
+### Web search
+
+```ruby
+web_tool = Legion::Extensions::Claude::Helpers::Tools.web_search(max_uses: 3)
+
+result = client.create(
+  model: 'claude-sonnet-4-6',
+  messages: [{ role: 'user', content: 'What happened in the news today?' }],
+  tools: [web_tool],
+  betas: [:web_search],
+  max_tokens: 1024
+)
+```
+
+### Effort control and fast mode
+
+```ruby
+result = client.create(
+  model: 'claude-sonnet-4-6',
+  messages: messages,
+  max_tokens: 2048,
+  output_config: { effort: 'high' }
 )
-puts tokens[:result]['input_tokens']
-
-# Create an async batch
-batch = client.create_batch(
-  requests: [
-    { custom_id: 'req-1', params: { model: 'claude-opus-4-6',
-                                    messages: [{ role: 'user', content: 'Hello' }],
-                                    max_tokens: 100 } }
-  ]
+
+result = client.create(
+  model: 'claude-sonnet-4-6',
+  messages: messages,
+  max_tokens: 512,
+  fast_mode: true
 )
-puts batch[:result]['id']
+```
+
+### Beta headers
+
+```ruby
+result = client.create(
+  model: 'claude-sonnet-4-6',
+  messages: messages,
+  max_tokens: 1024,
+  betas: [:token_efficient_tools, :advanced_tool_use]
+)
+```
+
+### Error handling
+
+```ruby
+begin
+  result = client.create(model: 'claude-sonnet-4-6', messages: messages, max_tokens: 512)
+rescue Legion::Extensions::Claude::Helpers::Errors::RateLimitError => e
+  puts "Rate limited (#{e.status}): #{e.message}"
+rescue Legion::Extensions::Claude::Helpers::Errors::AuthenticationError
+  puts 'Check your API key'
+rescue Legion::Extensions::Claude::Helpers::Errors::ApiError => e
+  puts "API error #{e.status}: #{e.message}"
+end
+```
+
+### Auto-retry
+
+```ruby
+result = Legion::Extensions::Claude::Helpers::Retry.with_retry(max_attempts: 3) do
+  client.create(model: 'claude-sonnet-4-6', messages: messages, max_tokens: 512)
+end
 ```
 
 ## Dependencies
 
-- `faraday` >= 2.0 - HTTP client
-- `multi_json` - JSON parser abstraction
+- `faraday` >= 2.0 — HTTP client
+- `multi_json` — JSON parser abstraction
 
 ## Requirements
 
@@ -97,8 +204,8 @@ puts batch[:result]['id']
 
 ## Related
 
-- `lex-bedrock` — Access Claude models via AWS Bedrock instead of Anthropic directly
-- `legion-llm` — High-level LLM interface including Anthropic via ruby_llm
+- `lex-bedrock` — Access Claude models via AWS Bedrock
+- `legion-llm` — High-level LLM interface
 - `extensions-ai/CLAUDE.md` — Architecture patterns shared across all AI extensions
 
 ## License

data/lib/legion/extensions/claude/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'legion/extensions/claude/helpers/client'
+require 'legion/extensions/claude/helpers/models'
 require 'legion/extensions/claude/runners/messages'
 require 'legion/extensions/claude/runners/models'
 require 'legion/extensions/claude/runners/batches'

data/lib/legion/extensions/claude/helpers/client.rb

@@ -9,19 +9,64 @@ module Legion
       module Helpers
         module Client
           DEFAULT_HOST = 'https://api.anthropic.com'
-          API_VERSION = '2023-06-01'
+          API_VERSION  = '2023-06-01'
+
+          BETA_HEADERS = {
+            interleaved_thinking:  'interleaved-thinking-2025-05-14',
+            context_1m:            'context-1m-2025-08-07',
+            context_management:    'context-management-2025-06-27',
+            structured_outputs:    'structured-outputs-2025-12-15',
+            web_search:            'web-search-2025-03-05',
+            advanced_tool_use:     'advanced-tool-use-2025-11-20',
+            effort:                'effort-2025-11-24',
+            task_budgets:          'task-budgets-2026-03-13',
+            prompt_caching_scope:  'prompt-caching-scope-2026-01-05',
+            fast_mode:             'fast-mode-2026-02-01',
+            redact_thinking:       'redact-thinking-2026-02-12',
+            token_efficient_tools: 'token-efficient-tools-2026-03-28',
+            summarize_connector:   'summarize-connector-text-2026-03-13',
+            afk_mode:              'afk-mode-2026-01-31',
+            advisor:               'advisor-tool-2026-03-01',
+            files_api:             'files-api-2025-04-14',
+            claude_code:           'claude-code-20250219',
+            tool_search:           'tool-search-tool-2025-10-19'
+          }.freeze
 
           module_function
 
-          def client(api_key:, host: DEFAULT_HOST, **_opts)
+          def client(api_key:, host: DEFAULT_HOST, betas: nil, **_opts)
+            beta_list = resolve_betas(betas)
+
             Faraday.new(url: host) do |conn|
               conn.request :json
               conn.response :json, content_type: /\bjson$/
               conn.headers['x-api-key'] = api_key
-              conn.headers['anthropic-version'] = API_VERSION
-              conn.headers['Content-Type'] = 'application/json'
+              conn.headers['anthropic-version']  = API_VERSION
+              conn.headers['Content-Type']       = 'application/json'
+              conn.headers['anthropic-beta']     = beta_list.join(',') if beta_list.any?
             end
           end
+
+          def streaming_client(api_key:, host: DEFAULT_HOST, betas: nil, **_opts)
+            beta_list = resolve_betas(betas)
+
+            Faraday.new(url: host) do |conn|
+              conn.headers['x-api-key'] = api_key
+              conn.headers['anthropic-version']  = API_VERSION
+              conn.headers['Content-Type']       = 'application/json'
+              conn.headers['Accept']             = 'text/event-stream'
+              conn.headers['anthropic-beta']     = beta_list.join(',') if beta_list.any?
+              conn.adapter Faraday.default_adapter
+            end
+          end
+
+          def resolve_betas(betas)
+            return [] if betas.nil? || betas.empty?
+
+            betas.filter_map do |b|
+              b.is_a?(Symbol) ? BETA_HEADERS[b] : b.to_s
+            end.uniq
+          end
         end
       end
     end

data/lib/legion/extensions/claude/helpers/errors.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Claude
+      module Helpers
+        module Errors
+          class ApiError < StandardError
+            attr_reader :status, :error_type, :body
+
+            def initialize(message = nil, status: nil, error_type: nil, body: nil)
+              super(message)
+              @status     = status
+              @error_type = error_type
+              @body       = body
+            end
+          end
+
+          class AuthenticationError  < ApiError; end
+          class PermissionError      < ApiError; end
+          class NotFoundError        < ApiError; end
+          class RateLimitError       < ApiError; end
+          class OverloadedError      < ApiError; end
+          class InvalidRequestError  < ApiError; end
+          class ServerError          < ApiError; end
+          class StreamingError       < ApiError; end
+
+          STATUS_MAP = {
+            401 => AuthenticationError,
+            403 => PermissionError,
+            404 => NotFoundError,
+            429 => RateLimitError,
+            529 => OverloadedError
+          }.freeze
+
+          TYPE_MAP = {
+            'authentication_error'  => AuthenticationError,
+            'permission_error'      => PermissionError,
+            'not_found_error'       => NotFoundError,
+            'rate_limit_error'      => RateLimitError,
+            'overloaded_error'      => OverloadedError,
+            'invalid_request_error' => InvalidRequestError,
+            'server_error'          => ServerError,
+            'streaming_error'       => StreamingError
+          }.freeze
+
+          RETRYABLE = [RateLimitError, OverloadedError].freeze
+
+          module_function
+
+          def from_response(status:, body:)
+            error_hash  = body.is_a?(Hash) ? (body[:error] || body['error']) : nil # rubocop:disable Legion/Framework/ApiStringKeys
+            error_type  = error_hash.is_a?(Hash) ? (error_hash[:type] || error_hash['type']) : nil
+            message     = error_hash.is_a?(Hash) ? (error_hash[:message] || error_hash['message']) : nil
+            message   ||= body.to_s
+
+            klass = TYPE_MAP[error_type] ||
+                    STATUS_MAP[status] ||
+                    (status >= 500 ? ServerError : InvalidRequestError)
+
+            klass.new(message, status: status, error_type: error_type, body: body)
+          end
+
+          def retryable?(error)
+            RETRYABLE.any? { |klass| error.is_a?(klass) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/claude/helpers/models.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Claude
+      module Helpers
+        module Models
+          # rubocop:disable Naming/VariableNumber
+          MODELS = {
+            haiku_3_5:  'claude-3-5-haiku-20241022',
+            haiku_4_5:  'claude-haiku-4-5-20251001',
+            sonnet_3_5: 'claude-3-5-sonnet-20241022',
+            sonnet_3_7: 'claude-3-7-sonnet-20250219',
+            sonnet_4:   'claude-sonnet-4-20250514',
+            sonnet_4_5: 'claude-sonnet-4-5-20250929',
+            sonnet_4_6: 'claude-sonnet-4-6',
+            opus_4:     'claude-opus-4-20250514',
+            opus_4_1:   'claude-opus-4-1-20250805',
+            opus_4_5:   'claude-opus-4-5-20251101',
+            opus_4_6:   'claude-opus-4-6'
+          }.freeze
+          # rubocop:enable Naming/VariableNumber
+
+          ADAPTIVE_THINKING_MODELS = %w[
+            claude-sonnet-4-20250514
+            claude-sonnet-4-5-20250929
+            claude-sonnet-4-6
+            claude-opus-4-20250514
+            claude-opus-4-1-20250805
+            claude-opus-4-5-20251101
+            claude-opus-4-6
+          ].freeze
+
+          module_function
+
+          def resolve(model)
+            key = model.is_a?(Symbol) ? model : model.to_s.to_sym
+            MODELS.fetch(key, model.to_s)
+          end
+
+          def adaptive_thinking?(model_id)
+            ADAPTIVE_THINKING_MODELS.include?(model_id.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/claude/helpers/response.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/claude/helpers/errors'
+
+module Legion
+  module Extensions
+    module Claude
+      module Helpers
+        module Response
+          RATE_LIMIT_HEADERS = {
+            'anthropic-ratelimit-unified-status'         => :status,
+            'anthropic-ratelimit-unified-reset'          => :reset,
+            'anthropic-ratelimit-unified-fallback'       => :fallback,
+            'anthropic-ratelimit-unified-5h-utilization' => :utilization_5h,
+            'anthropic-ratelimit-unified-5h-reset'       => :reset_5h,
+            'anthropic-ratelimit-unified-7d-utilization' => :utilization_7d,
+            'anthropic-ratelimit-unified-7d-reset'       => :reset_7d,
+            'anthropic-ratelimit-unified-overage-status' => :overage_status,
+            'anthropic-ratelimit-unified-overage-reset'  => :overage_reset
+          }.freeze
+
+          FLOAT_KEYS = %i[utilization_5h utilization_7d].freeze
+
+          module_function
+
+          def handle_response(response)
+            raise Errors.from_response(status: response.status, body: response.body) unless response.status >= 200 && response.status < 300
+
+            result = { result: response.body, status: response.status }
+            rate_info = parse_rate_limit_headers(response.headers)
+            result[:rate_limit] = rate_info unless rate_info.empty?
+            result
+          end
+
+          def parse_rate_limit_headers(headers)
+            return {} if headers.nil? || headers.empty?
+
+            parsed = {}
+            RATE_LIMIT_HEADERS.each do |header_name, key|
+              value = headers[header_name]
+              next if value.nil?
+
+              parsed[key] = FLOAT_KEYS.include?(key) ? value.to_f : value
+            end
+            parsed
+          end
+
+          def parse_usage(body)
+            usage = body.is_a?(Hash) ? (body[:usage] || body['usage'] || {}) : {} # rubocop:disable Legion/Framework/ApiStringKeys
+            {
+              input_tokens:       (usage[:input_tokens] || usage['input_tokens'] || 0).to_i,
+              output_tokens:      (usage[:output_tokens] || usage['output_tokens'] || 0).to_i,
+              cache_read_tokens:  (usage[:cache_read_input_tokens] || usage['cache_read_input_tokens'] || 0).to_i,
+              cache_write_tokens: (usage[:cache_creation_input_tokens] || usage['cache_creation_input_tokens'] || 0).to_i
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/claude/helpers/retry.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/claude/helpers/errors'
+
+module Legion
+  module Extensions
+    module Claude
+      module Helpers
+        module Retry
+          DEFAULT_MAX_ATTEMPTS = 3
+          DEFAULT_BASE_DELAY   = 1.0
+          DEFAULT_MAX_DELAY    = 60.0
+
+          module_function
+
+          def with_retry(max_attempts: DEFAULT_MAX_ATTEMPTS, base_delay: DEFAULT_BASE_DELAY,
+                         max_delay: DEFAULT_MAX_DELAY)
+            attempt = 0
+            begin
+              yield
+            rescue Errors::ApiError => e
+              raise unless Errors.retryable?(e)
+
+              attempt += 1
+              raise if attempt >= max_attempts
+
+              delay = backoff_seconds(attempt: attempt - 1, base_delay: base_delay, max_delay: max_delay)
+              sleep(delay) if delay.positive?
+              retry
+            end
+          end
+
+          def backoff_seconds(attempt:, base_delay: DEFAULT_BASE_DELAY, max_delay: DEFAULT_MAX_DELAY)
+            raw = base_delay * (2**attempt)
+            [raw, max_delay].min.to_f
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/claude/helpers/sse.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'multi_json'
+
+module Legion
+  module Extensions
+    module Claude
+      module Helpers
+        module Sse
+          module_function
+
+          def parse_stream(raw, include_pings: false)
+            events = []
+            current_event = nil
+
+            raw.each_line do |line|
+              line = line.chomp
+              if line.start_with?('event:')
+                current_event = line.sub(/^event:\s*/, '').strip
+              elsif line.start_with?('data:')
+                next if current_event == 'ping' && !include_pings
+
+                json_str = line.sub(/^data:\s*/, '').strip
+                next if json_str.empty?
+
+                begin
+                  data = MultiJson.load(json_str)
+                  events << { event: current_event, data: data }
+                rescue MultiJson::ParseError => e
+                  log.warn("SSE parse error: #{e.message}")
+                  next
+                end
+                current_event = nil
+              end
+            end
+
+            events
+          end
+
+          def collect_text(events)
+            events
+              .select { |e| e[:event] == 'content_block_delta' && e[:data].dig('delta', 'type') == 'text_delta' }
+              .map { |e| e[:data].dig('delta', 'text').to_s }
+              .join
+          end
+
+          def collect_usage(events)
+            input_tokens  = 0
+            output_tokens = 0
+
+            events.each do |e|
+              case e[:event]
+              when 'message_start'
+                usage = e[:data].dig('message', 'usage') || {}
+                input_tokens  += usage.fetch('input_tokens', 0).to_i
+                output_tokens += usage.fetch('output_tokens', 0).to_i
+              when 'message_delta'
+                usage = e[:data].fetch('usage', {})
+                output_tokens += usage.fetch('output_tokens', 0).to_i
+              end
+            end
+
+            { input_tokens: input_tokens, output_tokens: output_tokens }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/claude/helpers/tools.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Claude
+      module Helpers
+        module Tools
+          module_function
+
+          def web_search(max_uses: 5, allowed_domains: nil, blocked_domains: nil)
+            tool = { type: 'web_search_20250305', max_uses: max_uses }
+            tool[:allowed_domains] = allowed_domains if allowed_domains
+            tool[:blocked_domains] = blocked_domains if blocked_domains
+            tool
+          end
+
+          def cache_control
+            { type: 'ephemeral' }
+          end
+
+          def required_betas_for(tools)
+            return [] if tools.nil? || tools.empty?
+
+            betas = []
+            betas << :web_search if tools.any? { |t| t.is_a?(Hash) && t[:type].to_s.start_with?('web_search') }
+            betas
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/claude/runners/batches.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'legion/extensions/claude/helpers/client'
+require 'legion/extensions/claude/helpers/response'
 
 module Legion
   module Extensions
@@ -12,7 +13,7 @@ module Legion
           def create_batch(api_key:, requests:, **)
             body = { requests: requests }
             response = client(api_key: api_key, **).post('/v1/messages/batches', body)
-            { result: response.body, status: response.status }
+            Helpers::Response.handle_response(response)
           end
 
           def list_batches(api_key:, limit: 20, before_id: nil, after_id: nil, **)
@@ -21,22 +22,22 @@ module Legion
             params[:after_id] = after_id if after_id
 
             response = client(api_key: api_key, **).get('/v1/messages/batches', params)
-            { result: response.body, status: response.status }
+            Helpers::Response.handle_response(response)
           end
 
           def retrieve_batch(api_key:, batch_id:, **)
             response = client(api_key: api_key, **).get("/v1/messages/batches/#{batch_id}")
-            { result: response.body, status: response.status }
+            Helpers::Response.handle_response(response)
           end
 
           def cancel_batch(api_key:, batch_id:, **)
             response = client(api_key: api_key, **).post("/v1/messages/batches/#{batch_id}/cancel")
-            { result: response.body, status: response.status }
+            Helpers::Response.handle_response(response)
           end
 
           def batch_results(api_key:, batch_id:, **)
             response = client(api_key: api_key, **).get("/v1/messages/batches/#{batch_id}/results")
-            { result: response.body, status: response.status }
+            Helpers::Response.handle_response(response)
           end
 
           include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&

data/lib/legion/extensions/claude/runners/messages.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'legion/extensions/claude/helpers/client'
+require 'legion/extensions/claude/helpers/response'
+require 'legion/extensions/claude/helpers/sse'
 
 module Legion
   module Extensions
@@ -9,35 +11,105 @@ module Legion
         module Messages
           extend Legion::Extensions::Claude::Helpers::Client
 
-          def create(api_key:, model:, messages:, max_tokens: 1024, system: nil, temperature: nil, # rubocop:disable Metrics/ParameterLists
-                     top_p: nil, top_k: nil, stop_sequences: nil, metadata: nil, tools: nil,
-                     tool_choice: nil, stream: false, **)
-            body = {
-              model:      model,
-              messages:   messages,
-              max_tokens: max_tokens,
-              stream:     stream
+          def create(api_key:, model:, messages:, max_tokens: 1024, stream: false, betas: nil, **opts)
+            body = build_message_body(model: model, messages: messages, max_tokens: max_tokens, stream: stream, **opts)
+            resolved_betas = resolve_feature_betas(betas, opts)
+
+            response = client(api_key: api_key, betas: resolved_betas, **opts).post('/v1/messages', body)
+            result = Helpers::Response.handle_response(response)
+            result[:usage] = Helpers::Response.parse_usage(response.body) if response.body.is_a?(Hash)
+            result
+          end
+
+          def create_stream(api_key:, model:, messages:, max_tokens: 1024, betas: nil, **opts, &block)
+            body = build_message_body(model: model, messages: messages, max_tokens: max_tokens, stream: true, **opts)
+            resolved_betas = resolve_feature_betas(betas, opts)
+
+            raw_body = +''
+            conn = Helpers::Client.streaming_client(api_key: api_key, betas: resolved_betas)
+            response = conn.post('/v1/messages', MultiJson.dump(body)) do |req|
+              req.options.on_data = proc { |chunk, _bytes| raw_body << chunk }
+            end
+
+            raise Helpers::Errors.from_response(status: response.status, body: {}) unless response.status == 200
+
+            raw_body = response.body if raw_body.empty? && response.body.is_a?(String)
+
+            events = Helpers::Sse.parse_stream(raw_body)
+            events.each(&block) if block
+
+            {
+              result: Helpers::Sse.collect_text(events),
+              events: events,
+              usage:  Helpers::Sse.collect_usage(events),
+              status: 200
             }
-            body[:system] = system if system
-            body[:temperature] = temperature if temperature
-            body[:top_p] = top_p if top_p
-            body[:top_k] = top_k if top_k
-            body[:stop_sequences] = stop_sequences if stop_sequences
-            body[:metadata] = metadata if metadata
-            body[:tools] = tools if tools
-            body[:tool_choice] = tool_choice if tool_choice
-
-            response = client(api_key: api_key, **).post('/v1/messages', body)
-            { result: response.body, status: response.status }
           end
 
-          def count_tokens(api_key:, model:, messages:, system: nil, tools: nil, **)
+          def count_tokens(api_key:, model:, messages:, betas: nil, **opts)
+            system       = opts[:system]
+            tools        = opts[:tools]
+            thinking     = opts[:thinking]
+            cache_system = opts.fetch(:cache_system, false)
+
             body = { model: model, messages: messages }
-            body[:system] = system if system
-            body[:tools] = tools if tools
+            body[:system]   = build_system(system, cache_system) if system
+            body[:tools]    = tools    if tools
+            body[:thinking] = thinking if thinking
+
+            resolved_betas = Array(betas).dup
+            resolved_betas << :interleaved_thinking if thinking && !resolved_betas.include?(:interleaved_thinking)
+
+            response = client(api_key: api_key, betas: resolved_betas).post('/v1/messages/count_tokens', body)
+            Helpers::Response.handle_response(response)
+          end
+
+          private
+
+          def build_message_body(model:, messages:, max_tokens:, stream:, system: nil, temperature: nil, # rubocop:disable Metrics/ParameterLists
+                                 top_p: nil, top_k: nil, stop_sequences: nil, metadata: nil, tools: nil,
+                                 tool_choice: nil, cache_system: false, thinking: nil, output_config: nil,
+                                 fast_mode: false, context_management: nil, **)
+            body = { model: model, messages: messages, max_tokens: max_tokens, stream: stream }
+
+            body[:system]             = build_system(system, cache_system) if system
+            body[:top_p]              = top_p              if top_p
+            body[:top_k]              = top_k              if top_k
+            body[:stop_sequences]     = stop_sequences     if stop_sequences
+            body[:metadata]           = metadata           if metadata
+            body[:tools]              = tools              if tools
+            body[:tool_choice]        = tool_choice        if tool_choice
+            body[:output_config]      = output_config      if output_config
+            body[:speed]              = 'fast'             if fast_mode
+            body[:context_management] = context_management if context_management
+
+            if thinking
+              body[:thinking] = thinking
+            elsif temperature
+              body[:temperature] = temperature
+            end
+
+            body
+          end
+
+          def resolve_feature_betas(betas, opts)
+            resolved = Array(betas).dup
+            resolved << :prompt_caching_scope  if opts[:cache_scope] == :global
+            resolved << :interleaved_thinking  if opts[:thinking] && !resolved.include?(:interleaved_thinking)
+            resolved << :structured_outputs    if opts[:output_config]&.key?(:format)
+            resolved << :effort                if opts[:output_config]&.key?(:effort)
+            resolved << :task_budgets          if opts[:output_config]&.key?(:task_budget)
+            resolved << :fast_mode             if opts[:fast_mode]
+            resolved << :context_management    if opts[:context_management]
+            resolved
+          end
 
-            response = client(api_key: api_key, **).post('/v1/messages/count_tokens', body)
-            { result: response.body, status: response.status }
+          def build_system(system, cache_system)
+            if cache_system
+              [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }]
+            else
+              system
+            end
           end
 
           include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&

data/lib/legion/extensions/claude/runners/models.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'legion/extensions/claude/helpers/client'
+require 'legion/extensions/claude/helpers/response'
 
 module Legion
   module Extensions
@@ -15,12 +16,12 @@ module Legion
             params[:after_id] = after_id if after_id
 
             response = client(api_key: api_key, **).get('/v1/models', params)
-            { result: response.body, status: response.status }
+            Helpers::Response.handle_response(response)
           end
 
           def retrieve(api_key:, model_id:, **)
             response = client(api_key: api_key, **).get("/v1/models/#{model_id}")
-            { result: response.body, status: response.status }
+            Helpers::Response.handle_response(response)
           end
 
           include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Claude
-      VERSION = '0.1.3'
+      VERSION = '0.3.0'
     end
   end
 end

data/lib/legion/extensions/claude.rb

@@ -2,6 +2,12 @@
 
 require 'legion/extensions/claude/version'
 require 'legion/extensions/claude/helpers/client'
+require 'legion/extensions/claude/helpers/errors'
+require 'legion/extensions/claude/helpers/retry'
+require 'legion/extensions/claude/helpers/sse'
+require 'legion/extensions/claude/helpers/response'
+require 'legion/extensions/claude/helpers/tools'
+require 'legion/extensions/claude/helpers/models'
 require 'legion/extensions/claude/runners/messages'
 require 'legion/extensions/claude/runners/models'
 require 'legion/extensions/claude/runners/batches'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-claude
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Esity
@@ -158,6 +158,12 @@ files:
 - lib/legion/extensions/claude.rb
 - lib/legion/extensions/claude/client.rb
 - lib/legion/extensions/claude/helpers/client.rb
+- lib/legion/extensions/claude/helpers/errors.rb
+- lib/legion/extensions/claude/helpers/models.rb
+- lib/legion/extensions/claude/helpers/response.rb
+- lib/legion/extensions/claude/helpers/retry.rb
+- lib/legion/extensions/claude/helpers/sse.rb
+- lib/legion/extensions/claude/helpers/tools.rb
 - lib/legion/extensions/claude/runners/batches.rb
 - lib/legion/extensions/claude/runners/messages.rb
 - lib/legion/extensions/claude/runners/models.rb