exa-ai-ruby 1.0.0 → 1.1.0

data/lib/exa/cli.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "cli/config_store"
+require_relative "cli/account_resolver"
+require_relative "cli/root"

data/lib/exa/internal/transport/base_client.rb

@@ -44,16 +44,19 @@ module Exa
           @requester = requester
         end
 
-        def request(method:, path:, query: nil, headers: nil, body: nil, unwrap: nil, stream: false, response_model: nil)
+        def request(method:, path:, query: nil, headers: nil, body: nil, unwrap: nil, stream: false, response_model: nil, request_options: nil)
+          options = normalize_request_options(request_options)
           req = build_request(
             method: method,
             path: Array(path).join("/"),
             query: query,
             headers: headers,
-            body: body
+            body: body,
+            request_timeout: options[:timeout],
+            idempotency_key: options[:idempotency_key]
           )
 
-          _, response, stream_enum = send_request(req)
+          _, response, stream_enum = send_request(req, max_retries: options[:max_retries] || max_retries)
           parsed_headers = Exa::Internal::Util.normalized_headers(response.each_header.to_h)
 
           if stream
@@ -77,13 +80,14 @@ module Exa
           cleaned.join("/")
         end
 
-        def build_request(method:, path:, query:, headers:, body:)
+        def build_request(method:, path:, query:, headers:, body:, request_timeout:, idempotency_key:)
           normalized_path = normalize_path(path)
           url = @base_url + normalized_path
           url.query = Exa::Internal::Util.build_query(query)
 
           header_overrides = headers ? headers.each_with_object({}) { |(k, v), acc| acc[k] = v unless v.nil? } : {}
           final_headers = PLATFORM_HEADERS.merge(default_headers).merge(header_overrides)
+          final_headers["idempotency-key"] ||= idempotency_key if idempotency_key
 
           payload = case body
                     when nil
@@ -96,12 +100,14 @@ module Exa
                       JSON.generate(body)
                     end
 
+          effective_timeout = request_timeout || timeout
+
           {
             method: method,
             url: url,
             headers: final_headers,
             body: payload,
-            deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout,
+            deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + effective_timeout,
             max_retries: max_retries
           }
         end
@@ -118,11 +124,11 @@ module Exa
           {}
         end
 
-        def send_request(request, retry_count: 0)
+        def send_request(request, retry_count: 0, max_retries: @max_retries)
           status, response, body_enum = @requester.execute(request)
           if should_retry?(status) && retry_count < max_retries
-            sleep(retry_delay(retry_count))
-            return send_request(request, retry_count: retry_count + 1)
+            sleep(retry_delay(retry_count, response))
+            return send_request(request, retry_count: retry_count + 1, max_retries: max_retries)
           end
 
           if status >= 400
@@ -149,11 +155,36 @@ module Exa
           [408, 409, 429].include?(status) || status >= 500
         end
 
-        def retry_delay(retry_count)
+        def retry_delay(retry_count, response = nil)
+          header_delay = retry_after_delay(response)
+          return header_delay if header_delay
+
           delay = initial_retry_delay * (2**retry_count)
           [delay, max_retry_delay].min
         end
 
+        def retry_after_delay(response)
+          return nil unless response
+          value = nil
+          if response.respond_to?(:[])
+            value = response["Retry-After"] || response["retry-after"]
+          end
+          unless value
+            if response.respond_to?(:each_header)
+              response.each_header do |k, v|
+                if k.downcase == "retry-after"
+                  value = v
+                  break
+                end
+              end
+            end
+          end
+          return nil unless value
+          parsed = Integer(value) rescue Float(value) rescue nil
+          return nil unless parsed
+          [parsed.to_f, max_retry_delay].min
+        end
+
         def dig(obj, path)
           Array(path).reduce(obj) do |memo, key|
             memo.is_a?(Hash) ? memo[key] : nil
@@ -165,6 +196,15 @@ module Exa
           return model.from_hash(data) if model.respond_to?(:from_hash)
           model.new(data)
         end
+
+        def normalize_request_options(options)
+          return {} if options.nil?
+          opts = {}
+          opts[:timeout] = options[:timeout] if options[:timeout]
+          opts[:max_retries] = options[:max_retries] if options[:max_retries]
+          opts[:idempotency_key] = options[:idempotency_key] if options[:idempotency_key]
+          opts
+        end
       end
     end
   end

data/lib/exa/internal/transport/pooled_net_requester.rb

@@ -47,7 +47,16 @@ module Exa
             end
 
             _, response = enum.next
-            body = Exa::Internal::Util.fused_enum(enum)
+            body_stream = Enumerator.new do |y|
+              loop do
+                begin
+                  y << enum.next
+                rescue StopIteration
+                  break
+                end
+              end
+            end
+            body = Exa::Internal::Util.fused_enum(body_stream)
             [Integer(response.code), response, body]
           end
         end

data/lib/exa/resources/search.rb

@@ -21,9 +21,16 @@ module Exa
       end
 
       def answer(params)
+        stream = stream_requested?(params)
         normalized = normalize_nested_struct(params, :search_options, Exa::Types::AnswerSearchOptions)
         payload = serialize(Exa::Types::AnswerRequest, normalized)
-        client.request(method: :post, path: "answer", body: payload)
+        client.request(
+          method: :post,
+          path: "answer",
+          body: payload,
+          stream: stream,
+          response_model: stream ? nil : Exa::Responses::AnswerResponse
+        )
       end
 
       private
@@ -39,6 +46,19 @@ module Exa
         merged.delete(key.to_s)
         merged
       end
+
+      def stream_requested?(params)
+        case params
+        when Hash
+          value = params[:stream]
+          value = params["stream"] if value.nil?
+          !!value
+        when Exa::Types::AnswerRequest
+          !!params.stream
+        else
+          false
+        end
+      end
     end
   end
 end

data/lib/exa/resources/websets.rb

@@ -61,6 +61,23 @@ module Exa
         )
       end
 
+      def cancel(webset_id)
+        client.request(
+          method: :post,
+          path: websets_path(webset_id, "cancel"),
+          response_model: Exa::Responses::Webset
+        )
+      end
+
+      def preview(params)
+        client.request(
+          method: :post,
+          path: ["v0", "websets", "preview"],
+          body: params,
+          response_model: Exa::Responses::Webset
+        )
+      end
+
       private
 
       def websets_path(*parts)

data/lib/exa/responses/answer_response.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Exa
+  module Responses
+    class AnswerCitation < T::Struct
+      const :id, T.nilable(String)
+      const :url, T.nilable(String)
+      const :title, T.nilable(String)
+      const :author, T.nilable(String)
+      const :published_date, T.nilable(String)
+      const :text, T.nilable(String)
+      const :image, T.nilable(String)
+      const :favicon, T.nilable(String)
+
+      def self.from_hash(hash)
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          id: sym[:id],
+          url: sym[:url],
+          title: sym[:title],
+          author: sym[:author],
+          published_date: sym[:publishedDate],
+          text: sym[:text],
+          image: sym[:image],
+          favicon: sym[:favicon]
+        )
+      end
+    end
+
+    class CostBreakdown < T::Struct
+      const :search, T.nilable(Float)
+      const :contents, T.nilable(Float)
+      const :breakdown, T.nilable(T::Hash[Symbol, T.nilable(Float)])
+
+      def self.from_hash(hash)
+        return nil unless hash
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          search: sym[:search]&.to_f,
+          contents: sym[:contents]&.to_f,
+          breakdown: sym[:breakdown]&.transform_keys(&:to_sym)
+        )
+      end
+    end
+
+    class CostDollars < T::Struct
+      const :total, T.nilable(Float)
+      const :break_down, T.nilable(T::Array[CostBreakdown])
+      const :per_request_prices, T.nilable(T::Hash[Symbol, T.untyped])
+
+      def self.from_hash(hash)
+        return nil unless hash
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          total: sym[:total]&.to_f,
+          break_down: sym[:breakDown]&.map { CostBreakdown.from_hash(_1) },
+          per_request_prices: sym[:perRequestPrices]&.transform_keys(&:to_sym)
+        )
+      end
+    end
+
+    class AnswerResponse < T::Struct
+      const :answer, T.nilable(String)
+      const :citations, T::Array[AnswerCitation]
+      const :cost_dollars, T.nilable(CostDollars)
+
+      def self.from_hash(hash)
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          answer: sym[:answer],
+          citations: Array(sym[:citations]).map { AnswerCitation.from_hash(_1) },
+          cost_dollars: CostDollars.from_hash(sym[:costDollars])
+        )
+      end
+    end
+  end
+end

data/lib/exa/responses/search_response.rb

@@ -8,7 +8,7 @@ module Exa
       const :search_type, T.nilable(String)
       const :results, T::Array[ResultWithContent]
       const :context, T.nilable(String)
-      const :cost_dollars, T.nilable(Float)
+      const :cost_dollars, T.nilable(T.any(Float, T::Hash[Symbol, T.untyped]))
 
       def self.from_hash(hash)
         sym = Helpers.symbolize_keys(hash)
@@ -18,9 +18,22 @@ module Exa
           search_type: sym[:searchType],
           results: Array(sym[:results]).map { ResultWithContent.from_hash(_1) },
           context: sym[:context],
-          cost_dollars: sym[:costDollars]&.to_f
+          cost_dollars: normalize_cost(sym[:costDollars])
         )
       end
+
+      def self.normalize_cost(value)
+        case value
+        when nil
+          nil
+        when Numeric
+          value.to_f
+        when Hash
+          Exa::Responses::Helpers.symbolize_keys(value)
+        else
+          value
+        end
+      end
     end
 
     class FindSimilarResponse < T::Struct

data/lib/exa/responses.rb

@@ -10,4 +10,5 @@ require_relative "responses/webhook_response"
 require_relative "responses/import_response"
 require_relative "responses/webset_response"
 require_relative "responses/research_response"
+require_relative "responses/answer_response"
 require_relative "responses/raw_response"

data/lib/exa/types/answer.rb

@@ -17,6 +17,7 @@ module Exa
       const :query, String
       const :summary, T.nilable(AnswerSummaryOptions)
       const :search_options, T.nilable(AnswerSearchOptions)
+      const :stream, T.nilable(T::Boolean)
 
       def to_payload
         payload = Serializer.to_payload(self)

data/lib/exa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Exa
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exa-ai-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Vicente Reig Rincon de Arellano
@@ -51,6 +51,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: tty-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -93,17 +135,65 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.64'
+- !ruby/object:Gem::Dependency
+  name: aruba
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
 description: Exa API client in Ruby, Sorbet-friendly and inspired by openai-ruby.
 email:
 - hey@vicente.services
-executables: []
+executables:
+- exa
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- exe/exa
 - lib/exa.rb
+- lib/exa/cli.rb
+- lib/exa/cli/account_resolver.rb
+- lib/exa/cli/config_store.rb
+- lib/exa/cli/root.rb
 - lib/exa/client.rb
 - lib/exa/errors.rb
 - lib/exa/internal/transport/base_client.rb
@@ -122,6 +212,7 @@ files:
 - lib/exa/resources/websets/items.rb
 - lib/exa/resources/websets/monitors.rb
 - lib/exa/responses.rb
+- lib/exa/responses/answer_response.rb
 - lib/exa/responses/contents_response.rb
 - lib/exa/responses/event_response.rb
 - lib/exa/responses/helpers.rb