exaonruby 1.0.0

data/lib/exa/configuration.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  class Configuration
+    # @return [String, nil] API key for authentication
+    attr_accessor :api_key
+
+    # @return [String] Base URL for the Exa API
+    attr_accessor :base_url
+
+    # @return [String] Base URL for the Websets API
+    attr_accessor :websets_base_url
+
+    # @return [Integer] Request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] Number of retries for transient failures
+    attr_accessor :max_retries
+
+    # @return [Float] Initial retry delay in seconds
+    attr_accessor :retry_delay
+
+    # @return [Float] Maximum retry delay in seconds
+    attr_accessor :max_retry_delay
+
+    # @return [Array<Integer>] HTTP status codes to retry on
+    attr_accessor :retry_statuses
+
+    # @return [Array<Class>] Exception classes to retry on
+    attr_accessor :retry_exceptions
+
+    DEFAULT_BASE_URL = "https://api.exa.ai"
+    DEFAULT_WEBSETS_BASE_URL = "https://api.exa.ai/websets/v0"
+    DEFAULT_TIMEOUT = 60
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_RETRY_DELAY = 0.5
+    DEFAULT_MAX_RETRY_DELAY = 30.0
+    DEFAULT_RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+    DEFAULT_RETRY_EXCEPTIONS = [
+      Faraday::TimeoutError,
+      Faraday::ConnectionFailed
+    ].freeze
+
+    def initialize
+      @api_key = ENV.fetch("EXA_API_KEY", nil)
+      @base_url = DEFAULT_BASE_URL
+      @websets_base_url = DEFAULT_WEBSETS_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @max_retries = DEFAULT_MAX_RETRIES
+      @retry_delay = DEFAULT_RETRY_DELAY
+      @max_retry_delay = DEFAULT_MAX_RETRY_DELAY
+      @retry_statuses = DEFAULT_RETRY_STATUSES.dup
+      @retry_exceptions = DEFAULT_RETRY_EXCEPTIONS.dup
+    end
+
+    # Validates that required configuration is present
+    # @raise [Exa::AuthenticationError] if API key is missing
+    # @return [void]
+    def validate!
+      raise AuthenticationError, "API key is required. Set via Exa.configure or EXA_API_KEY environment variable." unless api_key
+    end
+
+    # Creates a duplicate of the configuration
+    # @return [Configuration] duplicated configuration
+    def dup
+      config = Configuration.new
+      config.api_key = api_key
+      config.base_url = base_url
+      config.websets_base_url = websets_base_url
+      config.timeout = timeout
+      config.max_retries = max_retries
+      config.retry_delay = retry_delay
+      config.max_retry_delay = max_retry_delay
+      config.retry_statuses = retry_statuses.dup
+      config.retry_exceptions = retry_exceptions.dup
+      config
+    end
+  end
+end

data/lib/exa/endpoints/answer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module Answer
+      # Get an LLM answer to a question informed by Exa search results
+      #
+      # The /answer endpoint performs an Exa search and uses an LLM to generate either:
+      # 1. A direct answer for specific queries (e.g., "What is the capital of France?" returns "Paris")
+      # 2. A detailed summary with citations for open-ended queries
+      #
+      # @param query [String] The question or query to answer
+      # @param text [Boolean] If true, includes full text content in search results
+      # @param stream [Boolean] If true, response is returned as server-sent events stream
+      # @param search_options [Hash] Additional search options to customize the underlying search
+      # @option search_options [Symbol] :type Search type (:neural, :auto, :fast, :deep)
+      # @option search_options [Integer] :num_results Number of results to use
+      # @option search_options [Array<String>] :include_domains Domains to include
+      # @option search_options [Array<String>] :exclude_domains Domains to exclude
+      # @option search_options [String] :start_published_date Only results published after this date
+      # @option search_options [String] :end_published_date Only results published before this date
+      #
+      # @return [Exa::Resources::AnswerResponse] Answer with citations
+      #
+      # @raise [Exa::InvalidRequestError] if parameters are invalid
+      # @raise [Exa::AuthenticationError] if API key is invalid
+      # @raise [Exa::RateLimitError] if rate limit is exceeded
+      #
+      # @example Get a direct answer
+      #   response = client.answer("What is the latest valuation of SpaceX?")
+      #   puts response.answer
+      #   response.citations.each { |c| puts "Source: #{c.url}" }
+      #
+      # @example Answer with search options
+      #   response = client.answer(
+      #     "What are the latest AI safety developments?",
+      #     text: true,
+      #     search_options: {
+      #       num_results: 10,
+      #       start_published_date: "2024-01-01T00:00:00.000Z"
+      #     }
+      #   )
+      def answer(query, text: nil, stream: false, **search_options)
+        raise InvalidRequestError, "query must be a non-empty string" if !query.is_a?(String) || query.empty?
+
+        params = build_answer_params(query, text, stream, search_options)
+        response = post("/answer", params)
+
+        Resources::AnswerResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      private
+
+      # @param query [String] The question
+      # @param text [Boolean, nil] Include text content
+      # @param stream [Boolean] Stream response
+      # @param search_options [Hash] Additional search options
+      # @return [Hash] API-formatted parameters
+      def build_answer_params(query, text, stream, search_options)
+        params = { query: query }
+
+        params[:text] = text unless text.nil?
+        params[:stream] = stream if stream
+
+        if search_options[:type]
+          params[:type] = search_options[:type].to_s
+        end
+
+        if search_options[:num_results]
+          params[:numResults] = search_options[:num_results]
+        end
+
+        if search_options[:include_domains]
+          params[:includeDomains] = search_options[:include_domains]
+        end
+
+        if search_options[:exclude_domains]
+          params[:excludeDomains] = search_options[:exclude_domains]
+        end
+
+        if search_options[:start_published_date]
+          params[:startPublishedDate] = Utils::ParameterConverter.format_date(search_options[:start_published_date])
+        end
+
+        if search_options[:end_published_date]
+          params[:endPublishedDate] = Utils::ParameterConverter.format_date(search_options[:end_published_date])
+        end
+
+        if search_options[:start_crawl_date]
+          params[:startCrawlDate] = Utils::ParameterConverter.format_date(search_options[:start_crawl_date])
+        end
+
+        if search_options[:end_crawl_date]
+          params[:endCrawlDate] = Utils::ParameterConverter.format_date(search_options[:end_crawl_date])
+        end
+
+        if search_options[:category]
+          params[:category] = search_options[:category].to_s.tr("_", " ")
+        end
+
+        params
+      end
+    end
+  end
+end

data/lib/exa/endpoints/contents.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module Contents
+      VALID_LIVECRAWL_OPTIONS = %i[never fallback preferred always].freeze
+
+      # Get the full page contents, summaries, and metadata for a list of URLs
+      #
+      # Returns instant results from Exa's cache, with automatic live crawling
+      # as fallback for uncached pages.
+      #
+      # @param urls [Array<String>] URLs to fetch content from
+      # @param text [Boolean, Hash] Return text content. Hash for options: { max_characters: 1000 }
+      # @param highlights [Boolean, Hash] Return highlights. Hash for options: { num_sentences: 3, highlight_query: "..." }
+      # @param summary [Boolean, Hash] Return summary. Hash for options: { query: "..." }
+      # @param livecrawl [Symbol] Livecrawl option: :never, :fallback (default), :preferred, :always
+      # @param livecrawl_timeout [Integer] Livecrawl timeout in milliseconds
+      # @param subpages [Integer] Number of subpages to crawl
+      # @param subpage_target [String, Array<String>] Terms to find specific subpages
+      # @param context [Boolean, Integer] Return context string for LLM. Integer for max characters
+      #
+      # @return [Exa::Resources::ContentsResponse] Contents results with statuses
+      #
+      # @raise [Exa::InvalidRequestError] if parameters are invalid
+      # @raise [Exa::AuthenticationError] if API key is invalid
+      # @raise [Exa::RateLimitError] if rate limit is exceeded
+      #
+      # @example Basic content retrieval
+      #   client.get_contents(["https://example.com/article"])
+      #
+      # @example With text and summary
+      #   client.get_contents(
+      #     ["https://arxiv.org/abs/2307.06435"],
+      #     text: true,
+      #     summary: true
+      #   )
+      #
+      # @example With livecrawl and subpages
+      #   client.get_contents(
+      #     ["https://example.com"],
+      #     livecrawl: :preferred,
+      #     subpages: 3,
+      #     subpage_target: "about"
+      #   )
+      def get_contents(urls, **options)
+        validate_contents_options!(urls, options)
+
+        params = build_contents_params(urls, options)
+        response = post("/contents", params)
+
+        Resources::ContentsResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      private
+
+      # @param urls [Array<String>] URLs to validate
+      # @param options [Hash] Options to validate
+      # @raise [Exa::InvalidRequestError] if validation fails
+      def validate_contents_options!(urls, options)
+        raise InvalidRequestError, "urls must be a non-empty array" if !urls.is_a?(Array) || urls.empty?
+
+        urls.each do |url|
+          raise InvalidRequestError, "Each URL must be a string" unless url.is_a?(String)
+        end
+
+        if options[:livecrawl] && !VALID_LIVECRAWL_OPTIONS.include?(options[:livecrawl])
+          raise InvalidRequestError, "Invalid livecrawl option: #{options[:livecrawl]}. Valid options: #{VALID_LIVECRAWL_OPTIONS.join(", ")}"
+        end
+
+        if options[:subpages] && options[:subpages] < 0
+          raise InvalidRequestError, "subpages must be a non-negative integer"
+        end
+      end
+
+      # @param urls [Array<String>] URLs to fetch
+      # @param options [Hash] Content options
+      # @return [Hash] API-formatted parameters
+      def build_contents_params(urls, options)
+        params = { urls: urls }
+
+        add_contents_options!(params, options)
+
+        params
+      end
+
+      # @param params [Hash] Parameters to modify
+      # @param options [Hash] Source options
+      def add_contents_options!(params, options)
+        params[:text] = format_content_param(options[:text]) if options.key?(:text)
+        params[:highlights] = format_highlights_param(options[:highlights]) if options.key?(:highlights)
+        params[:summary] = format_summary_param(options[:summary]) if options.key?(:summary)
+
+        if options.key?(:context)
+          params[:context] = options[:context].is_a?(Integer) ? { maxCharacters: options[:context] } : options[:context]
+        end
+
+        params[:livecrawl] = options[:livecrawl].to_s if options[:livecrawl]
+        params[:livecrawlTimeout] = options[:livecrawl_timeout] if options[:livecrawl_timeout]
+        params[:subpages] = options[:subpages] if options[:subpages]
+        params[:subpageTarget] = options[:subpage_target] if options[:subpage_target]
+
+        add_extras!(params, options) if options[:extras]
+      end
+
+      # @param option [Boolean, Hash] Content option
+      # @return [Boolean, Hash] Formatted option
+      def format_content_param(option)
+        return option if option.is_a?(TrueClass) || option.is_a?(FalseClass)
+
+        Utils::ParameterConverter.to_api_params(option)
+      end
+
+      # @param option [Boolean, Hash] Highlights option
+      # @return [Boolean, Hash] Formatted option
+      def format_highlights_param(option)
+        return option if option.is_a?(TrueClass) || option.is_a?(FalseClass)
+
+        Utils::ParameterConverter.to_api_params(option)
+      end
+
+      # @param option [Boolean, Hash] Summary option
+      # @return [Boolean, Hash] Formatted option
+      def format_summary_param(option)
+        return option if option.is_a?(TrueClass) || option.is_a?(FalseClass)
+
+        Utils::ParameterConverter.to_api_params(option)
+      end
+
+      # @param params [Hash] Parameters to modify
+      # @param options [Hash] Source options
+      def add_extras!(params, options)
+        params[:extras] = Utils::ParameterConverter.to_api_params(options[:extras])
+      end
+    end
+  end
+end

data/lib/exa/endpoints/events.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module Events
+      VALID_EVENT_TYPES = %w[
+        webset.created webset.deleted webset.paused webset.idle
+        webset.search.created webset.search.canceled webset.search.completed webset.search.updated
+        import.created import.completed
+        webset.item.created webset.item.enriched
+        monitor.created monitor.updated monitor.deleted
+        monitor.run.created monitor.run.completed
+        webset.export.created webset.export.completed
+      ].freeze
+
+      # Gets an Event by ID
+      #
+      # @param event_id [String] Event ID
+      # @return [Exa::Resources::Event] The Event
+      #
+      # @example Get an event
+      #   event = client.get_event("evt_abc123")
+      #   puts "Type: #{event.type}"
+      #   puts "Data: #{event.data}"
+      def get_event(event_id)
+        raise InvalidRequestError, "event_id must be a non-empty string" if !event_id.is_a?(String) || event_id.empty?
+
+        response = websets_get("/events/#{event_id}")
+
+        Resources::Event.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      # Lists Events with optional filtering
+      #
+      # @param cursor [String, nil] Cursor for pagination
+      # @param limit [Integer, nil] Number of results per page
+      # @param types [Array<String>, nil] Filter by event types
+      # @param webset_id [String, nil] Filter by Webset ID
+      # @param after [String, Time, nil] Events after this timestamp
+      # @param before [String, Time, nil] Events before this timestamp
+      #
+      # @return [Exa::Resources::EventListResponse] Paginated list of Events
+      #
+      # @example List recent item events
+      #   response = client.list_events(
+      #     types: ["webset.item.created", "webset.item.enriched"],
+      #     limit: 50
+      #   )
+      #   response.data.each { |e| puts "#{e.type} at #{e.created_at}" }
+      def list_events(cursor: nil, limit: nil, types: nil, webset_id: nil, after: nil, before: nil)
+        params = {}
+        params[:cursor] = cursor if cursor
+        params[:limit] = limit if limit
+        params[:types] = types if types
+        params[:websetId] = webset_id if webset_id
+        params[:after] = Utils::ParameterConverter.format_date(after) if after
+        params[:before] = Utils::ParameterConverter.format_date(before) if before
+
+        response = websets_get("/events", params)
+
+        Resources::EventListResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+    end
+  end
+end

data/lib/exa/endpoints/find_similar.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Endpoints
+    module FindSimilar
+      VALID_LIVECRAWL_OPTIONS = %i[never fallback preferred always].freeze
+
+      # Find similar links to the provided URL
+      #
+      # Uses Exa's embeddings-based model to find pages that are semantically
+      # similar to the source URL. Optionally returns the contents of found pages.
+      #
+      # @param url [String] The source URL to find similar links for
+      # @param num_results [Integer] Number of results to return (max 100)
+      # @param include_domains [Array<String>] Domains to include in results
+      # @param exclude_domains [Array<String>] Domains to exclude from results
+      # @param start_crawl_date [String, Time] Results crawled after this date (ISO 8601)
+      # @param end_crawl_date [String, Time] Results crawled before this date (ISO 8601)
+      # @param start_published_date [String, Time] Results published after this date (ISO 8601)
+      # @param end_published_date [String, Time] Results published before this date (ISO 8601)
+      # @param include_text [Array<String>] Strings that must be present in page text
+      # @param exclude_text [Array<String>] Strings that must not be present in page text
+      # @param text [Boolean, Hash] Return text content. Hash for options: { max_characters: 1000 }
+      # @param highlights [Boolean, Hash] Return highlights. Hash for options: { num_sentences: 3, highlight_query: "..." }
+      # @param summary [Boolean, Hash] Return summary. Hash for options: { query: "..." }
+      # @param context [Boolean, Integer] Return context string for LLM. Integer for max characters
+      # @param moderation [Boolean] Enable content moderation
+      #
+      # @return [Exa::Resources::SearchResponse] Similar links results
+      #
+      # @raise [Exa::InvalidRequestError] if parameters are invalid
+      # @raise [Exa::AuthenticationError] if API key is invalid
+      # @raise [Exa::RateLimitError] if rate limit is exceeded
+      #
+      # @example Basic similar links search
+      #   client.find_similar("https://arxiv.org/abs/2307.06435")
+      #
+      # @example With content and filters
+      #   client.find_similar(
+      #     "https://arxiv.org/abs/2307.06435",
+      #     text: true,
+      #     num_results: 20,
+      #     include_domains: ["arxiv.org", "paperswithcode.com"]
+      #   )
+      def find_similar(url, **options)
+        validate_find_similar_options!(url, options)
+
+        params = build_find_similar_params(url, options)
+        response = post("/findSimilar", params)
+
+        Resources::SearchResponse.new(
+          Utils::ParameterConverter.from_api_response(response)
+        )
+      end
+
+      private
+
+      # @param url [String] URL to validate
+      # @param options [Hash] Options to validate
+      # @raise [Exa::InvalidRequestError] if validation fails
+      def validate_find_similar_options!(url, options)
+        raise InvalidRequestError, "url must be a non-empty string" if !url.is_a?(String) || url.empty?
+
+        if options[:num_results] && (options[:num_results] < 1 || options[:num_results] > 100)
+          raise InvalidRequestError, "num_results must be between 1 and 100"
+        end
+      end
+
+      # @param url [String] Source URL
+      # @param options [Hash] Search options
+      # @return [Hash] API-formatted parameters
+      def build_find_similar_params(url, options)
+        params = { url: url }
+
+        params[:numResults] = options[:num_results] if options[:num_results]
+        params[:moderation] = options[:moderation] if options.key?(:moderation)
+
+        add_find_similar_domain_filters!(params, options)
+        add_find_similar_date_filters!(params, options)
+        add_find_similar_text_filters!(params, options)
+        add_find_similar_content_options!(params, options)
+
+        params
+      end
+
+      # @param params [Hash] Parameters to modify
+      # @param options [Hash] Source options
+      def add_find_similar_domain_filters!(params, options)
+        params[:includeDomains] = options[:include_domains] if options[:include_domains]
+        params[:excludeDomains] = options[:exclude_domains] if options[:exclude_domains]
+      end
+
+      # @param params [Hash] Parameters to modify
+      # @param options [Hash] Source options
+      def add_find_similar_date_filters!(params, options)
+        params[:startCrawlDate] = format_find_similar_date(options[:start_crawl_date]) if options[:start_crawl_date]
+        params[:endCrawlDate] = format_find_similar_date(options[:end_crawl_date]) if options[:end_crawl_date]
+        params[:startPublishedDate] = format_find_similar_date(options[:start_published_date]) if options[:start_published_date]
+        params[:endPublishedDate] = format_find_similar_date(options[:end_published_date]) if options[:end_published_date]
+      end
+
+      # @param params [Hash] Parameters to modify
+      # @param options [Hash] Source options
+      def add_find_similar_text_filters!(params, options)
+        params[:includeText] = options[:include_text] if options[:include_text]
+        params[:excludeText] = options[:exclude_text] if options[:exclude_text]
+      end
+
+      # @param params [Hash] Parameters to modify
+      # @param options [Hash] Source options
+      def add_find_similar_content_options!(params, options)
+        params[:text] = format_find_similar_content_option(options[:text]) if options.key?(:text)
+        params[:highlights] = format_find_similar_highlights_option(options[:highlights]) if options.key?(:highlights)
+        params[:summary] = format_find_similar_summary_option(options[:summary]) if options.key?(:summary)
+
+        if options.key?(:context)
+          params[:context] = options[:context].is_a?(Integer) ? { maxCharacters: options[:context] } : options[:context]
+        end
+      end
+
+      # @param option [Boolean, Hash] Content option
+      # @return [Boolean, Hash] Formatted option
+      def format_find_similar_content_option(option)
+        return option if option.is_a?(TrueClass) || option.is_a?(FalseClass)
+
+        Utils::ParameterConverter.to_api_params(option)
+      end
+
+      # @param option [Boolean, Hash] Highlights option
+      # @return [Boolean, Hash] Formatted option
+      def format_find_similar_highlights_option(option)
+        return option if option.is_a?(TrueClass) || option.is_a?(FalseClass)
+
+        Utils::ParameterConverter.to_api_params(option)
+      end
+
+      # @param option [Boolean, Hash] Summary option
+      # @return [Boolean, Hash] Formatted option
+      def format_find_similar_summary_option(option)
+        return option if option.is_a?(TrueClass) || option.is_a?(FalseClass)
+
+        Utils::ParameterConverter.to_api_params(option)
+      end
+
+      # @param value [Time, Date, String, nil] Date value
+      # @return [String, nil] ISO 8601 formatted string
+      def format_find_similar_date(value)
+        Utils::ParameterConverter.format_date(value)
+      end
+    end
+  end
+end