exaonruby 1.0.0

data/lib/exa/cli.rb

@@ -0,0 +1,458 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require "thor"
+require "json"
+
+module Exa
+  # Beautiful command-line interface for the Exa.ai API
+  #
+  # Features:
+  # - Neural search from the terminal
+  # - Answer questions instantly
+  # - Manage Websets and enrichments
+  # - Monitor research tasks
+  # - Colorful, informative output
+  #
+  # @example Basic usage
+  #   $ exa search "latest AI research"
+  #   $ exa answer "What is the valuation of SpaceX?"
+  #   $ exa websets list
+  class CLI < Thor
+    class_option :api_key, type: :string, aliases: "-k", desc: "API key (or set EXA_API_KEY)"
+    class_option :json, type: :boolean, aliases: "-j", desc: "Output raw JSON"
+    class_option :no_color, type: :boolean, desc: "Disable colored output"
+
+    def self.exit_on_failure?
+      true
+    end
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # SEARCH COMMANDS
+    # ═══════════════════════════════════════════════════════════════════════
+
+    desc "search QUERY", "Search the web using Exa's neural search"
+    method_option :num, type: :numeric, default: 10, aliases: "-n", desc: "Number of results"
+    method_option :type, type: :string, default: "auto", desc: "Search type: auto, neural, fast, deep"
+    method_option :text, type: :boolean, default: false, aliases: "-t", desc: "Include text content"
+    method_option :summary, type: :boolean, default: false, aliases: "-s", desc: "Include AI summary"
+    method_option :domain, type: :string, aliases: "-d", desc: "Filter by domain"
+    method_option :category, type: :string, aliases: "-c", desc: "Category filter"
+    def search(query)
+      with_client do |client|
+        opts = {
+          num_results: options[:num],
+          type: options[:type].to_sym,
+          text: options[:text],
+          summary: options[:summary]
+        }
+        opts[:include_domains] = [options[:domain]] if options[:domain]
+        opts[:category] = options[:category].to_sym if options[:category]
+
+        response = client.search(query, **opts)
+
+        if options[:json]
+          puts JSON.pretty_generate(response.raw)
+        else
+          print_search_results(response, query)
+        end
+      end
+    end
+
+    desc "answer QUESTION", "Get an AI-powered answer with citations"
+    method_option :text, type: :boolean, default: true, aliases: "-t", desc: "Include source text"
+    def answer(question)
+      with_client do |client|
+        response = client.answer(question, text: options[:text])
+
+        if options[:json]
+          puts JSON.pretty_generate(response.raw)
+        else
+          print_answer(response, question)
+        end
+      end
+    end
+
+    desc "similar URL", "Find pages similar to a URL"
+    method_option :num, type: :numeric, default: 10, aliases: "-n", desc: "Number of results"
+    method_option :text, type: :boolean, default: false, aliases: "-t", desc: "Include text content"
+    def similar(url)
+      with_client do |client|
+        response = client.find_similar(url, num_results: options[:num], text: options[:text])
+
+        if options[:json]
+          puts JSON.pretty_generate(response.raw)
+        else
+          print_search_results(response, "Similar to: #{url}")
+        end
+      end
+    end
+
+    desc "contents URLS...", "Fetch full page contents from URLs"
+    method_option :summary, type: :boolean, default: false, aliases: "-s", desc: "Include AI summary"
+    def contents(*urls)
+      with_client do |client|
+        response = client.get_contents(urls, text: true, summary: options[:summary])
+
+        if options[:json]
+          puts JSON.pretty_generate(response.raw)
+        else
+          print_contents(response)
+        end
+      end
+    end
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # RESEARCH COMMANDS
+    # ═══════════════════════════════════════════════════════════════════════
+
+    desc "research INSTRUCTIONS", "Start an async research task"
+    method_option :model, type: :string, default: "exa-research", desc: "Model: exa-research-fast, exa-research, exa-research-pro"
+    method_option :wait, type: :boolean, default: false, aliases: "-w", desc: "Wait for completion"
+    def research(instructions)
+      with_client do |client|
+        task = client.create_research(instructions: instructions, model: options[:model])
+
+        if options[:wait]
+          print_waiting_for_research(task)
+          task = wait_for_research(client, task.research_id)
+        end
+
+        if options[:json]
+          puts JSON.pretty_generate(task.raw)
+        else
+          print_research_task(task)
+        end
+      end
+    end
+
+    desc "research_status ID", "Get status of a research task"
+    def research_status(research_id)
+      with_client do |client|
+        task = client.get_research(research_id)
+
+        if options[:json]
+          puts JSON.pretty_generate(task.raw)
+        else
+          print_research_task(task)
+        end
+      end
+    end
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # WEBSET COMMANDS
+    # ═══════════════════════════════════════════════════════════════════════
+
+    desc "websets SUBCOMMAND", "Manage Websets"
+    subcommand "websets", Class.new(Thor) {
+      class_option :api_key, type: :string, aliases: "-k", desc: "API key (or set EXA_API_KEY)"
+      class_option :json, type: :boolean, aliases: "-j", desc: "Output raw JSON"
+      class_option :no_color, type: :boolean, desc: "Disable colored output"
+
+      desc "list", "List all Websets"
+      method_option :limit, type: :numeric, default: 20, aliases: "-n", desc: "Max results"
+      def list
+        with_client do |client|
+          response = client.list_websets(limit: options[:limit])
+
+          if options[:json]
+            puts JSON.pretty_generate(response.raw)
+          else
+            print_websets_list(response)
+          end
+        end
+      end
+
+      desc "get ID", "Get a Webset by ID"
+      def get(id)
+        with_client do |client|
+          webset = client.get_webset(id)
+
+          if options[:json]
+            puts JSON.pretty_generate(webset.raw)
+          else
+            print_webset(webset)
+          end
+        end
+      end
+
+      desc "items ID", "List items in a Webset"
+      method_option :limit, type: :numeric, default: 20, aliases: "-n", desc: "Max results"
+      def items(id)
+        with_client do |client|
+          response = client.list_webset_items(id, limit: options[:limit])
+
+          if options[:json]
+            puts JSON.pretty_generate(response.raw)
+          else
+            print_webset_items(response)
+          end
+        end
+      end
+
+      desc "delete ID", "Delete a Webset"
+      def delete(id)
+        with_client do |client|
+          client.delete_webset(id)
+          puts color("✓ Webset #{id} deleted", :green)
+        end
+      end
+
+      private
+
+      def with_client
+        api_key = options[:api_key] || ENV["EXA_API_KEY"]
+        raise Thor::Error, "API key required. Set EXA_API_KEY or use --api-key" unless api_key
+
+        client = Exa::Client.new(api_key: api_key)
+        yield client
+      rescue Exa::Error => e
+        raise Thor::Error, color("✗ #{e.message}", :red)
+      end
+
+      def color(text, color_name)
+        return text if options[:no_color]
+
+        colors = {
+          red: "\e[31m",
+          green: "\e[32m",
+          yellow: "\e[33m",
+          blue: "\e[34m",
+          magenta: "\e[35m",
+          cyan: "\e[36m",
+          white: "\e[37m",
+          bold: "\e[1m",
+          dim: "\e[2m",
+          reset: "\e[0m"
+        }
+        "#{colors[color_name]}#{text}#{colors[:reset]}"
+      end
+
+      def print_websets_list(response)
+        header("📊 Websets (#{response.data.length})")
+        response.data.each do |ws|
+          status_color = ws.status == "idle" ? :green : :yellow
+          puts "  #{color(ws.id, :cyan)} #{color(ws.status, status_color)}"
+          puts "    #{color(ws.title || "Untitled", :white)}" if ws.title
+        end
+      end
+
+      def print_webset(webset)
+        header("📊 Webset: #{webset.id}")
+        puts "  #{color("Status:", :dim)} #{webset.status}"
+        puts "  #{color("Title:", :dim)} #{webset.title}" if webset.title
+        puts "  #{color("Created:", :dim)} #{webset.created_at}"
+        puts ""
+        if webset.searches && !webset.searches.empty?
+          puts "  #{color("Searches:", :bold)}"
+          webset.searches.each do |s|
+            puts "    #{color("•", :cyan)} #{s.query} (#{s.status})"
+          end
+        end
+      end
+
+      def print_webset_items(response)
+        header("📋 Items (#{response.data.length})")
+        response.data.each_with_index do |item, i|
+          puts "  #{color("[#{i + 1}]", :cyan)} #{item.url}"
+          if item.properties
+            props = item.properties
+            puts "    #{color("Title:", :dim)} #{props.title}" if props.title
+          end
+        end
+      end
+
+      def header(text)
+        puts ""
+        puts color("═" * 60, :dim)
+        puts color("  #{text}", :bold)
+        puts color("═" * 60, :dim)
+        puts ""
+      end
+    }
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # VERSION AND INFO
+    # ═══════════════════════════════════════════════════════════════════════
+
+    desc "version", "Show version information"
+    def version
+      puts ""
+      puts color("  ╔═══════════════════════════════════════╗", :cyan)
+      puts color("  ║", :cyan) + color("         EXA RUBY CLI", :bold) + color("               ║", :cyan)
+      puts color("  ║", :cyan) + "         Version #{Exa::VERSION}               " + color("║", :cyan)
+      puts color("  ╚═══════════════════════════════════════╝", :cyan)
+      puts ""
+      puts "  #{color("API:", :dim)} https://api.exa.ai"
+      puts "  #{color("Docs:", :dim)} https://docs.exa.ai"
+      puts ""
+    end
+
+    desc "info", "Show current configuration"
+    def info
+      api_key = options[:api_key] || ENV["EXA_API_KEY"]
+
+      puts ""
+      header("⚙️  Configuration")
+      puts "  #{color("API Key:", :dim)} #{api_key ? "#{api_key[0..7]}..." : color("Not set", :red)}"
+      puts "  #{color("Environment:", :dim)} #{ENV["EXA_API_KEY"] ? "EXA_API_KEY set" : "Not set"}"
+      puts ""
+    end
+
+    private
+
+    def with_client
+      api_key = options[:api_key] || ENV["EXA_API_KEY"]
+      raise Thor::Error, "API key required. Set EXA_API_KEY or use --api-key" unless api_key
+
+      client = Client.new(api_key: api_key)
+      yield client
+    rescue Error => e
+      raise Thor::Error, color("✗ #{e.message}", :red)
+    end
+
+    def color(text, color_name)
+      return text if options[:no_color]
+
+      colors = {
+        red: "\e[31m",
+        green: "\e[32m",
+        yellow: "\e[33m",
+        blue: "\e[34m",
+        magenta: "\e[35m",
+        cyan: "\e[36m",
+        white: "\e[37m",
+        bold: "\e[1m",
+        dim: "\e[2m",
+        reset: "\e[0m"
+      }
+      "#{colors[color_name]}#{text}#{colors[:reset]}"
+    end
+
+    def header(text)
+      puts ""
+      puts color("═" * 60, :dim)
+      puts color("  #{text}", :bold)
+      puts color("═" * 60, :dim)
+      puts ""
+    end
+
+    def print_search_results(response, query)
+      header("🔍 Search: \"#{query}\"")
+      puts "  #{color("Results:", :dim)} #{response.count}  #{color("Cost:", :dim)} $#{response.total_cost.round(4)}"
+      puts ""
+
+      response.results.each_with_index do |result, i|
+        puts "  #{color("[#{i + 1}]", :cyan)} #{color(result.title || "Untitled", :bold)}"
+        puts "      #{color(result.url, :blue)}"
+        if result.published_date
+          puts "      #{color("Published:", :dim)} #{result.published_date.strftime("%Y-%m-%d")}"
+        end
+        if result.text
+          snippet = result.text[0..200].gsub(/\s+/, " ").strip
+          puts "      #{color(snippet, :dim)}..."
+        end
+        if result.summary
+          puts "      #{color("Summary:", :green)} #{result.summary[0..150]}..."
+        end
+        puts ""
+      end
+    end
+
+    def print_answer(response, question)
+      header("💡 Answer")
+      puts "  #{color("Q:", :cyan)} #{question}"
+      puts ""
+      puts "  #{color("A:", :green)} #{response.answer}"
+      puts ""
+
+      if response.citations.any?
+        puts "  #{color("Sources:", :bold)}"
+        response.citations.each_with_index do |citation, i|
+          puts "    #{color("[#{i + 1}]", :cyan)} #{citation.title}"
+          puts "        #{color(citation.url, :blue)}"
+        end
+        puts ""
+      end
+
+      puts "  #{color("Cost:", :dim)} $#{response.total_cost.round(4)}"
+    end
+
+    def print_contents(response)
+      header("📄 Contents (#{response.results.length} pages)")
+
+      response.results.each_with_index do |page, i|
+        puts "  #{color("[#{i + 1}]", :cyan)} #{color(page.title || "Untitled", :bold)}"
+        puts "      #{color(page.url, :blue)}"
+        if page.text
+          puts ""
+          lines = page.text.split("\n").map(&:strip).reject(&:empty?).first(10)
+          lines.each { |line| puts "      #{color(line[0..80], :dim)}" }
+          puts "      ..."
+        end
+        if page.summary
+          puts ""
+          puts "      #{color("Summary:", :green)} #{page.summary[0..200]}..."
+        end
+        puts ""
+      end
+    end
+
+    def print_research_task(task)
+      status_colors = {
+        "pending" => :yellow,
+        "running" => :cyan,
+        "completed" => :green,
+        "failed" => :red,
+        "canceled" => :dim
+      }
+      status_color = status_colors[task.status] || :white
+
+      header("🔬 Research Task")
+      puts "  #{color("ID:", :dim)} #{task.research_id}"
+      puts "  #{color("Status:", :dim)} #{color(task.status.upcase, status_color)}"
+      puts "  #{color("Model:", :dim)} #{task.model}"
+
+      if task.progress
+        progress_bar = "▓" * (task.progress * 20).round + "░" * (20 - (task.progress * 20).round)
+        puts "  #{color("Progress:", :dim)} [#{color(progress_bar, :cyan)}] #{(task.progress * 100).round}%"
+      end
+
+      if task.output
+        puts ""
+        puts "  #{color("Output:", :bold)}"
+        output_lines = task.output.to_s.split("\n").first(20)
+        output_lines.each { |line| puts "    #{line[0..70]}" }
+        puts "    ..." if task.output.to_s.split("\n").length > 20
+      end
+
+      if task.error_message
+        puts ""
+        puts "  #{color("Error:", :red)} #{task.error_message}"
+      end
+    end
+
+    def print_waiting_for_research(task)
+      puts "  #{color("⏳ Waiting for research to complete...", :yellow)}"
+      puts "  #{color("ID:", :dim)} #{task.research_id}"
+    end
+
+    def wait_for_research(client, research_id)
+      loop do
+        task = client.get_research(research_id)
+
+        case task.status
+        when "completed", "failed", "canceled"
+          return task
+        when "running"
+          if task.progress
+            print "\r  #{color("Progress:", :dim)} #{(task.progress * 100).round}%    "
+          end
+        end
+
+        sleep 3
+      end
+    end
+  end
+end

data/lib/exa/client.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module Exa
+  class Client
+    include Endpoints::Search
+    include Endpoints::Contents
+    include Endpoints::FindSimilar
+    include Endpoints::Answer
+    include Endpoints::Research
+    include Endpoints::Websets
+    include Endpoints::WebsetItems
+    include Endpoints::WebsetSearches
+    include Endpoints::WebsetEnrichments
+    include Endpoints::Monitors
+    include Endpoints::Imports
+    include Endpoints::Webhooks
+    include Endpoints::Events
+
+    # @return [Configuration] Client configuration
+    attr_reader :config
+
+    # Creates a new Exa API client
+    #
+    # @param api_key [String, nil] API key (defaults to EXA_API_KEY env var)
+    # @param base_url [String, nil] Base URL for Search API
+    # @param websets_base_url [String, nil] Base URL for Websets API
+    # @param timeout [Integer, nil] Request timeout in seconds
+    # @param max_retries [Integer, nil] Maximum retry attempts
+    #
+    # @yield [Configuration] Optional configuration block
+    #
+    # @example Create client with API key
+    #   client = Exa::Client.new(api_key: "your-api-key")
+    #
+    # @example Create client with configuration block
+    #   client = Exa::Client.new do |config|
+    #     config.api_key = "your-api-key"
+    #     config.timeout = 120
+    #   end
+    def initialize(api_key: nil, base_url: nil, websets_base_url: nil, timeout: nil, max_retries: nil)
+      @config = Configuration.new
+
+      @config.api_key = api_key if api_key
+      @config.base_url = base_url if base_url
+      @config.websets_base_url = websets_base_url if websets_base_url
+      @config.timeout = timeout if timeout
+      @config.max_retries = max_retries if max_retries
+
+      yield @config if block_given?
+
+      @config.validate!
+
+      @connection = build_connection(@config.base_url)
+      @websets_connection = build_connection(@config.websets_base_url)
+    end
+
+    private
+
+    # Builds a Faraday connection with retry middleware
+    # @param base_url [String] Base URL for the connection
+    # @return [Faraday::Connection]
+    def build_connection(base_url)
+      Faraday.new(url: base_url) do |conn|
+        conn.request :json
+        conn.response :json, content_type: /\bjson$/
+
+        conn.request :retry, {
+          max: config.max_retries,
+          interval: config.retry_delay,
+          max_interval: config.max_retry_delay,
+          backoff_factor: 2,
+          retry_statuses: config.retry_statuses,
+          exceptions: config.retry_exceptions,
+          retry_block: ->(env, options, retries, exc) {
+            Exa.logger&.warn("Retrying request (attempt #{retries + 1}): #{exc.message}")
+          }
+        }
+
+        conn.options.timeout = config.timeout
+        conn.options.open_timeout = 10
+
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    # Makes a POST request to the Search API
+    # @param path [String] API endpoint path
+    # @param body [Hash] Request body
+    # @return [Hash] Parsed response
+    def post(path, body)
+      response = @connection.post(path) do |req|
+        req.headers["x-api-key"] = config.api_key
+        req.headers["Content-Type"] = "application/json"
+        req.body = body
+      end
+
+      handle_response(response)
+    end
+
+    # Makes a GET request to the Search API
+    # @param path [String] API endpoint path
+    # @param params [Hash] Query parameters
+    # @return [Hash] Parsed response
+    def get(path, params = {})
+      response = @connection.get(path) do |req|
+        req.headers["x-api-key"] = config.api_key
+        req.params = params unless params.empty?
+      end
+
+      handle_response(response)
+    end
+
+    # Makes a POST request to the Websets API
+    # @param path [String] API endpoint path
+    # @param body [Hash] Request body
+    # @return [Hash] Parsed response
+    def websets_post(path, body)
+      response = @websets_connection.post(path) do |req|
+        req.headers["x-api-key"] = config.api_key
+        req.headers["Content-Type"] = "application/json"
+        req.body = body
+      end
+
+      handle_response(response)
+    end
+
+    # Makes a GET request to the Websets API
+    # @param path [String] API endpoint path
+    # @param params [Hash] Query parameters
+    # @return [Hash] Parsed response
+    def websets_get(path, params = {})
+      response = @websets_connection.get(path) do |req|
+        req.headers["x-api-key"] = config.api_key
+        req.params = params unless params.empty?
+      end
+
+      handle_response(response)
+    end
+
+    # Makes a DELETE request to the Websets API
+    # @param path [String] API endpoint path
+    # @return [Hash] Parsed response
+    def websets_delete(path)
+      response = @websets_connection.delete(path) do |req|
+        req.headers["x-api-key"] = config.api_key
+      end
+
+      handle_response(response)
+    end
+
+    # Makes a PATCH request to the Websets API
+    # @param path [String] API endpoint path
+    # @param body [Hash] Request body
+    # @return [Hash] Parsed response
+    def websets_patch(path, body)
+      response = @websets_connection.patch(path) do |req|
+        req.headers["x-api-key"] = config.api_key
+        req.headers["Content-Type"] = "application/json"
+        req.body = body
+      end
+
+      handle_response(response)
+    end
+
+    # Handles API response and raises appropriate errors
+    # @param response [Faraday::Response] HTTP response
+    # @return [Hash] Parsed response body
+    # @raise [Exa::Error] on non-success status
+    def handle_response(response)
+      body = response.body
+
+      case response.status
+      when 200..299
+        body.is_a?(Hash) ? symbolize_keys(body) : body
+      else
+        raise Exa.error_for_status(
+          response.status,
+          response_body: body.is_a?(Hash) ? symbolize_keys(body) : nil,
+          headers: response.headers
+        )
+      end
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, "Request timed out: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    end
+
+    # Recursively symbolizes hash keys
+    # @param hash [Hash, Array, Object] Object to process
+    # @return [Hash, Array, Object] Object with symbolized keys
+    def symbolize_keys(hash)
+      case hash
+      when Hash
+        hash.each_with_object({}) do |(key, value), result|
+          result[key.to_sym] = symbolize_keys(value)
+        end
+      when Array
+        hash.map { |item| symbolize_keys(item) }
+      else
+        hash
+      end
+    end
+  end
+end