exa-ai-ruby 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66972bcd1f042b148cd8dc5f004dad3fa38d0a2f242ba8727ded974866cb502c
-  data.tar.gz: d4cc2dada13aa407b22fbb168cc9683b8018c8ae3b75f386c5fe7f85bc624a1c
+  metadata.gz: bc02adeea0f6941eca67efd47e5cfb78dbaa07bf59acfaf441f5e63fe86839ce
+  data.tar.gz: cc85d78c4754424b3755857e81528f7eb537754f79a3a1cd789613cce28adce4
 SHA512:
-  metadata.gz: 9ded95dff3837d3c2e827468bdca4d300d802ac318357d0b1b4ced3946a0578ec4c9eb4d97daeb5cf0f4cf3fe1199444a6f95b02caf5ae6aa6a9d512f5773d7f
-  data.tar.gz: cc208c8492d43dc2a48d9072e5d402d24de5fee3945e5db60dcc761755332c54168d3dc77a3eda3b22e39af937ee20df57e932d308116e746f76835ca4419b3f
+  metadata.gz: 1d929f07c2b3e235d5beacbeb68fee05f0b39217c925a4d92866552daa8e15f985ff3ad30e1c788c12ac1c1f12595b49e9f093d156b2524954216170f4b537e4
+  data.tar.gz: ebd90c1384c99d842895721a0025451df8689872e961f20e8f8e5022e4e457687b9a2dac72238b2a7506d300ea06dc5442d0ceef8df2bd6267a944c83a0308a0

data/README.md

@@ -23,7 +23,8 @@ This README is intentionally exhaustive—LLM agents and humans alike should be
    - [Events, Imports, Webhooks](#events-imports-webhooks)
 6. [Structured Output via Sorbet + dspy-schema](#structured-output-via-sorbet--dspy-schema)
 7. [Streaming & Transport Helpers](#streaming--transport-helpers)
-8. [Testing & TDD Plan](#testing--tdd-plan)
+8. [Instrumentation & Cost Tracking](#instrumentation--cost-tracking)
+9. [Testing & TDD Plan](#testing--tdd-plan)
 
 ---
 
@@ -367,6 +368,150 @@ See `test/transport/stream_test.rb` for examples.
 
 ---
 
+## Instrumentation & Cost Tracking
+
+The gem includes a built-in instrumentation system for tracking API usage and costs. Events are emitted around every API request, and you can subscribe to them for logging, monitoring, or cost management.
+
+### Basic Cost Tracking
+
+```ruby
+require "exa"
+
+client = Exa::Client.new(api_key: ENV.fetch("EXA_API_KEY"))
+
+# Create and subscribe a cost tracker
+tracker = Exa::Instrumentation::CostTracker.new
+tracker.subscribe
+
+# Make API calls - costs are tracked automatically
+response = client.search.search(query: "AI papers", num_results: 10)
+puts response.cost_dollars&.total  # => 0.005
+
+client.search.contents(urls: ["https://example.com"], text: true)
+
+# Check accumulated costs
+puts tracker.total_cost     # => 0.006
+puts tracker.request_count  # => 2
+puts tracker.average_cost   # => 0.003
+
+# Get breakdown by endpoint
+tracker.summary.each do |endpoint, cost|
+  puts "#{endpoint.serialize}: $#{cost}"
+end
+# => search: $0.005
+# => contents: $0.001
+
+# Print a formatted report
+puts tracker.report
+
+# Reset tracking
+tracker.reset!
+
+# Unsubscribe when done
+tracker.unsubscribe
+```
+
+### Custom Event Subscribers
+
+Subscribe to specific events using wildcard patterns:
+
+```ruby
+# Subscribe to all request events
+Exa.instrumentation.subscribe("exa.request.*") do |event_name, payload|
+  case event_name
+  when "exa.request.start"
+    puts "Starting #{payload.endpoint.serialize} request..."
+  when "exa.request.complete"
+    puts "Completed in #{payload.duration_ms.round(2)}ms, cost: $#{payload.cost_dollars}"
+  when "exa.request.error"
+    puts "Error: #{payload.error_class} - #{payload.error_message}"
+  end
+end
+
+# Subscribe to specific events
+Exa.instrumentation.subscribe("exa.request.error") do |_name, payload|
+  ErrorTracker.notify(payload.error_class, payload.error_message)
+end
+```
+
+### Building Custom Subscribers
+
+Extend `BaseSubscriber` for reusable instrumentation:
+
+```ruby
+class BudgetGuard < Exa::Instrumentation::BaseSubscriber
+  def initialize(budget_limit)
+    @budget = budget_limit
+    @spent = 0.0
+    @mutex = Mutex.new
+    super()
+  end
+
+  def subscribe
+    add_subscription("exa.request.complete") do |_name, payload|
+      next unless payload.cost_dollars
+
+      @mutex.synchronize do
+        @spent += payload.cost_dollars
+        raise "Budget exceeded! Spent $#{@spent} of $#{@budget}" if @spent > @budget
+      end
+    end
+  end
+
+  attr_reader :spent
+end
+
+guard = BudgetGuard.new(1.00)  # $1 budget
+guard.subscribe
+# ... make API calls ...
+guard.unsubscribe
+```
+
+### Event Types
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `exa.request.start` | `RequestStart` | Emitted when a request begins |
+| `exa.request.complete` | `RequestComplete` | Emitted on successful completion |
+| `exa.request.error` | `RequestError` | Emitted when a request fails |
+
+**RequestStart** fields: `request_id`, `endpoint`, `http_method`, `path`, `timestamp`
+
+**RequestComplete** fields: `request_id`, `endpoint`, `duration_ms`, `status`, `cost_dollars`, `timestamp`
+
+**RequestError** fields: `request_id`, `endpoint`, `duration_ms`, `error_class`, `error_message`, `timestamp`
+
+### Async Compatibility
+
+The instrumentation system is thread-safe and works inside `Async` blocks:
+
+```ruby
+require "async"
+require "exa/internal/transport/async_requester"
+
+tracker = Exa::Instrumentation::CostTracker.new
+tracker.subscribe
+
+Async do
+  requester = Exa::Internal::Transport::AsyncRequester.new
+  client = Exa::Client.new(api_key: ENV.fetch("EXA_API_KEY"), requester: requester)
+
+  # Concurrent requests - all tracked safely
+  tasks = 5.times.map do |i|
+    Async { client.search.search(query: "query #{i}", num_results: 3) }
+  end
+  tasks.each(&:wait)
+
+  puts "Total cost for #{tracker.request_count} requests: $#{tracker.total_cost}"
+ensure
+  requester.close
+end
+
+tracker.unsubscribe
+```
+
+---
+
 ## Testing & TDD Plan
 
 Run the suite:

data/lib/exa/instrumentation/cost_tracker.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Exa
+  module Instrumentation
+    # Built-in subscriber for tracking API costs from actual response data.
+    # Thread-safe and works with both sync and async requests.
+    #
+    # @example Basic usage
+    #   tracker = Exa::Instrumentation::CostTracker.new
+    #   tracker.subscribe
+    #
+    #   client.search.search(query: "AI papers", num_results: 10)
+    #   client.search.contents(urls: ["https://example.com"], text: true)
+    #
+    #   puts tracker.total_cost  # => 0.006
+    #   puts tracker.summary     # => { Search => 0.005, Contents => 0.001 }
+    #
+    #   tracker.unsubscribe  # Clean up when done
+    class CostTracker < BaseSubscriber
+      # @return [Float] Total accumulated cost in dollars
+      attr_reader :total_cost
+
+      # @return [Integer] Number of requests tracked
+      attr_reader :request_count
+
+      # @return [Array<Hash>] All tracked requests with their costs
+      attr_reader :requests
+
+      def initialize
+        @total_cost = 0.0
+        @request_count = 0
+        @requests = []
+        @mutex = Mutex.new
+        super()
+      end
+
+      # Subscribe to request completion events.
+      # Call this after initialization to start tracking.
+      def subscribe
+        add_subscription("exa.request.complete") do |_event_name, payload|
+          next unless payload.cost_dollars
+
+          @mutex.synchronize do
+            @total_cost += payload.cost_dollars
+            @request_count += 1
+            @requests << {
+              endpoint: payload.endpoint,
+              cost: payload.cost_dollars,
+              request_id: payload.request_id,
+              timestamp: payload.timestamp
+            }
+          end
+        end
+      end
+
+      # Returns a summary of costs grouped by endpoint.
+      # @return [Hash<Endpoint, Float>] Cost per endpoint
+      def summary
+        @mutex.synchronize do
+          @requests
+            .group_by { |req| req[:endpoint] }
+            .transform_values { |reqs| reqs.sum { |r| r[:cost] } }
+        end
+      end
+
+      # Returns the average cost per request.
+      # @return [Float] Average cost or 0.0 if no requests
+      def average_cost
+        @mutex.synchronize do
+          return 0.0 if @request_count.zero?
+          @total_cost / @request_count
+        end
+      end
+
+      # Reset all tracked data.
+      def reset!
+        @mutex.synchronize do
+          @total_cost = 0.0
+          @request_count = 0
+          @requests.clear
+        end
+      end
+
+      # Returns a formatted report of costs.
+      # @return [String] Human-readable cost report
+      def report
+        @mutex.synchronize do
+          lines = ["Exa API Cost Report"]
+          lines << "-" * 40
+          lines << "Total Cost: $#{format('%.6f', @total_cost)}"
+          lines << "Request Count: #{@request_count}"
+          lines << "Average Cost: $#{format('%.6f', @request_count.zero? ? 0.0 : @total_cost / @request_count)}"
+          lines << ""
+          lines << "By Endpoint:"
+
+          @requests
+            .group_by { |req| req[:endpoint] }
+            .transform_values { |reqs| reqs.sum { |r| r[:cost] } }
+            .sort_by { |_endpoint, cost| -cost }
+            .each do |endpoint, cost|
+              lines << "  #{endpoint.serialize}: $#{format('%.6f', cost)}"
+            end
+
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/exa/instrumentation/events.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Exa
+  module Instrumentation
+    # Enum representing API endpoints for instrumentation
+    class Endpoint < T::Enum
+      enums do
+        Search = new("search")
+        Contents = new("contents")
+        FindSimilar = new("findSimilar")
+        Answer = new("answer")
+        Research = new("research")
+        ResearchList = new("research/list")
+        ResearchCancel = new("research/cancel")
+        WebsetCreate = new("websets/create")
+        WebsetGet = new("websets/get")
+        WebsetList = new("websets/list")
+        WebsetDelete = new("websets/delete")
+        WebsetUpdate = new("websets/update")
+        WebsetSearch = new("websets/search")
+        WebsetCancel = new("websets/cancel")
+        WebsetItems = new("websets/items")
+        WebsetEnrichments = new("websets/enrichments")
+        Events = new("events")
+        Webhooks = new("webhooks")
+        Imports = new("imports")
+        Unknown = new("unknown")
+      end
+
+      # Map a path string to an Endpoint enum value
+      def self.from_path(path)
+        normalized = Array(path).join("/").downcase
+
+        case normalized
+        when "search" then Search
+        when "contents" then Contents
+        when "findsimilar" then FindSimilar
+        when "answer" then Answer
+        when /^research$/ then Research
+        when /^research\/[^\/]+$/ then Research
+        when /^research\/[^\/]+\/cancel$/ then ResearchCancel
+        when /^websets$/ then WebsetCreate
+        when /^websets\/[^\/]+$/ then WebsetGet
+        when /^websets\/[^\/]+\/items/ then WebsetItems
+        when /^websets\/[^\/]+\/enrichments/ then WebsetEnrichments
+        when /^websets\/[^\/]+\/search$/ then WebsetSearch
+        when /^websets\/[^\/]+\/cancel$/ then WebsetCancel
+        when /^events/ then Events
+        when /^webhooks/ then Webhooks
+        when /^imports/ then Imports
+        else Unknown
+        end
+      end
+    end
+
+    # Type alias for responses that include cost information
+    ResponseWithCost = T.type_alias do
+      T.any(
+        Exa::Responses::SearchResponse,
+        Exa::Responses::FindSimilarResponse,
+        Exa::Responses::ContentsResponse,
+        Exa::Responses::AnswerResponse
+      )
+    end
+
+    # Type alias for all response types
+    AnyResponse = T.type_alias do
+      T.any(
+        Exa::Responses::SearchResponse,
+        Exa::Responses::FindSimilarResponse,
+        Exa::Responses::ContentsResponse,
+        Exa::Responses::AnswerResponse,
+        Exa::Responses::Research,
+        Exa::Responses::ResearchListResponse
+      )
+    end
+
+    module Events
+      # Emitted when a request starts
+      class RequestStart < T::Struct
+        const :request_id, String
+        const :endpoint, Endpoint
+        const :http_method, Symbol
+        const :path, String
+        const :timestamp, Float
+      end
+
+      # Emitted when a request completes successfully
+      class RequestComplete < T::Struct
+        const :request_id, String
+        const :endpoint, Endpoint
+        const :duration_ms, Float
+        const :status, Integer
+        const :cost_dollars, T.nilable(Float)
+        const :timestamp, Float
+      end
+
+      # Emitted when a request fails with an error
+      class RequestError < T::Struct
+        const :request_id, String
+        const :endpoint, Endpoint
+        const :duration_ms, Float
+        const :error_class, String
+        const :error_message, String
+        const :timestamp, Float
+      end
+    end
+  end
+end

data/lib/exa/instrumentation.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Exa
+  module Instrumentation
+    # Thread-safe event registry for subscribing to and emitting API events.
+    # Supports wildcard pattern matching (e.g., 'exa.request.*').
+    class EventRegistry
+      def initialize
+        @listeners = {}
+        @mutex = Mutex.new
+      end
+
+      # Subscribe to events matching a pattern.
+      # @param pattern [String] Event pattern (supports '*' wildcard)
+      # @yield [event_name, payload] Block called when matching events are emitted
+      # @return [String] Subscription ID for later unsubscription
+      def subscribe(pattern, &block)
+        return unless block_given?
+
+        subscription_id = SecureRandom.uuid
+        @mutex.synchronize do
+          @listeners[subscription_id] = {
+            pattern: pattern,
+            block: block
+          }
+        end
+
+        subscription_id
+      end
+
+      # Unsubscribe from events.
+      # @param subscription_id [String] The ID returned from subscribe
+      def unsubscribe(subscription_id)
+        @mutex.synchronize do
+          @listeners.delete(subscription_id)
+        end
+      end
+
+      # Clear all listeners.
+      def clear_listeners
+        @mutex.synchronize do
+          @listeners.clear
+        end
+      end
+
+      # Emit an event to all matching subscribers.
+      # @param event_name [String] The event name (e.g., 'exa.request.complete')
+      # @param payload [Object] The event payload (usually a typed struct)
+      def notify(event_name, payload)
+        # Take a snapshot of current listeners to avoid holding the mutex during execution
+        matching_listeners = @mutex.synchronize do
+          @listeners.select do |_id, listener|
+            pattern_matches?(listener[:pattern], event_name)
+          end.dup
+        end
+
+        matching_listeners.each do |_id, listener|
+          listener[:block].call(event_name, payload)
+        rescue StandardError
+          # Silently ignore listener errors to avoid breaking the main flow
+        end
+      end
+
+      # Returns the count of registered listeners.
+      def listener_count
+        @mutex.synchronize { @listeners.size }
+      end
+
+      private
+
+      def pattern_matches?(pattern, event_name)
+        if pattern.include?("*")
+          # Convert wildcard pattern to regex
+          # exa.request.* becomes ^exa\.request\..*$
+          regex_pattern = "^#{Regexp.escape(pattern).gsub('\\*', '.*')}$"
+          Regexp.new(regex_pattern).match?(event_name)
+        else
+          # Exact match
+          pattern == event_name
+        end
+      end
+    end
+
+    # Base class for creating event subscribers.
+    # Subclasses should implement #subscribe to add subscriptions.
+    #
+    # @example
+    #   class MyCostTracker < Exa::Instrumentation::BaseSubscriber
+    #     def initialize
+    #       @total = 0.0
+    #       super()
+    #     end
+    #
+    #     def subscribe
+    #       add_subscription('exa.request.complete') do |_, payload|
+    #         @total += payload.cost_dollars || 0
+    #       end
+    #     end
+    #   end
+    class BaseSubscriber
+      def initialize
+        @subscriptions = []
+      end
+
+      # Override to add subscriptions. Called automatically after initialize.
+      def subscribe
+        raise NotImplementedError, "Subclasses must implement #subscribe"
+      end
+
+      # Unsubscribe from all registered subscriptions.
+      def unsubscribe
+        @subscriptions.each { |id| Exa.instrumentation.unsubscribe(id) }
+        @subscriptions.clear
+      end
+
+      protected
+
+      # Add a subscription to the global event registry.
+      # @param pattern [String] Event pattern to match
+      # @yield [event_name, payload] Block called for matching events
+      # @return [String] Subscription ID
+      def add_subscription(pattern, &block)
+        subscription_id = Exa.instrumentation.subscribe(pattern, &block)
+        @subscriptions << subscription_id
+        subscription_id
+      end
+    end
+  end
+end
+
+require_relative "instrumentation/events"
+require_relative "instrumentation/cost_tracker"

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

@@ -3,6 +3,7 @@
 require "uri"
 require "cgi"
 require "json"
+require "securerandom"
 
 require_relative "../util"
 require_relative "pooled_net_requester"
@@ -45,10 +46,17 @@ module Exa
         end
 
         def request(method:, path:, query: nil, headers: nil, body: nil, unwrap: nil, stream: false, response_model: nil, request_options: nil)
+          request_id = SecureRandom.uuid
+          path_str = Array(path).join("/")
+          endpoint = Exa::Instrumentation::Endpoint.from_path(path_str)
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          emit_request_start(request_id, endpoint, method, path_str)
+
           options = normalize_request_options(request_options)
           req = build_request(
             method: method,
-            path: Array(path).join("/"),
+            path: path_str,
             query: query,
             headers: headers,
             body: body,
@@ -56,15 +64,23 @@ module Exa
             idempotency_key: options[:idempotency_key]
           )
 
-          _, 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)
+          begin
+            status, 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)
+
+            result = if stream
+                       Exa::Internal::Transport::Stream.new(headers: parsed_headers, stream: stream_enum)
+                     else
+                       decoded = Exa::Internal::Util.decode_content(parsed_headers, stream: stream_enum)
+                       coerced = coerce_response(response_model, decoded)
+                       unwrap ? dig(coerced, unwrap) : coerced
+                     end
 
-          if stream
-            Exa::Internal::Transport::Stream.new(headers: parsed_headers, stream: stream_enum)
-          else
-            decoded = Exa::Internal::Util.decode_content(parsed_headers, stream: stream_enum)
-            coerced = coerce_response(response_model, decoded)
-            unwrap ? dig(coerced, unwrap) : coerced
+            emit_request_complete(request_id, endpoint, start_time, status, result)
+            result
+          rescue StandardError => e
+            emit_request_error(request_id, endpoint, start_time, e)
+            raise
           end
         end
 
@@ -205,6 +221,61 @@ module Exa
           opts[:idempotency_key] = options[:idempotency_key] if options[:idempotency_key]
           opts
         end
+
+        def emit_request_start(request_id, endpoint, http_method, path)
+          Exa.emit(
+            "exa.request.start",
+            Exa::Instrumentation::Events::RequestStart.new(
+              request_id: request_id,
+              endpoint: endpoint,
+              http_method: http_method,
+              path: path,
+              timestamp: Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            )
+          )
+        end
+
+        def emit_request_complete(request_id, endpoint, start_time, status, result)
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000
+          cost_dollars = extract_cost_dollars(result)
+
+          Exa.emit(
+            "exa.request.complete",
+            Exa::Instrumentation::Events::RequestComplete.new(
+              request_id: request_id,
+              endpoint: endpoint,
+              duration_ms: duration_ms,
+              status: status,
+              cost_dollars: cost_dollars,
+              timestamp: Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            )
+          )
+        end
+
+        def emit_request_error(request_id, endpoint, start_time, error)
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000
+
+          Exa.emit(
+            "exa.request.error",
+            Exa::Instrumentation::Events::RequestError.new(
+              request_id: request_id,
+              endpoint: endpoint,
+              duration_ms: duration_ms,
+              error_class: error.class.name,
+              error_message: error.message,
+              timestamp: Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            )
+          )
+        end
+
+        def extract_cost_dollars(result)
+          return nil unless result.respond_to?(:cost_dollars)
+          cost = result.cost_dollars
+          return nil unless cost
+
+          # CostDollars struct has a total field
+          cost.respond_to?(:total) ? cost.total : nil
+        end
       end
     end
   end

data/lib/exa/responses/answer_response.rb

@@ -27,38 +27,6 @@ module Exa
       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]

data/lib/exa/responses/contents_response.rb

@@ -18,7 +18,7 @@ module Exa
       const :results, T::Array[ResultWithContent]
       const :context, T.nilable(String)
       const :statuses, T.nilable(T::Array[ContentStatus])
-      const :cost_dollars, T.nilable(Float)
+      const :cost_dollars, T.nilable(CostDollars)
 
       def self.from_hash(hash)
         sym = Helpers.symbolize_keys(hash)
@@ -27,7 +27,7 @@ module Exa
           results: Array(sym[:results]).map { ResultWithContent.from_hash(_1) },
           context: sym[:context],
           statuses: sym[:statuses]&.map { ContentStatus.from_hash(_1) },
-          cost_dollars: sym[:costDollars]&.to_f
+          cost_dollars: CostDollars.from_hash(sym[:costDollars])
         )
       end
     end

data/lib/exa/responses/cost.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Exa
+  module Responses
+    # Detailed breakdown of costs by operation type within a single request iteration
+    class CostBreakdownDetail < T::Struct
+      const :neural_search, T.nilable(Float)
+      const :deep_search, T.nilable(Float)
+      const :content_text, T.nilable(Float)
+      const :content_highlight, T.nilable(Float)
+      const :content_summary, T.nilable(Float)
+
+      def self.from_hash(hash)
+        return nil unless hash
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          neural_search: sym[:neuralSearch]&.to_f,
+          deep_search: sym[:deepSearch]&.to_f,
+          content_text: sym[:contentText]&.to_f,
+          content_highlight: sym[:contentHighlight]&.to_f,
+          content_summary: sym[:contentSummary]&.to_f
+        )
+      end
+    end
+
+    # Cost breakdown for a single request iteration (search + contents)
+    class CostBreakdown < T::Struct
+      const :search, T.nilable(Float)
+      const :contents, T.nilable(Float)
+      const :breakdown, T.nilable(CostBreakdownDetail)
+
+      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: CostBreakdownDetail.from_hash(sym[:breakdown])
+        )
+      end
+    end
+
+    # Standard price per request for different search operations
+    class PerRequestPrices < T::Struct
+      const :neural_search, T.nilable(Float)
+      const :deep_search, T.nilable(Float)
+
+      def self.from_hash(hash)
+        return nil unless hash
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          neural_search: sym[:neuralSearch]&.to_f,
+          deep_search: sym[:deepSearch]&.to_f
+        )
+      end
+    end
+
+    # Standard price per page for different content operations
+    class PerPagePrices < T::Struct
+      const :text, T.nilable(Float)
+      const :highlight, T.nilable(Float)
+      const :summary, T.nilable(Float)
+
+      def self.from_hash(hash)
+        return nil unless hash
+        sym = Helpers.symbolize_keys(hash)
+        new(
+          text: sym[:text]&.to_f,
+          highlight: sym[:highlight]&.to_f,
+          summary: sym[:summary]&.to_f
+        )
+      end
+    end
+
+    # Complete cost information returned by Exa API responses
+    class CostDollars < T::Struct
+      const :total, T.nilable(Float)
+      const :break_down, T.nilable(T::Array[CostBreakdown])
+      const :per_request_prices, T.nilable(PerRequestPrices)
+      const :per_page_prices, T.nilable(PerPagePrices)
+
+      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: PerRequestPrices.from_hash(sym[:perRequestPrices]),
+          per_page_prices: PerPagePrices.from_hash(sym[:perPagePrices])
+        )
+      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(T.any(Float, T::Hash[Symbol, T.untyped]))
+      const :cost_dollars, T.nilable(CostDollars)
 
       def self.from_hash(hash)
         sym = Helpers.symbolize_keys(hash)
@@ -18,29 +18,16 @@ module Exa
           search_type: sym[:searchType],
           results: Array(sym[:results]).map { ResultWithContent.from_hash(_1) },
           context: sym[:context],
-          cost_dollars: normalize_cost(sym[:costDollars])
+          cost_dollars: CostDollars.from_hash(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
       const :request_id, T.nilable(String)
       const :results, T::Array[ResultWithContent]
       const :context, T.nilable(String)
-      const :cost_dollars, T.nilable(Float)
+      const :cost_dollars, T.nilable(CostDollars)
 
       def self.from_hash(hash)
         sym = Helpers.symbolize_keys(hash)
@@ -48,7 +35,7 @@ module Exa
           request_id: sym[:requestId],
           results: Array(sym[:results]).map { ResultWithContent.from_hash(_1) },
           context: sym[:context],
-          cost_dollars: sym[:costDollars]&.to_f
+          cost_dollars: CostDollars.from_hash(sym[:costDollars])
         )
       end
     end

data/lib/exa/responses.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "responses/helpers"
+require_relative "responses/cost"
 require_relative "responses/result"
 require_relative "responses/search_response"
 require_relative "responses/contents_response"

data/lib/exa/version.rb

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

data/lib/exa.rb

@@ -12,3 +12,30 @@ require_relative "exa/client"
 require_relative "exa/types"
 require_relative "exa/responses"
 require_relative "exa/resources"
+require_relative "exa/instrumentation"
+
+module Exa
+  class << self
+    # Returns the global instrumentation event registry.
+    # Use this to subscribe to API events for cost tracking, logging, etc.
+    #
+    # @example Subscribe to all request events
+    #   Exa.instrumentation.subscribe('exa.request.*') do |event_name, payload|
+    #     puts "#{event_name}: #{payload.inspect}"
+    #   end
+    #
+    # @return [Exa::Instrumentation::EventRegistry]
+    def instrumentation
+      @instrumentation ||= Instrumentation::EventRegistry.new
+    end
+
+    # Emit an event to all subscribers.
+    # Primarily used internally by the transport layer.
+    #
+    # @param event_name [String] The event name (e.g., 'exa.request.complete')
+    # @param payload [Object] The event payload
+    def emit(event_name, payload)
+      instrumentation.notify(event_name, payload)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exa-ai-ruby
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Vicente Reig Rincon de Arellano
@@ -203,6 +203,9 @@ files:
 - lib/exa/cli/root.rb
 - lib/exa/client.rb
 - lib/exa/errors.rb
+- lib/exa/instrumentation.rb
+- lib/exa/instrumentation/cost_tracker.rb
+- lib/exa/instrumentation/events.rb
 - lib/exa/internal/transport/async_requester.rb
 - lib/exa/internal/transport/base_client.rb
 - lib/exa/internal/transport/pooled_net_requester.rb
@@ -222,6 +225,7 @@ files:
 - lib/exa/responses.rb
 - lib/exa/responses/answer_response.rb
 - lib/exa/responses/contents_response.rb
+- lib/exa/responses/cost.rb
 - lib/exa/responses/event_response.rb
 - lib/exa/responses/helpers.rb
 - lib/exa/responses/import_response.rb