exa-ai 0.1.0

data/exe/exa-ai-research-start

@@ -0,0 +1,175 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Set up load paths
+require "bundler/setup"
+require "exa"
+
+# Parse command-line arguments
+def parse_args(argv)
+  args = {
+    output_format: "json",
+    api_key: nil,
+    events: false,
+    wait: false
+  }
+
+  i = 0
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--instructions"
+      args[:instructions] = argv[i + 1]
+      i += 2
+    when "--model"
+      args[:model] = argv[i + 1]
+      i += 2
+    when "--output-schema"
+      args[:output_schema] = argv[i + 1]
+      i += 2
+    when "--wait"
+      args[:wait] = true
+      i += 1
+    when "--events"
+      args[:events] = true
+      i += 1
+    when "--api-key"
+      args[:api_key] = argv[i + 1]
+      i += 2
+    when "--output-format"
+      args[:output_format] = argv[i + 1]
+      i += 2
+    when "--help", "-h"
+      puts <<~HELP
+        Usage: exa-api research-start --instructions "TEXT" [OPTIONS]
+
+        Start a research task using Exa AI
+
+        Options:
+          --instructions TEXT   Research instructions (required)
+          --model MODEL         Model to use (e.g., gpt-4, gpt-3.5-turbo)
+          --output-schema JSON  JSON schema string for structured output
+          --wait                Wait for task to complete (polls until done)
+          --events              Include event log in output (only with --wait)
+          --api-key KEY         Exa API key (or set EXA_API_KEY env var)
+          --output-format FMT   Output format: json, pretty, or text (default: json)
+          --help, -h            Show this help message
+
+        Examples:
+          exa-api research-start --instructions "Find Ruby performance tips"
+          exa-api research-start --instructions "Analyze AI trends" --wait --events
+          exa-api research-start --instructions "Summarize papers" --model gpt-4 --wait
+          exa-api research-start --instructions "Find stats" --output-schema '{"type":"object"}'
+      HELP
+      exit 0
+    else
+      i += 1
+    end
+  end
+
+  args
+end
+
+# Main execution
+begin
+  args = parse_args(ARGV)
+
+  # Validate instructions
+  if args[:instructions].nil? || args[:instructions].empty?
+    $stderr.puts "Error: --instructions flag is required"
+    $stderr.puts "Run 'exa-api research-start --help' for usage information"
+    exit 1
+  end
+
+  # Resolve API key
+  api_key = Exa::CLI::Base.resolve_api_key(args[:api_key])
+
+  # Resolve output format
+  output_format = Exa::CLI::Base.resolve_output_format(args[:output_format])
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # Prepare research parameters
+  research_params = { instructions: args[:instructions] }
+  research_params[:model] = args[:model] if args[:model]
+
+  # Parse output_schema as JSON if provided
+  if args[:output_schema]
+    begin
+      research_params[:output_schema] = JSON.parse(args[:output_schema])
+    rescue JSON::ParserError => e
+      $stderr.puts "Error: Invalid JSON in --output-schema: #{e.message}"
+      exit 1
+    end
+  end
+
+  # Start research task
+  task = client.research_start(**research_params)
+
+  # If --wait flag is set, poll until task completes
+  if args[:wait]
+    $stderr.print "Starting research task... "
+
+    begin
+      final_task = Exa::CLI::Polling.poll(max_duration: 300, initial_delay: 2, max_delay: 10) do
+        # Get current task status
+        current_task = client.research_get(task.research_id, events: args[:events])
+
+        # Show progress indicator
+        case current_task.status
+        when "pending"
+          $stderr.print "⏳"
+        when "running"
+          $stderr.print "⚙️"
+        end
+
+        # Check if done
+        done = current_task.finished?
+
+        { done: done, result: current_task, status: current_task.status }
+      end
+
+      $stderr.puts " #{final_task.status.upcase}"
+
+      # Format and output final result
+      output = Exa::CLI::Formatters::ResearchFormatter.format_task(final_task, output_format, show_events: args[:events])
+      puts output
+
+      # Exit with error code if task failed
+      exit 1 if final_task.failed?
+
+    rescue Exa::CLI::Polling::TimeoutError => e
+      $stderr.puts "\nError: Task did not complete within timeout period (5 minutes)"
+      $stderr.puts "Task ID: #{task.research_id}"
+      $stderr.puts "You can check the status later with: exa-api research-get #{task.research_id}"
+      exit 1
+    end
+  else
+    # Just return the initial task (with status "pending")
+    output = Exa::CLI::Formatters::ResearchFormatter.format_task(task, output_format, show_events: false)
+    puts output
+  end
+
+rescue Exa::ConfigurationError => e
+  $stderr.puts "Configuration error: #{e.message}"
+  exit 1
+rescue Exa::Unauthorized => e
+  $stderr.puts "Authentication error: #{e.message}"
+  $stderr.puts "Check your API key (set EXA_API_KEY or use --api-key)"
+  exit 1
+rescue Exa::ClientError => e
+  $stderr.puts "Client error: #{e.message}"
+  exit 1
+rescue Exa::ServerError => e
+  $stderr.puts "Server error: #{e.message}"
+  $stderr.puts "The Exa API may be experiencing issues. Please try again later."
+  exit 1
+rescue Exa::Error => e
+  $stderr.puts "Error: #{e.message}"
+  exit 1
+rescue StandardError => e
+  $stderr.puts "Unexpected error: #{e.message}"
+  $stderr.puts e.backtrace.first(5) if ENV["DEBUG"]
+  exit 1
+end

data/exe/exa-ai-search

@@ -0,0 +1,134 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Set up load paths
+require "bundler/setup"
+require "exa"
+
+# Parse command-line arguments
+def parse_args(argv)
+  args = {
+    output_format: "json",
+    api_key: nil
+  }
+
+  # Extract query (first non-flag argument)
+  query_parts = []
+  i = 0
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--num-results"
+      args[:num_results] = argv[i + 1].to_i
+      i += 2
+    when "--type"
+      args[:type] = argv[i + 1]
+      i += 2
+    when "--include-domains"
+      args[:include_domains] = argv[i + 1].split(",").map(&:strip)
+      i += 2
+    when "--exclude-domains"
+      args[:exclude_domains] = argv[i + 1].split(",").map(&:strip)
+      i += 2
+    when "--use-autoprompt"
+      args[:use_autoprompt] = true
+      i += 1
+    when "--api-key"
+      args[:api_key] = argv[i + 1]
+      i += 2
+    when "--output-format"
+      args[:output_format] = argv[i + 1]
+      i += 2
+    when "--help", "-h"
+      puts <<~HELP
+        Usage: exa-api search QUERY [OPTIONS]
+
+        Search the web using Exa AI
+
+        Arguments:
+          QUERY                 Search query (required)
+
+        Options:
+          --num-results N       Number of results to return (default: 10)
+          --type TYPE           Search type: keyword, neural, or auto (default: auto)
+          --include-domains D   Comma-separated list of domains to include
+          --exclude-domains D   Comma-separated list of domains to exclude
+          --use-autoprompt      Use Exa's autoprompt feature
+          --api-key KEY         Exa API key (or set EXA_API_KEY env var)
+          --output-format FMT   Output format: json, pretty, or text (default: json)
+          --help, -h            Show this help message
+
+        Examples:
+          exa-api search "ruby programming"
+          exa-api search "machine learning" --num-results 5 --type keyword
+          exa-api search "AI research" --include-domains arxiv.org,scholar.google.com
+          exa-api search "tutorials" --output-format pretty
+      HELP
+      exit 0
+    else
+      query_parts << arg
+      i += 1
+    end
+  end
+
+  args[:query] = query_parts.join(" ")
+  args
+end
+
+# Main execution
+begin
+  args = parse_args(ARGV)
+
+  # Validate query
+  if args[:query].nil? || args[:query].empty?
+    $stderr.puts "Error: Query is required"
+    $stderr.puts "Run 'exa-api search --help' for usage information"
+    exit 1
+  end
+
+  # Resolve API key
+  api_key = Exa::CLI::Base.resolve_api_key(args[:api_key])
+
+  # Resolve output format
+  output_format = Exa::CLI::Base.resolve_output_format(args[:output_format])
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # Prepare search parameters
+  search_params = {}
+  search_params[:num_results] = args[:num_results] if args[:num_results]
+  search_params[:type] = args[:type] if args[:type]
+  search_params[:include_domains] = args[:include_domains] if args[:include_domains]
+  search_params[:exclude_domains] = args[:exclude_domains] if args[:exclude_domains]
+  search_params[:use_autoprompt] = args[:use_autoprompt] if args[:use_autoprompt]
+
+  # Execute search
+  result = client.search(args[:query], **search_params)
+
+  # Format and output result
+  output = Exa::CLI::Formatters::SearchFormatter.format(result, output_format)
+  puts output
+
+rescue Exa::ConfigurationError => e
+  $stderr.puts "Configuration error: #{e.message}"
+  exit 1
+rescue Exa::Unauthorized => e
+  $stderr.puts "Authentication error: #{e.message}"
+  $stderr.puts "Check your API key (set EXA_API_KEY or use --api-key)"
+  exit 1
+rescue Exa::ClientError => e
+  $stderr.puts "Client error: #{e.message}"
+  exit 1
+rescue Exa::ServerError => e
+  $stderr.puts "Server error: #{e.message}"
+  $stderr.puts "The Exa API may be experiencing issues. Please try again later."
+  exit 1
+rescue Exa::Error => e
+  $stderr.puts "Error: #{e.message}"
+  exit 1
+rescue StandardError => e
+  $stderr.puts "Unexpected error: #{e.message}"
+  $stderr.puts e.backtrace.first(5) if ENV["DEBUG"]
+  exit 1
+end

data/lib/exa/cli/base.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    class Base
+      # Resolve API key from flag or environment variable
+      # Flag takes precedence over environment variable
+      def self.resolve_api_key(flag_value)
+        return flag_value if flag_value && !flag_value.empty?
+
+        env_key = ENV["EXA_API_KEY"]
+        return env_key if env_key && !env_key.empty?
+
+        raise ConfigurationError,
+              "Missing API key. Set EXA_API_KEY environment variable or use --api-key flag"
+      end
+
+      # Resolve and validate output format
+      # Valid formats: json, pretty, text
+      # Defaults to json
+      def self.resolve_output_format(flag_value)
+        format = (flag_value || "json").downcase
+        valid_formats = %w[json pretty text]
+
+        return format if valid_formats.include?(format)
+
+        raise ConfigurationError,
+              "Invalid output format: #{format}. Valid formats: #{valid_formats.join(', ')}"
+      end
+
+      # Build a client instance with the given API key
+      def self.build_client(api_key, **options)
+        Client.new(api_key: api_key, **options)
+      end
+
+      # Format output data based on format type
+      def self.format_output(data, format)
+        case format
+        when "json"
+          JSON.pretty_generate(data.is_a?(Hash) ? data : { result: data })
+        when "pretty"
+          data.inspect
+        when "text"
+          data.to_s
+        else
+          data.to_s
+        end
+      end
+    end
+  end
+end

data/lib/exa/cli/error_handler.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    class ErrorHandler
+      def self.handle_error(error, command_name = nil)
+        case error
+        when ConfigurationError
+          handle_configuration_error(error, command_name)
+        when Unauthorized
+          handle_unauthorized_error(error, command_name)
+        when ClientError
+          handle_client_error(error, command_name)
+        when ServerError
+          handle_server_error(error, command_name)
+        else
+          handle_generic_error(error, command_name)
+        end
+      end
+
+      private
+
+      def self.handle_configuration_error(error, command_name)
+        $stderr.puts "❌ Configuration Error"
+        $stderr.puts ""
+        $stderr.puts error.message
+        $stderr.puts ""
+        $stderr.puts "Solutions:"
+        $stderr.puts "  1. Set the EXA_API_KEY environment variable:"
+        $stderr.puts "     export EXA_API_KEY='your-api-key'"
+        $stderr.puts ""
+        $stderr.puts "  2. Or pass it as a flag:"
+        $stderr.puts "     #{command_name} ... --api-key YOUR_API_KEY" if command_name
+        $stderr.puts ""
+        $stderr.puts "Get your API key at: https://dashboard.exa.ai"
+      end
+
+      def self.handle_unauthorized_error(error, command_name)
+        $stderr.puts "❌ Authentication Error"
+        $stderr.puts ""
+        $stderr.puts "Your API key is invalid or has expired."
+        $stderr.puts ""
+        if error.response&.fetch("error", nil)
+          $stderr.puts "Details: #{error.response['error']}"
+          $stderr.puts ""
+        end
+        $stderr.puts "Solutions:"
+        $stderr.puts "  1. Verify your API key is correct"
+        $stderr.puts "  2. Check if your API key has expired or been revoked"
+        $stderr.puts "  3. Get a new key from: https://dashboard.exa.ai"
+      end
+
+      def self.handle_client_error(error, command_name)
+        $stderr.puts "❌ Request Error"
+        $stderr.puts ""
+        $stderr.puts error.message
+        $stderr.puts ""
+
+        # Try to extract status code from response
+        status = error.response&.fetch("status", "unknown") if error.response.is_a?(Hash)
+
+        case status
+        when 400
+          $stderr.puts "This was a bad request. Please check your arguments."
+        when 404
+          $stderr.puts "The requested resource was not found."
+        when 422
+          $stderr.puts "The request data was invalid. Check your parameters."
+        when 429
+          $stderr.puts "You've exceeded the rate limit. Please wait before trying again."
+        end
+
+        $stderr.puts ""
+        $stderr.puts "Run '#{command_name} --help' for usage information." if command_name
+      end
+
+      def self.handle_server_error(error, command_name)
+        $stderr.puts "❌ Server Error"
+        $stderr.puts ""
+        $stderr.puts "The Exa API encountered an error:"
+        $stderr.puts error.message
+        $stderr.puts ""
+        $stderr.puts "Solutions:"
+        $stderr.puts "  1. Try again in a moment"
+        $stderr.puts "  2. Check API status: https://status.exa.ai"
+        $stderr.puts "  3. Contact support if the error persists"
+      end
+
+      def self.handle_generic_error(error, command_name)
+        $stderr.puts "❌ Error"
+        $stderr.puts ""
+        $stderr.puts error.message
+        $stderr.puts ""
+        $stderr.puts "Run '#{command_name} --help' for usage information." if command_name
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class AnswerFormatter
+        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 = []
+          output << "Answer:"
+          output << "-" * 60
+
+          # Handle both string and structured (hash) answers
+          if result.answer.is_a?(Hash)
+            output << JSON.pretty_generate(result.answer)
+          else
+            output << result.answer
+          end
+          output << ""
+
+          if result.citations && !result.citations.empty?
+            output << "Citations:"
+            output << "-" * 60
+            result.citations.each_with_index do |citation, idx|
+              output << "[#{idx + 1}] #{citation['title']}"
+              output << "    URL:      #{citation['url']}"
+              output << "    Author:   #{citation['author']}" if citation['author']
+              output << "    Date:     #{citation['publishedDate']}" if citation['publishedDate']
+              output << ""
+            end
+          end
+
+          output << "Cost: $#{result.cost_dollars}" if result.cost_dollars
+
+          output.join("\n")
+        end
+
+        def self.format_text(result)
+          # Handle both string and structured (hash) answers
+          if result.answer.is_a?(Hash)
+            JSON.pretty_generate(result.answer)
+          else
+            result.answer
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class ContentsFormatter
+        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 |content, idx|
+            output << "=== Content #{idx + 1} ==="
+            output << "URL:   #{content['url']}"
+            output << "Title: #{content['title']}"
+            output << ""
+            output << "Text:"
+            output << "-" * 40
+            text = content['text'] || content['content'] || "(No text available)"
+            # Truncate long text to first 500 chars
+            truncated = text.length > 500 ? text[0..500] + "..." : text
+            output << truncated
+            output << ""
+          end
+          output.join("\n")
+        end
+
+        def self.format_text(result)
+          output = []
+          result.results.each do |content|
+            output << "#{content['url']}\n#{content['text'] || '(No text available)'}"
+          end
+          output.join("\n\n")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Exa
+  module CLI
+    module Formatters
+      class ContextFormatter
+        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 = []
+          output << "=" * 60
+          output << "Query: #{result.query}"
+          output << "=" * 60
+          output << ""
+          output << "Metadata:"
+          output << "  Request ID:   #{result.request_id}"
+          output << "  Results:      #{result.results_count}"
+          output << "  Cost:         $#{result.cost_dollars}"
+          output << "  Search Time:  #{result.search_time}ms"
+          output << ""
+          output << "Code Context:"
+          output << "-" * 60
+          output << result.response.to_s
+          output.join("\n")
+        end
+
+        def self.format_text(result)
+          output = []
+          output << "Query: #{result.query}"
+          output << "Request ID: #{result.request_id}"
+          output << "Results: #{result.results_count}"
+          output << "Cost: $#{result.cost_dollars}"
+          output << "Search Time: #{result.search_time}ms"
+          output << ""
+          output << "Code Context:"
+          output << "-" * 40
+          output << result.response.to_s
+          output.join("\n")
+        end
+      end
+    end
+  end
+end