exa-ai 0.3.0 → 0.4.0

data/exe/exa-ai

@@ -1,21 +1,38 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
-require "exa"
-require "exa/cli/base"
+require "exa-ai"
 
 # Global CLI interface for Exa API
 
 module ExaCLI
   AVAILABLE_COMMANDS = {
     "search" => "Search the web",
+    "find-similar" => "Find content similar to a URL",
     "answer" => "Generate an answer to a question",
     "context" => "Get code context from repositories",
     "get-contents" => "Retrieve page contents",
     "research-start" => "Start a research task",
     "research-get" => "Get research task status",
-    "research-list" => "List research tasks"
+    "research-list" => "List research tasks",
+    "webset-create" => "Create a new webset",
+    "webset-get" => "Get webset details",
+    "webset-list" => "List websets",
+    "webset-update" => "Update a webset",
+    "webset-delete" => "Delete a webset",
+    "webset-cancel" => "Cancel a webset",
+    "webset-search-create" => "Create a search in a webset",
+    "webset-search-get" => "Get webset search details",
+    "webset-search-cancel" => "Cancel a webset search",
+    "webset-item-list" => "List items in a webset",
+    "webset-item-get" => "Get webset item details",
+    "webset-item-delete" => "Delete a webset item",
+    "enrichment-create" => "Create an enrichment",
+    "enrichment-get" => "Get enrichment details",
+    "enrichment-list" => "List enrichments",
+    "enrichment-update" => "Update an enrichment",
+    "enrichment-delete" => "Delete an enrichment",
+    "enrichment-cancel" => "Cancel an enrichment"
   }.freeze
 
   def self.run
@@ -31,6 +48,8 @@ module ExaCLI
       exit 1
     when "search"
       exec File.expand_path("../exa-ai-search", __FILE__), *ARGV[1..]
+    when "find-similar"
+      exec File.expand_path("../exa-ai-find-similar", __FILE__), *ARGV[1..]
     when "answer"
       exec File.expand_path("../exa-ai-answer", __FILE__), *ARGV[1..]
     when "context"
@@ -43,6 +62,42 @@ module ExaCLI
       exec File.expand_path("../exa-ai-research-get", __FILE__), *ARGV[1..]
     when "research-list"
       exec File.expand_path("../exa-ai-research-list", __FILE__), *ARGV[1..]
+    when "webset-create"
+      exec File.expand_path("../exa-ai-webset-create", __FILE__), *ARGV[1..]
+    when "webset-get"
+      exec File.expand_path("../exa-ai-webset-get", __FILE__), *ARGV[1..]
+    when "webset-list"
+      exec File.expand_path("../exa-ai-webset-list", __FILE__), *ARGV[1..]
+    when "webset-update"
+      exec File.expand_path("../exa-ai-webset-update", __FILE__), *ARGV[1..]
+    when "webset-delete"
+      exec File.expand_path("../exa-ai-webset-delete", __FILE__), *ARGV[1..]
+    when "webset-cancel"
+      exec File.expand_path("../exa-ai-webset-cancel", __FILE__), *ARGV[1..]
+    when "webset-search-create"
+      exec File.expand_path("../exa-ai-webset-search-create", __FILE__), *ARGV[1..]
+    when "webset-search-get"
+      exec File.expand_path("../exa-ai-webset-search-get", __FILE__), *ARGV[1..]
+    when "webset-search-cancel"
+      exec File.expand_path("../exa-ai-webset-search-cancel", __FILE__), *ARGV[1..]
+    when "webset-item-list"
+      exec File.expand_path("../exa-ai-webset-item-list", __FILE__), *ARGV[1..]
+    when "webset-item-get"
+      exec File.expand_path("../exa-ai-webset-item-get", __FILE__), *ARGV[1..]
+    when "webset-item-delete"
+      exec File.expand_path("../exa-ai-webset-item-delete", __FILE__), *ARGV[1..]
+    when "enrichment-create"
+      exec File.expand_path("../exa-ai-enrichment-create", __FILE__), *ARGV[1..]
+    when "enrichment-get"
+      exec File.expand_path("../exa-ai-enrichment-get", __FILE__), *ARGV[1..]
+    when "enrichment-list"
+      exec File.expand_path("../exa-ai-enrichment-list", __FILE__), *ARGV[1..]
+    when "enrichment-update"
+      exec File.expand_path("../exa-ai-enrichment-update", __FILE__), *ARGV[1..]
+    when "enrichment-delete"
+      exec File.expand_path("../exa-ai-enrichment-delete", __FILE__), *ARGV[1..]
+    when "enrichment-cancel"
+      exec File.expand_path("../exa-ai-enrichment-cancel", __FILE__), *ARGV[1..]
     else
       print_error_for_command(ARGV[0])
       exit 1
@@ -54,11 +109,51 @@ module ExaCLI
     puts ""
     puts "Usage: exa-ai <command> [options]"
     puts ""
-    puts "Commands:"
-    AVAILABLE_COMMANDS.each do |cmd, desc|
-      puts "  #{cmd.ljust(20)} #{desc}"
-    end
-    puts ""
+
+    print_command_section("Core Search", [
+      ["search", "Search the web"],
+      ["find-similar", "Find content similar to a URL"],
+      ["answer", "Generate an answer to a question"],
+      ["context", "Get code context from repositories"],
+      ["get-contents", "Retrieve page contents"]
+    ])
+
+    print_command_section("Research", [
+      ["research-start", "Start a research task"],
+      ["research-get", "Get research task status"],
+      ["research-list", "List research tasks"]
+    ])
+
+    print_command_section("Websets", [
+      ["webset-create", "Create a new webset"],
+      ["webset-get", "Get webset details"],
+      ["webset-list", "List websets"],
+      ["webset-update", "Update a webset"],
+      ["webset-delete", "Delete a webset"],
+      ["webset-cancel", "Cancel a webset"]
+    ])
+
+    print_command_section("Webset Searches", [
+      ["webset-search-create", "Create a search in a webset"],
+      ["webset-search-get", "Get webset search details"],
+      ["webset-search-cancel", "Cancel a webset search"]
+    ])
+
+    print_command_section("Webset Items", [
+      ["webset-item-list", "List items in a webset"],
+      ["webset-item-get", "Get webset item details"],
+      ["webset-item-delete", "Delete a webset item"]
+    ])
+
+    print_command_section("Webset Enrichments", [
+      ["enrichment-create", "Create an enrichment"],
+      ["enrichment-get", "Get enrichment details"],
+      ["enrichment-list", "List enrichments"],
+      ["enrichment-update", "Update an enrichment"],
+      ["enrichment-delete", "Delete an enrichment"],
+      ["enrichment-cancel", "Cancel an enrichment"]
+    ])
+
     puts "Global Options:"
     puts "  --help, -h         Show this help message"
     puts "  --version          Show version number"
@@ -69,6 +164,14 @@ module ExaCLI
     puts "  exa-ai research-start --instructions 'Find AI papers'"
   end
 
+  def self.print_command_section(title, commands)
+    puts "#{title}:"
+    commands.each do |cmd, desc|
+      puts "  #{cmd.ljust(24)} #{desc}"
+    end
+    puts ""
+  end
+
   def self.print_error_for_command(cmd)
     return print_help if cmd.nil?
 

data/exe/exa-ai-answer

@@ -1,11 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Set up load paths
-require "bundler/setup"
-require "exa"
-require "exa/cli/base"
-require "exa/cli/formatters/answer_formatter"
+require "exa-ai"
 
 # Parse command-line arguments
 def parse_args(argv)

data/exe/exa-ai-context

@@ -1,10 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
-require "exa"
-require "exa/cli/base"
-require "exa/cli/formatters/context_formatter"
+require "exa-ai"
 
 # Parse command line arguments
 def parse_args(args)

data/exe/exa-ai-enrichment-cancel

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+webset_id = nil
+enrichment_id = nil
+api_key = nil
+output_format = "json"
+
+args = ARGV.dup
+while args.any?
+  arg = args.shift
+  case arg
+  when "--api-key"
+    api_key = args.shift
+  when "--output-format"
+    output_format = args.shift
+  when "--help", "-h"
+    puts <<~HELP
+      Usage: exa-ai enrichment-cancel <webset_id> <enrichment_id> [OPTIONS]
+
+      Cancel a running enrichment
+
+      Arguments:
+        webset_id              ID of the webset (required)
+        enrichment_id          ID of the enrichment to cancel (required)
+
+      Options:
+        --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-ai enrichment-cancel ws_123 enr_456
+        exa-ai enrichment-cancel ws_123 enr_456 --output-format pretty
+    HELP
+    exit 0
+  else
+    # First positional argument is webset_id, second is enrichment_id
+    if webset_id.nil?
+      webset_id = arg
+    elsif enrichment_id.nil?
+      enrichment_id = arg
+    else
+      $stderr.puts "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+end
+
+# Validate
+if webset_id.nil?
+  $stderr.puts "Error: webset_id argument is required"
+  $stderr.puts "Usage: exa-ai enrichment-cancel <webset_id> <enrichment_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai enrichment-cancel --help' for more information"
+  exit 1
+end
+
+if enrichment_id.nil?
+  $stderr.puts "Error: enrichment_id argument is required"
+  $stderr.puts "Usage: exa-ai enrichment-cancel <webset_id> <enrichment_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai enrichment-cancel --help' for more information"
+  exit 1
+end
+
+begin
+  # Resolve API key and format
+  api_key = Exa::CLI::Base.resolve_api_key(api_key)
+  output_format = Exa::CLI::Base.resolve_output_format(output_format)
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # Cancel enrichment
+  enrichment = client.cancel_enrichment(webset_id: webset_id, id: enrichment_id)
+
+  # Format and output
+  output = Exa::CLI::Formatters::EnrichmentFormatter.format(enrichment, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Enrichment not found: #{e.message}"
+  exit 1
+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-enrichment-create

@@ -0,0 +1,235 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+VALID_FORMATS = %w[text url options].freeze
+
+# Recursively convert hash keys from strings to symbols
+def deep_symbolize_keys(obj)
+  case obj
+  when Hash
+    obj.each_with_object({}) do |(key, value), result|
+      result[key.to_sym] = deep_symbolize_keys(value)
+    end
+  when Array
+    obj.map { |item| deep_symbolize_keys(item) }
+  else
+    obj
+  end
+end
+
+# Parse JSON string or load from file (supports @file.json syntax)
+def parse_json_or_file(value)
+  json_data = if value.start_with?("@")
+                file_path = value[1..]
+                JSON.parse(File.read(file_path))
+              else
+                JSON.parse(value)
+              end
+  deep_symbolize_keys(json_data)
+rescue JSON::ParserError => e
+  $stderr.puts "Error: Invalid JSON: #{e.message}"
+  exit 1
+rescue Errno::ENOENT => e
+  $stderr.puts "Error: File not found: #{e.message}"
+  exit 1
+end
+
+# Parse command-line arguments
+def parse_args(argv)
+  # Check for help first
+  if argv.include?("--help") || argv.include?("-h")
+    puts <<~HELP
+      Usage: exa-ai enrichment-create <webset_id> --description TEXT --format TYPE [OPTIONS]
+
+      Create a new enrichment for a webset
+
+      Required:
+        <webset_id>                Webset ID
+        --description TEXT         What to extract
+        --format TYPE              One of: #{VALID_FORMATS.join(', ')}
+
+      Options:
+        --title TEXT               Display title
+        --options JSON             Array of {label: "..."} (required if format=options, supports @file.json)
+        --instructions TEXT        Additional instructions
+        --metadata JSON            Custom metadata (supports @file.json)
+        --wait                     Wait for enrichment to complete
+        --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-ai enrichment-create ws_123 --description "Company size" --format text
+        exa-ai enrichment-create ws_123 --description "Industry" --format options --options options.json
+        exa-ai enrichment-create ws_123 --description "Website URL" --format url --wait
+    HELP
+    exit 0
+  end
+
+  args = {
+    output_format: "json",
+    api_key: nil,
+    wait: false
+  }
+
+  # First, check for positional argument (webset_id)
+  if argv.empty? || argv[0].start_with?("--")
+    return args
+  end
+
+  args[:webset_id] = argv[0]
+  i = 1
+
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--description"
+      args[:description] = argv[i + 1]
+      i += 2
+    when "--format"
+      args[:format] = argv[i + 1]
+      i += 2
+    when "--title"
+      args[:title] = argv[i + 1]
+      i += 2
+    when "--options"
+      args[:options] = parse_json_or_file(argv[i + 1])
+      i += 2
+    when "--instructions"
+      args[:instructions] = argv[i + 1]
+      i += 2
+    when "--metadata"
+      args[:metadata] = parse_json_or_file(argv[i + 1])
+      i += 2
+    when "--wait"
+      args[:wait] = 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
+    else
+      $stderr.puts "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+
+  args
+end
+
+# Main execution
+begin
+  args = parse_args(ARGV)
+
+  # Validate required parameters
+  unless args[:webset_id]
+    $stderr.puts "Error: <webset_id> is required"
+    $stderr.puts "Run 'exa-ai enrichment-create --help' for usage information"
+    exit 1
+  end
+
+  unless args[:description]
+    $stderr.puts "Error: --description is required"
+    $stderr.puts "Run 'exa-ai enrichment-create --help' for usage information"
+    exit 1
+  end
+
+  unless args[:format]
+    $stderr.puts "Error: --format is required"
+    $stderr.puts "Run 'exa-ai enrichment-create --help' for usage information"
+    exit 1
+  end
+
+  # Validate format
+  unless VALID_FORMATS.include?(args[:format])
+    $stderr.puts "Error: format must be one of: #{VALID_FORMATS.join(', ')}"
+    exit 1
+  end
+
+  # Validate options requirement for 'options' format
+  if args[:format] == "options" && !args[:options]
+    $stderr.puts "Error: --options is required when format is 'options'"
+    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 enrichment parameters
+  enrichment_params = {
+    description: args[:description],
+    format: args[:format]
+  }
+  enrichment_params[:title] = args[:title] if args[:title]
+  enrichment_params[:options] = args[:options] if args[:options]
+  enrichment_params[:instructions] = args[:instructions] if args[:instructions]
+  enrichment_params[:metadata] = args[:metadata] if args[:metadata]
+
+  # Create enrichment
+  enrichment = client.create_enrichment(webset_id: args[:webset_id], **enrichment_params)
+
+  # If --wait flag is set, poll until enrichment is complete
+  if args[:wait]
+    $stderr.print "Creating enrichment... "
+
+    begin
+      final_enrichment = Exa::CLI::Polling.poll(max_duration: 300, initial_delay: 2, max_delay: 10) do
+        current = client.get_enrichment(webset_id: args[:webset_id], id: enrichment.id)
+
+        case current.status
+        when "pending"
+          $stderr.print "⏳"
+        when "running"
+          $stderr.print "⚙️"
+        end
+
+        done = current.completed?
+        { done: done, result: current, status: current.status }
+      end
+
+      $stderr.puts " COMPLETED"
+      enrichment = final_enrichment
+
+    rescue Exa::CLI::Polling::TimeoutError
+      $stderr.puts "\nWarning: Enrichment did not complete within timeout"
+      $stderr.puts "Enrichment ID: #{enrichment.id}"
+      $stderr.puts "Check status with: exa-ai enrichment-get #{args[:webset_id]} #{enrichment.id}"
+    end
+  end
+
+  # Format and output result
+  output = Exa::CLI::Formatters::EnrichmentFormatter.format(enrichment, 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/exe/exa-ai-enrichment-delete

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+webset_id = nil
+enrichment_id = nil
+force = false
+api_key = nil
+output_format = "json"
+
+args = ARGV.dup
+while args.any?
+  arg = args.shift
+  case arg
+  when "--force"
+    force = true
+  when "--api-key"
+    api_key = args.shift
+  when "--output-format"
+    output_format = args.shift
+  when "--help", "-h"
+    puts <<~HELP
+      Usage: exa-ai enrichment-delete <webset_id> <enrichment_id> [OPTIONS]
+
+      Delete an enrichment
+
+      Arguments:
+        webset_id              ID of the webset (required)
+        enrichment_id          ID of the enrichment to delete (required)
+
+      Options:
+        --force                Skip confirmation prompt
+        --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-ai enrichment-delete ws_123 enr_456
+        exa-ai enrichment-delete ws_123 enr_456 --force
+    HELP
+    exit 0
+  else
+    # First positional argument is webset_id, second is enrichment_id
+    if webset_id.nil?
+      webset_id = arg
+    elsif enrichment_id.nil?
+      enrichment_id = arg
+    else
+      $stderr.puts "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+end
+
+# Validate
+if webset_id.nil?
+  $stderr.puts "Error: webset_id argument is required"
+  $stderr.puts "Usage: exa-ai enrichment-delete <webset_id> <enrichment_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai enrichment-delete --help' for more information"
+  exit 1
+end
+
+if enrichment_id.nil?
+  $stderr.puts "Error: enrichment_id argument is required"
+  $stderr.puts "Usage: exa-ai enrichment-delete <webset_id> <enrichment_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai enrichment-delete --help' for more information"
+  exit 1
+end
+
+begin
+  # Resolve API key and format
+  api_key = Exa::CLI::Base.resolve_api_key(api_key)
+  output_format = Exa::CLI::Base.resolve_output_format(output_format)
+
+  # Confirm deletion unless --force is used
+  unless force
+    $stderr.print "Delete enrichment #{enrichment_id} from webset #{webset_id}? (y/N): "
+    response = $stdin.gets.chomp.downcase
+    unless response == "y" || response == "yes"
+      $stderr.puts "Cancelled"
+      exit 0
+    end
+  end
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # Delete enrichment
+  result = client.delete_enrichment(webset_id: webset_id, id: enrichment_id)
+
+  # Format and output
+  output = Exa::CLI::Formatters::EnrichmentFormatter.format(result, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Enrichment not found: #{e.message}"
+  exit 1
+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