exa-ai 0.1.0

data/lib/exa/cli/formatters/research_formatter.rb

@@ -0,0 +1,120 @@
+module Exa
+  module CLI
+    module Formatters
+      class ResearchFormatter
+        def self.format_task(task, format, show_events: false)
+          case format
+          when "json"
+            JSON.pretty_generate(task.to_h)
+          when "pretty"
+            format_task_pretty(task, show_events: show_events)
+          when "text"
+            format_task_text(task, show_events: show_events)
+          else
+            JSON.pretty_generate(task.to_h)
+          end
+        end
+
+        def self.format_list(list, format)
+          case format
+          when "json"
+            JSON.pretty_generate(list.to_h)
+          when "pretty"
+            format_list_pretty(list)
+          when "text"
+            format_list_text(list)
+          else
+            JSON.pretty_generate(list.to_h)
+          end
+        end
+
+        private
+
+        def self.format_task_pretty(task, show_events: false)
+          output = []
+          output << "Research Task: #{task.research_id}"
+          output << "Status: #{task.status.upcase}"
+          output << "Created: #{task.created_at}"
+          output << ""
+
+          case task.status
+          when "pending"
+            output << "Task is pending execution..."
+          when "running"
+            output << "Task is running... ⚙️"
+          when "completed"
+            output << "Output:"
+            output << "--------"
+            output << task.output.to_s
+            output << ""
+            output << "Cost: $#{task.cost_dollars}" if task.cost_dollars
+          when "failed"
+            output << "Error: #{task.error}"
+          when "canceled"
+            output << "Task was canceled"
+            output << "Finished: #{task.finished_at}" if task.finished_at
+          end
+
+          if show_events && task.events && !task.events.empty?
+            output << ""
+            output << "Events:"
+            output << "-------"
+            task.events.each do |event|
+              output << "- #{event}"
+            end
+          end
+
+          output.join("\n")
+        end
+
+        def self.format_list_pretty(list)
+          output = []
+          output << "Research Tasks (#{list.data.length}):"
+          output << ""
+
+          if list.data.empty?
+            output << "No tasks found."
+          else
+            # Simple table format
+            output << "%-40s %-15s %s" % ["Task ID", "Status", "Created"]
+            output << "-" * 70
+
+            list.data.each do |task|
+              task_id = task.research_id.to_s[0..38]
+              status = task.status.upcase[0..14]
+              created = task.created_at.to_s[0..19]
+              output << "%-40s %-15s %s" % [task_id, status, created]
+            end
+          end
+
+          output << ""
+          if list.has_more
+            output << "More results available. Use --cursor #{list.next_cursor} for next page."
+          else
+            output << "End of results."
+          end
+
+          output.join("\n")
+        end
+
+        def self.format_task_text(task, show_events: false)
+          output = []
+          output << "#{task.research_id} #{task.status.upcase} #{task.created_at}"
+          if task.status == "completed"
+            output << task.output.to_s
+          elsif task.status == "failed"
+            output << "Error: #{task.error}"
+          end
+          output.join("\n")
+        end
+
+        def self.format_list_text(list)
+          output = list.data.map do |task|
+            "#{task.research_id} #{task.status.upcase} #{task.created_at}"
+          end
+          output.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/exa/cli/formatters/search_formatter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class SearchFormatter
+        def self.format(result, format)
+          case format
+          when "json"
+            JSON.pretty_generate(result.to_h)
+          when "pretty"
+            format_pretty(result)
+          when "text"
+            format_text(result)
+          else
+            JSON.pretty_generate(result.to_h)
+          end
+        end
+
+        private
+
+        def self.format_pretty(result)
+          output = []
+          result.results.each_with_index do |item, idx|
+            output << "--- Result #{idx + 1} ---"
+            output << "Title:       #{item['title']}"
+            output << "URL:         #{item['url']}"
+            output << "Score:       #{item['score']}" if item['score']
+            output << ""
+          end
+          output.join("\n")
+        end
+
+        def self.format_text(result)
+          output = []
+          result.results.each do |item|
+            output << "#{item['title']}\n#{item['url']}"
+          end
+          output.join("\n\n")
+        end
+      end
+    end
+  end
+end

data/lib/exa/cli/polling.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    class Polling
+      class TimeoutError < StandardError; end
+
+      # Poll a block until it returns done: true
+      # Implements exponential backoff with jitter
+      #
+      # Options:
+      #   max_duration: Maximum time to poll (default: 300 seconds / 5 minutes)
+      #   initial_delay: Initial delay in seconds (default: 1)
+      #   max_delay: Maximum delay between polls (default: 30)
+      #
+      # Block should return a hash:
+      #   { done: boolean, result: any, status: string }
+      #
+      # Returns the result value when done is true
+      def self.poll(max_duration: 300, initial_delay: 1, max_delay: 30)
+        start_time = Time.now
+        current_delay = initial_delay
+        attempt = 0
+
+        loop do
+          response = yield
+          return response[:result] if response[:done]
+
+          elapsed_time = Time.now - start_time
+          if elapsed_time > max_duration
+            raise TimeoutError,
+                  "Polling timed out after #{elapsed_time.round(2)} seconds"
+          end
+
+          # Sleep before next attempt
+          sleep [current_delay, max_delay].min
+
+          # Exponential backoff: multiply by 2 for next iteration
+          current_delay *= 2
+
+          attempt += 1
+        end
+      end
+    end
+  end
+end

data/lib/exa/client.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Exa
+  # Main client for interacting with the Exa.ai API
+  #
+  # Provides methods for all supported Exa.ai operations including search,
+  # content retrieval, answer generation, and async research tasks.
+  #
+  # @example Basic usage
+  #   client = Exa::Client.new(api_key: "your-key")
+  #   results = client.search("ruby on rails")
+  #   results.results.each { |r| puts r.title }
+  #
+  # @example Using configuration
+  #   Exa.configure { |config| config.api_key = "your-key" }
+  #   client = Exa::Client.new
+  class Client
+    # Initialize a new Exa client
+    #
+    # @param api_key [String, nil] API key for authentication. Falls back to Exa.api_key if not provided
+    # @param options [Hash] Connection options
+    # @option options [String] :base_url Custom API base URL (default: https://api.exa.ai)
+    # @option options [Integer] :timeout Request timeout in seconds (default: 30)
+    # @raise [ConfigurationError] If API key is not provided and not configured
+    def initialize(api_key: nil, **options)
+      @api_key = api_key || Exa.api_key
+      @options = options
+
+      validate_api_key!
+    end
+
+    # Execute a search query
+    #
+    # @param query [String] Search query
+    # @param params [Hash] Additional search parameters
+    # @option params [String] :type Search type (web, news, etc.)
+    # @option params [Array<String>] :include_domains Domains to include in results
+    # @option params [Array<String>] :exclude_domains Domains to exclude from results
+    # @option params [Integer] :num_results Number of results to return
+    # @return [Resources::SearchResult] Search results with metadata
+    def search(query, **params)
+      Services::Search.new(connection, query: query, **params).call
+    end
+
+    # Find similar content to a given URL
+    #
+    # @param url [String] URL to find similar content for
+    # @param options [Hash] Search options
+    # @option options [Integer] :num_results Number of results to return
+    # @return [Resources::SearchResult] Similar results
+    def find_similar(url, **options)
+      Services::FindSimilar.new(connection, url: url, **options).call
+    end
+
+    # Get full page contents for URLs
+    #
+    # @param urls [Array<String>, String] URL or URLs to fetch contents for
+    # @param options [Hash] Fetch options
+    # @return [Resources::ContentCollection] Collection of page contents
+    def get_contents(urls, **options)
+      Services::GetContents.new(connection, urls: urls, **options).call
+    end
+
+    # Get AI-generated answers to a query
+    #
+    # @param query [String] Question or query
+    # @param options [Hash] Answer options
+    # @option options [String] :format Response format (default: standard)
+    # @return [Resources::Answer] AI-generated answer with sources
+    def answer(query, **options)
+      Services::Answer.new(connection, query: query, **options).call
+    end
+
+    # Start an asynchronous research task
+    #
+    # @param params [Hash] Research parameters
+    # @return [Resources::Research] Research task with ID
+    def research_start(**params)
+      Services::ResearchStart.new(connection, **params).call
+    end
+
+    # List all research tasks
+    #
+    # @param params [Hash] Listing parameters
+    # @option params [Integer] :limit Maximum number of tasks to return
+    # @return [Resources::ResearchList] List of research tasks
+    def research_list(**params)
+      Services::ResearchList.new(connection, **params).call
+    end
+
+    # Get status and results of a research task
+    #
+    # @param research_id [String] Research task ID
+    # @param params [Hash] Fetch options
+    # @return [Resources::Research] Research task with current status and results
+    def research_get(research_id, **params)
+      Services::ResearchGet.new(connection, research_id: research_id, **params).call
+    end
+
+    # Search code repositories
+    #
+    # @param query [String] Code search query
+    # @param params [Hash] Search parameters
+    # @option params [Array<String>] :languages Programming languages to search
+    # @return [Resources::SearchResult] Code search results
+    def context(query, **params)
+      Services::Context.new(connection, query: query, **params).call
+    end
+
+    private
+
+    def connection
+      @connection ||= Connection.build(
+        api_key: @api_key,
+        **connection_options
+      )
+    end
+
+    def connection_options
+      options = {}
+      options[:base_url] = @options[:base_url] if @options[:base_url]
+      options[:timeout] = @options[:timeout] if @options[:timeout]
+      options
+    end
+
+    def validate_api_key!
+      return if @api_key && !@api_key.empty?
+
+      raise ConfigurationError, "API key is required. Set it with Exa.configure or pass it to Client.new"
+    end
+  end
+end

data/lib/exa/connection.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Exa
+  class Connection
+    def self.build(api_key:, **options, &block)
+      Faraday.new(url: options[:base_url] || DEFAULT_BASE_URL) do |conn|
+        # Authentication
+        conn.request :authorization, "Bearer", api_key
+
+        # Request/Response JSON encoding
+        conn.request :json
+
+        # Custom error handling (registered before JSON so it runs after in response chain)
+        conn.response :raise_error
+        conn.response :json, content_type: /\bjson$/
+
+        # Timeouts
+        conn.options.timeout = options[:timeout] || 30
+        conn.options.open_timeout = options[:open_timeout] || 10
+
+        # Adapter (allow override for testing)
+        if block_given?
+          conn.adapter options[:adapter] || Faraday.default_adapter, &block
+        else
+          conn.adapter options[:adapter] || Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/exa/error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Exa
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(message = nil, response = nil)
+      @response = response
+      super(message)
+    end
+  end
+
+  # Client errors (4xx)
+  class ClientError < Error; end
+  class BadRequest < ClientError; end          # 400
+  class Unauthorized < ClientError; end        # 401
+  class Forbidden < ClientError; end           # 403
+  class NotFound < ClientError; end            # 404
+  class UnprocessableEntity < ClientError; end # 422
+  class TooManyRequests < ClientError; end     # 429
+
+  # Server errors (5xx)
+  class ServerError < Error; end
+  class InternalServerError < ServerError; end # 500
+  class BadGateway < ServerError; end          # 502
+  class ServiceUnavailable < ServerError; end  # 503
+  class GatewayTimeout < ServerError; end      # 504
+
+  # Configuration errors
+  class ConfigurationError < Error; end
+end

data/lib/exa/middleware/raise_error.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Exa
+  module Middleware
+    class RaiseError < Faraday::Middleware
+      def on_complete(env)
+        case env[:status]
+        when 400
+          handle_error(env, Exa::BadRequest)
+        when 401
+          handle_error(env, Exa::Unauthorized)
+        when 403
+          handle_error(env, Exa::Forbidden)
+        when 404
+          handle_error(env, Exa::NotFound)
+        when 422
+          handle_error(env, Exa::UnprocessableEntity)
+        when 429
+          handle_error(env, Exa::TooManyRequests)
+        when 500
+          handle_error(env, Exa::InternalServerError)
+        when 502
+          handle_error(env, Exa::BadGateway)
+        when 503
+          handle_error(env, Exa::ServiceUnavailable)
+        when 504
+          handle_error(env, Exa::GatewayTimeout)
+        end
+      end
+
+      private
+
+      def handle_error(env, error_class)
+        message = extract_error_message(env)
+        raise error_class.new(message, env.response)
+      end
+
+      def extract_error_message(env)
+        body = env[:body]
+
+        if body.is_a?(Hash)
+          return body["error"] if body["error"]
+          return body[:error] if body[:error]
+        end
+
+        "HTTP #{env[:status]}"
+      end
+    end
+  end
+end
+
+# Register the middleware with Faraday
+Faraday::Response.register_middleware raise_error: Exa::Middleware::RaiseError

data/lib/exa/resources/answer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents an answer response from the Exa API
+    #
+    # This class wraps the JSON response from the /answer endpoint and provides
+    # a Ruby-friendly interface for accessing the generated answer and citations.
+    class Answer < Struct.new(:answer, :citations, :cost_dollars, keyword_init: true)
+      def initialize(answer:, citations: [], cost_dollars: nil)
+        super
+        freeze
+      end
+
+      def to_h
+        { answer: answer, citations: citations, cost_dollars: cost_dollars }
+      end
+    end
+  end
+end

data/lib/exa/resources/contents_result.rb

@@ -0,0 +1,29 @@
+module Exa
+  module Resources
+    # Represents a contents response from the Exa API
+    #
+    # This class wraps the JSON response from the /contents endpoint and provides
+    # a Ruby-friendly interface for accessing content results and metadata.
+    class ContentsResult < Struct.new(
+      :results,
+      :request_id,
+      :context,
+      :statuses,
+      :cost_dollars,
+      keyword_init: true
+    )
+      def initialize(results:, request_id: nil, context: nil, statuses: nil, cost_dollars: nil)
+        super
+        freeze
+      end
+
+      def empty?
+        results.empty?
+      end
+
+      def first
+        results.first
+      end
+    end
+  end
+end

data/lib/exa/resources/context_result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Exa
+  module Resources
+    # Represents a Context API response from the Exa API
+    #
+    # This class wraps the JSON response from the /context endpoint and provides
+    # a Ruby-friendly interface for accessing code snippets and metadata.
+    class ContextResult < Struct.new(
+      :request_id,
+      :query,
+      :response,
+      :results_count,
+      :cost_dollars,
+      :search_time,
+      :output_tokens,
+      keyword_init: true
+    )
+      def initialize(**)
+        super
+        freeze
+      end
+
+      def to_h
+        {
+          request_id: request_id,
+          query: query,
+          response: response,
+          results_count: results_count,
+          cost_dollars: cost_dollars,
+          search_time: search_time,
+          output_tokens: output_tokens
+        }
+      end
+    end
+  end
+end

data/lib/exa/resources/find_similar_result.rb

@@ -0,0 +1,28 @@
+module Exa
+  module Resources
+    # Represents a find similar response from the Exa API
+    #
+    # This class wraps the JSON response from the /findSimilar endpoint and provides
+    # a Ruby-friendly interface for accessing similar results and metadata.
+    class FindSimilarResult < Struct.new(
+      :results,
+      :request_id,
+      :context,
+      :cost_dollars,
+      keyword_init: true
+    )
+      def initialize(results:, request_id: nil, context: nil, cost_dollars: nil)
+        super
+        freeze
+      end
+
+      def empty?
+        results.empty?
+      end
+
+      def first
+        results.first
+      end
+    end
+  end
+end

data/lib/exa/resources/research_list.rb

@@ -0,0 +1,18 @@
+module Exa
+  module Resources
+    class ResearchList < Struct.new(:data, :has_more, :next_cursor, keyword_init: true)
+      def initialize(data:, has_more:, next_cursor: nil)
+        super
+        freeze
+      end
+
+      def to_h
+        {
+          data: data.map { |item| item.respond_to?(:to_h) ? item.to_h : item },
+          has_more: has_more,
+          next_cursor: next_cursor
+        }
+      end
+    end
+  end
+end

data/lib/exa/resources/research_task.rb

@@ -0,0 +1,39 @@
+module Exa
+  module Resources
+    class ResearchTask < Struct.new(
+      :research_id, :created_at, :status, :model, :instructions,
+      :output_schema, :events, :output, :cost_dollars, :finished_at,
+      :error, keyword_init: true
+    )
+      def initialize(research_id:, created_at:, status:, instructions:, model: nil, output_schema: nil, events: nil, output: nil, cost_dollars: nil, finished_at: nil, error: nil)
+        super
+        freeze
+      end
+
+      def pending? = status == 'pending'
+      def running? = status == 'running'
+      def completed? = status == 'completed'
+      def failed? = status == 'failed'
+      def canceled? = status == 'canceled'
+
+      def finished? = !running? && !pending?
+
+      def to_h
+        result = {
+          research_id: research_id,
+          created_at: created_at,
+          status: status,
+          instructions: instructions
+        }
+        result[:model] = model if model
+        result[:output_schema] = output_schema if output_schema
+        result[:events] = events if events
+        result[:output] = output if output
+        result[:cost_dollars] = cost_dollars if cost_dollars
+        result[:finished_at] = finished_at if finished_at
+        result[:error] = error if error
+        result
+      end
+    end
+  end
+end

data/lib/exa/resources/search_result.rb

@@ -0,0 +1,30 @@
+module Exa
+  module Resources
+    # Represents a search response from the Exa API
+    #
+    # This class wraps the JSON response from the /search endpoint and provides
+    # a Ruby-friendly interface for accessing search results and metadata.
+    class SearchResult < Struct.new(
+      :results,
+      :request_id,
+      :resolved_search_type,
+      :search_type,
+      :context,
+      :cost_dollars,
+      keyword_init: true
+    )
+      def initialize(results:, request_id: nil, resolved_search_type: nil, search_type: nil, context: nil, cost_dollars: nil)
+        super
+        freeze
+      end
+
+      def empty?
+        results.empty?
+      end
+
+      def first
+        results.first
+      end
+    end
+  end
+end

data/lib/exa/services/answer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    class Answer
+      def initialize(connection, **params)
+        @connection = connection
+        @params = params
+      end
+
+      def call
+        response = @connection.post("/answer", @params)
+        body = response.body
+
+        Resources::Answer.new(
+          answer: body["answer"],
+          citations: body["citations"] || [],
+          cost_dollars: body["costDollars"]
+        )
+      end
+    end
+  end
+end