lex-claude 0.1.2 → 0.3.0

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,26 +22,26 @@ 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) &&
-                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex, false)
         end
       end
     end

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,39 +11,109 @@ 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, **) # rubocop:disable Metrics/ParameterLists
+          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) &&
-                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex, false)
         end
       end
     end

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,16 +16,16 @@ 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) &&
-                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex, false)
         end
       end
     end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Claude
-      VERSION = '0.1.2'
+      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'
@@ -9,7 +15,7 @@ require 'legion/extensions/claude/runners/batches'
 module Legion
   module Extensions
     module Claude
-      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core, false
     end
   end
 end