exa-ai-ruby 1.1.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db2209bdedef9b83244089dc9741f0f5efb80c97b6dcb5a35d84bdbfa5a75578
-  data.tar.gz: 44d3a68b788de10a8515524efb56c5cad08e3ab0a5f9278f4d0c32a55471100c
+  metadata.gz: 79ae8c332333d78a85777c6661ee49c1d413048025d03258c22647287bd445fb
+  data.tar.gz: 938adda9c303fc20ec216c2ac70d4e0dde78934e7ec6ab4c3f1318900fcabeff
 SHA512:
-  metadata.gz: dc728d52cb343576e48632e765864e47f5b800662d15cc9748e2c438e9b0f93c1b71bb1f884075337117fcfa755d4d3fca702c42093157783877bf0adf5d3677
-  data.tar.gz: 938036e4dd8429695ec519870cd3edb121c4b113c3127f557a790a02246f71a51335802f963330f7a83360236b9931dee8adc3c8c9724eb40bb11a49de4008dc
+  metadata.gz: 73a0621ead908309d13d516d74e5e720e8a01e5f09b9c4ee3f940a7af5fa090cbb40810f0273bd9208190f395371675168f005f50c24430c0c29b805a4dfdb40
+  data.tar.gz: a19fef60b65061fb8c450aa4c30dffb2e23dac495b6ef1db4c09a7a6c3f9fe489710cce167bc16279439e1853274b6cc3d4431127b9fef414dc677b29089762b

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.2.0] - 2025-10-31
+- Add `Exa::Internal::Transport::AsyncRequester`, enabling optional fiber-scheduler-friendly HTTP via the `async` ecosystem.
+- Document async usage in the README with Gemfile requirements and concurrent request example.
+- Cover the new requester with Minitest specs and wire optional development/test dependencies so contributors can run the async suite locally.
+
+## [1.1.3] - 2025-10-30
+- Extend compatibility down to Ruby 3.0.x by lowering the minimum required Ruby version.
+
 ## [1.1.2] - 2025-10-27
 - Broaden support to Ruby 3.1+ by relaxing the gem's minimum Ruby requirement.
 

data/README.md

@@ -69,6 +69,37 @@ Runtime dependencies:
 - `connection_pool` – `Net::HTTP` pooling in `PooledNetRequester`.
 - `dspy-schema` – converts Sorbet types to JSON Schema (structured output support).
 
+### Optional: Async transports
+
+To integrate with Ruby’s `async` scheduler, add the optional dependencies and inject the provided requester:
+
+```ruby
+# Gemfile
+gem "async", "~> 2.6"
+gem "async-http", "~> 0.92"
+```
+
+```ruby
+require "async"
+require "exa/internal/transport/async_requester"
+require "exa"
+
+Async do
+  requester = Exa::Internal::Transport::AsyncRequester.new
+  client = Exa::Client.new(api_key: ENV.fetch("EXA_API_KEY"), requester: requester)
+
+  search_task = Async { client.search.search(query: "autonomous robotics", num_results: 3) }
+  research_task = Async { client.research.create(instructions: "Track major AI policy updates.") }
+
+  puts search_task.wait.results.first.title
+  puts research_task.wait.id
+ensure
+  requester.close
+end
+```
+
+The async requester preserves the same typed resources and streaming helpers, so switching between synchronous and asynchronous transports is a single constructor change.
+
 Set the API key via `EXA_API_KEY` or pass `api_key:` when instantiating `Exa::Client`.
 
 If you are building automation that calls this README (e.g., using `curl`/`wget` or a retrieval plug‑in), fetch the raw file from GitHub: `https://raw.githubusercontent.com/vicentereig/exa-ruby/main/README.md`.

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+begin
+  require "async"
+  require "async/http/internet"
+rescue LoadError => e
+  raise LoadError, "Install the `async` and `async-http` gems to use AsyncRequester (caused by #{e.message})"
+end
+
+require "exa/errors"
+require_relative "../util"
+
+module Exa
+  module Internal
+    module Transport
+      class AsyncRequester
+        # Wraps an Async::HTTP::Response to mimic Net::HTTP's header API.
+        class ResponseAdapter
+          def initialize(response)
+            @response = response
+          end
+
+          def each_header
+            return enum_for(__method__) unless block_given?
+            @response.headers.each do |key, value|
+              Array(value).each { |v| yield(key, v) }
+            end
+          end
+
+          def [](key)
+            value = @response.headers[key]
+            value.is_a?(Array) ? value.first : value
+          end
+
+          def finish
+            @response.finish
+          end
+        end
+
+        attr_reader :internet
+
+        def initialize(internet: nil)
+          @internet = internet || Async::HTTP::Internet.new
+        end
+
+        def execute(request)
+          task = Async::Task.current?
+          unless task
+            raise Exa::Errors::ConfigurationError,
+              "AsyncRequester must run inside an Async scheduler (wrap calls in `Async do ... end`)."
+          end
+
+          deadline = request.fetch(:deadline)
+          response = with_timeout(deadline, request[:url]) do
+            internet.call(
+              request.fetch(:method).to_s.upcase,
+              request.fetch(:url).to_s,
+              request.fetch(:headers),
+              request[:body]
+            )
+          end
+
+          adapter = ResponseAdapter.new(response)
+
+          body_enum = build_body_enum(response: response, deadline: deadline, url: request.fetch(:url).to_s)
+
+          [Integer(response.status), adapter, body_enum]
+        rescue Async::TimeoutError
+          raise Exa::Errors::APITimeoutError.new("Request timed out", url: request[:url])
+        rescue Exa::Errors::APIError, Exa::Errors::ConfigurationError
+          raise
+        rescue StandardError => e
+          raise Exa::Errors::APIConnectionError.new(e.message, url: request[:url])
+        end
+
+        def close
+          internet.close
+        end
+
+        private
+
+        def build_body_enum(response:, deadline:, url:)
+          body = response.body
+          Exa::Internal::Util.fused_enum(
+            Enumerator.new do |y|
+              begin
+                loop do
+                  chunk = read_chunk(body: body, deadline: deadline, url: url)
+                  break if chunk.nil?
+                  y << chunk
+                end
+              ensure
+                response.finish
+              end
+            end
+          ) { response.finish }
+        end
+
+        def read_chunk(body:, deadline:, url:)
+          remaining = remaining(deadline)
+          return nil if remaining <= 0
+
+          Async::Task.current.with_timeout(remaining) do
+            body.read
+          end
+        rescue Async::TimeoutError
+          raise Exa::Errors::APITimeoutError.new("Request timed out", url: url)
+        end
+
+        def with_timeout(deadline, url)
+          remaining = remaining(deadline)
+          raise Exa::Errors::APITimeoutError.new("Request timed out", url: url) if remaining <= 0
+
+          Async::Task.current.with_timeout(remaining) { yield }
+        end
+
+        def remaining(deadline)
+          deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/exa/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exa-ai-ruby
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Vicente Reig Rincon de Arellano
@@ -44,6 +44,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -51,6 +54,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.1
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -197,6 +203,7 @@ files:
 - lib/exa/cli/root.rb
 - lib/exa/client.rb
 - lib/exa/errors.rb
+- lib/exa/internal/transport/async_requester.rb
 - lib/exa/internal/transport/base_client.rb
 - lib/exa/internal/transport/pooled_net_requester.rb
 - lib/exa/internal/transport/stream.rb
@@ -249,7 +256,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="