exa-ai 0.3.0 → 0.4.0

data/exe/exa-ai-webset-cancel

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+webset_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 webset-cancel <webset_id> [OPTIONS]
+
+      Cancel a running webset
+
+      Arguments:
+        webset_id              ID of the webset 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 webset-cancel ws_abc123
+        exa-ai webset-cancel ws_abc123 --output-format pretty
+    HELP
+    exit 0
+  else
+    # First positional argument is webset_id
+    if webset_id.nil?
+      webset_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 webset-cancel <webset_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai webset-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 webset
+  webset = client.cancel_webset(webset_id)
+
+  # Format and output
+  output = Exa::CLI::Formatters::WebsetFormatter.format(webset, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Webset 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-webset-create

@@ -0,0 +1,192 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# 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)
+  args = {
+    output_format: "json",
+    api_key: nil,
+    wait: false
+  }
+
+  i = 0
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--search"
+      args[:search] = parse_json_or_file(argv[i + 1])
+      i += 2
+    when "--enrichments"
+      args[:enrichments] = parse_json_or_file(argv[i + 1])
+      i += 2
+    when "--exclude"
+      args[:exclude] = parse_json_or_file(argv[i + 1])
+      i += 2
+    when "--external-id"
+      args[:external_id] = 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
+    when "--help", "-h"
+      puts <<~HELP
+        Usage: exa-ai webset-create --search JSON [OPTIONS]
+
+        Create a new webset with search criteria
+
+        Required:
+          --search JSON              Search configuration (supports @file.json)
+
+        Options:
+          --enrichments JSON         Array of enrichment configs (supports @file.json)
+          --exclude JSON             Array of exclude configs (supports @file.json)
+          --external-id ID           External identifier for the webset
+          --metadata JSON            Custom metadata (supports @file.json)
+          --wait                     Wait for webset to reach idle status
+          --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 webset-create --search '{"query":"AI startups","count":10}'
+          exa-ai webset-create --search @search.json --enrichments @enrichments.json
+          exa-ai webset-create --search @search.json --wait
+      HELP
+      exit 0
+    else
+      $stderr.puts "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+
+  args
+end
+
+# Main execution
+begin
+  args = parse_args(ARGV)
+
+  # Validate required parameters
+  unless args[:search]
+    $stderr.puts "Error: --search is required"
+    $stderr.puts "Run 'exa-ai webset-create --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 webset parameters
+  webset_params = { search: args[:search] }
+  webset_params[:enrichments] = args[:enrichments] if args[:enrichments]
+  webset_params[:exclude] = args[:exclude] if args[:exclude]
+  webset_params[:externalId] = args[:external_id] if args[:external_id]
+  webset_params[:metadata] = args[:metadata] if args[:metadata]
+
+  # Create webset
+  webset = client.create_webset(**webset_params)
+
+  # If --wait flag is set, poll until webset is idle
+  if args[:wait]
+    $stderr.print "Creating webset... "
+
+    begin
+      final_webset = Exa::CLI::Polling.poll(max_duration: 300, initial_delay: 2, max_delay: 10) do
+        current_webset = client.get_webset(webset.id)
+
+        # Show progress indicator
+        case current_webset.status
+        when "pending"
+          $stderr.print "⏳"
+        when "running"
+          $stderr.print "⚙️"
+        end
+
+        done = current_webset.idle?
+        { done: done, result: current_webset, status: current_webset.status }
+      end
+
+      $stderr.puts " #{final_webset.status.upcase}"
+      webset = final_webset
+
+    rescue Exa::CLI::Polling::TimeoutError
+      $stderr.puts "\nWarning: Webset creation did not complete within timeout"
+      $stderr.puts "Webset ID: #{webset.id}"
+      $stderr.puts "Check status with: exa-ai webset-get #{webset.id}"
+    end
+  end
+
+  # Format and output result
+  output = Exa::CLI::Formatters::WebsetFormatter.format(webset, 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-webset-delete

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+webset_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 webset-delete <webset_id> [OPTIONS]
+
+      Delete a webset
+
+      Arguments:
+        webset_id              ID of the webset 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 webset-delete ws_abc123
+        exa-ai webset-delete ws_abc123 --force
+    HELP
+    exit 0
+  else
+    # First positional argument is webset_id
+    if webset_id.nil?
+      webset_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 webset-delete <webset_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai webset-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 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 webset
+  result = client.delete_webset(webset_id)
+
+  # Format and output
+  output = Exa::CLI::Formatters::WebsetFormatter.format(result, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Webset 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-webset-get

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+webset_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 webset-get <webset_id> [OPTIONS]
+
+      Retrieve details for a webset
+
+      Arguments:
+        webset_id              ID of the webset to retrieve (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 webset-get ws_abc123
+        exa-ai webset-get ws_abc123 --output-format pretty
+    HELP
+    exit 0
+  else
+    # First positional argument is webset_id
+    if webset_id.nil?
+      webset_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 webset-get <webset_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai webset-get --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)
+
+  # Get webset
+  webset = client.get_webset(webset_id)
+
+  # Format and output
+  output = Exa::CLI::Formatters::WebsetFormatter.format(webset, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Webset not found: #{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}"
+  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-webset-item-delete

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+webset_id = nil
+item_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 webset-item-delete <webset_id> <item_id> [OPTIONS]
+
+      Delete a webset item
+
+      Arguments:
+        webset_id              ID of the webset (required)
+        item_id                ID of the item (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 webset-item-delete ws_123 item_456
+        exa-ai webset-item-delete ws_123 item_456 --output-format text
+    HELP
+    exit 0
+  else
+    # First positional argument is webset_id, second is item_id
+    if webset_id.nil?
+      webset_id = arg
+    elsif item_id.nil?
+      item_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 webset-item-delete <webset_id> <item_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai webset-item-delete --help' for more information"
+  exit 1
+end
+
+if item_id.nil?
+  $stderr.puts "Error: item_id argument is required"
+  $stderr.puts "Usage: exa-ai webset-item-delete <webset_id> <item_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai webset-item-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)
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # Delete item
+  result = client.delete_item(webset_id: webset_id, id: item_id)
+
+  # Format and output
+  if result
+    case output_format
+    when :text
+      puts "Item #{item_id} deleted successfully"
+    when :pretty
+      puts JSON.pretty_generate({ success: true, item_id: item_id })
+    else
+      puts JSON.generate({ success: true, item_id: item_id })
+    end
+  end
+
+rescue Exa::NotFound => e
+  $stderr.puts "Item not found: #{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}"
+  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-webset-item-get

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+webset_id = nil
+item_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 webset-item-get <webset_id> <item_id> [OPTIONS]
+
+      Get details of a webset item
+
+      Arguments:
+        webset_id              ID of the webset (required)
+        item_id                ID of the item (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 webset-item-get ws_123 item_456
+        exa-ai webset-item-get ws_123 item_456 --output-format pretty
+        exa-ai webset-item-get ws_123 item_456 --output-format text
+    HELP
+    exit 0
+  else
+    # First positional argument is webset_id, second is item_id
+    if webset_id.nil?
+      webset_id = arg
+    elsif item_id.nil?
+      item_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 webset-item-get <webset_id> <item_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai webset-item-get --help' for more information"
+  exit 1
+end
+
+if item_id.nil?
+  $stderr.puts "Error: item_id argument is required"
+  $stderr.puts "Usage: exa-ai webset-item-get <webset_id> <item_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai webset-item-get --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)
+
+  # Get item
+  item = client.get_item(webset_id: webset_id, id: item_id)
+
+  # Format and output
+  output = Exa::CLI::Formatters::WebsetItemFormatter.format(item, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Item not found: #{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}"
+  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