exa-ai 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f9d0670c6b642073a66e32d8ecdd46702931e4b17f66bd6970b976a51ec5c56
-  data.tar.gz: 2f9126068c6e0672cf7ac67b2d18e188396dbd3785285c4683b2deb99b97d14d
+  metadata.gz: 4f55e9efe411da4b9eaf3018791aa7819fc8872c69e32369627014594eb23670
+  data.tar.gz: 0d074ce4bb6eaa2902b80fe5df239be717f182c3703ebfcd6c45944de7cd1245
 SHA512:
-  metadata.gz: 70e7be7fd10d14c69dd1b3125e453c9aa5a7233fb5f618233b8e3af0b42c7546a02b7cb34b9a20f9bb25b0f235f5b6fcbecefbaa5c33393720a47200b1443d93
-  data.tar.gz: 3ef41b82e7126b4f875a3acddeaf046293a75e2d6cae3a03ea1c3ab46dc5ba9d8ade004add9e5f588876b7cdc4bf7a6c4f27d6be08a42b31e29a7ec3a987dd4f
+  metadata.gz: 732d915bf1eadcabff77ae2dcf7c573d426021bea3dac1fe0b2013958dde5a53129c62675ff66279b5204233c970b988ea72ad29ef94bb4b5219cba55910145b
+  data.tar.gz: f4f73347c282e2ebb2209afd42a02e1fb253e9d682a5959ce1cd2ea27519f132c156fb897bbd3177d24f4b88bd06874afd76b81bf70ccb225dcb3ad64ec6249b

data/README.md

@@ -128,6 +128,15 @@ exa-ai enrichment-get WEBSET_ID ENRICHMENT_ID
 exa-ai enrichment-update WEBSET_ID ENRICHMENT_ID --description "Updated description"
 exa-ai enrichment-delete WEBSET_ID ENRICHMENT_ID --force
 exa-ai enrichment-cancel WEBSET_ID ENRICHMENT_ID
+
+# Webset Imports
+exa-ai webset-import-create companies.csv --count 100 --title "My Companies" --format csv --entity-type company
+exa-ai webset-import-create data.csv --count 50 --title "Tech Startups" --format csv --entity-type company --csv-identifier 0
+exa-ai webset-import-create import.csv --count 100 --title "Import" --format csv --entity-type company --metadata '{"source":"crm"}' --quiet
+exa-ai webset-import-list
+exa-ai webset-import-get IMPORT_ID
+exa-ai webset-import-update IMPORT_ID --title "Updated Title"
+exa-ai webset-import-delete IMPORT_ID
 ```
 
 ## Features
@@ -150,6 +159,7 @@ The gem provides complete access to Exa's API endpoints:
 - **Webset Searches** — Run searches within websets and manage search tasks
 - **Webset Items** — List, retrieve, and manage individual items in websets
 - **Enrichments** — Create and manage AI-powered data enrichment tasks on websets
+- **Imports** — Upload CSV files to import external data into websets
 
 ## Error Handling
 

data/exe/exa-ai

@@ -32,7 +32,19 @@ module ExaCLI
     "enrichment-list" => "List enrichments",
     "enrichment-update" => "Update an enrichment",
     "enrichment-delete" => "Delete an enrichment",
-    "enrichment-cancel" => "Cancel an enrichment"
+    "enrichment-cancel" => "Cancel an enrichment",
+    "import-create" => "Create a new import",
+    "import-list" => "List imports",
+    "import-get" => "Get import details",
+    "import-update" => "Update an import",
+    "import-delete" => "Delete an import",
+    "monitor-create" => "Create a webset monitor",
+    "monitor-get" => "Get monitor details",
+    "monitor-list" => "List monitors",
+    "monitor-update" => "Update a monitor",
+    "monitor-delete" => "Delete a monitor",
+    "monitor-runs-list" => "List monitor runs",
+    "monitor-runs-get" => "Get monitor run details"
   }.freeze
 
   def self.run
@@ -98,6 +110,30 @@ module ExaCLI
       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..]
+    when "import-create"
+      exec File.expand_path("../exa-ai-import-create", __FILE__), *ARGV[1..]
+    when "import-list"
+      exec File.expand_path("../exa-ai-import-list", __FILE__), *ARGV[1..]
+    when "import-get"
+      exec File.expand_path("../exa-ai-import-get", __FILE__), *ARGV[1..]
+    when "import-update"
+      exec File.expand_path("../exa-ai-import-update", __FILE__), *ARGV[1..]
+    when "import-delete"
+      exec File.expand_path("../exa-ai-import-delete", __FILE__), *ARGV[1..]
+    when "monitor-create"
+      exec File.expand_path("../exa-ai-monitor-create", __FILE__), *ARGV[1..]
+    when "monitor-get"
+      exec File.expand_path("../exa-ai-monitor-get", __FILE__), *ARGV[1..]
+    when "monitor-list"
+      exec File.expand_path("../exa-ai-monitor-list", __FILE__), *ARGV[1..]
+    when "monitor-update"
+      exec File.expand_path("../exa-ai-monitor-update", __FILE__), *ARGV[1..]
+    when "monitor-delete"
+      exec File.expand_path("../exa-ai-monitor-delete", __FILE__), *ARGV[1..]
+    when "monitor-runs-list"
+      exec File.expand_path("../exa-ai-monitor-runs-list", __FILE__), *ARGV[1..]
+    when "monitor-runs-get"
+      exec File.expand_path("../exa-ai-monitor-runs-get", __FILE__), *ARGV[1..]
     else
       print_error_for_command(ARGV[0])
       exit 1
@@ -154,6 +190,24 @@ module ExaCLI
       ["enrichment-cancel", "Cancel an enrichment"]
     ])
 
+    print_command_section("Imports", [
+      ["import-create", "Create a new import"],
+      ["import-list", "List imports"],
+      ["import-get", "Get import details"],
+      ["import-update", "Update an import"],
+      ["import-delete", "Delete an import"]
+    ])
+
+    print_command_section("Webset Monitors", [
+      ["monitor-create", "Create a webset monitor"],
+      ["monitor-get", "Get monitor details"],
+      ["monitor-list", "List monitors"],
+      ["monitor-update", "Update a monitor"],
+      ["monitor-delete", "Delete a monitor"],
+      ["monitor-runs-list", "List monitor runs"],
+      ["monitor-runs-get", "Get monitor run details"]
+    ])
+
     puts "Global Options:"
     puts "  --help, -h         Show this help message"
     puts "  --version          Show version number"

data/exe/exa-ai-enrichment-create

@@ -51,9 +51,7 @@ def parse_args(argv)
         --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)
@@ -91,15 +89,9 @@ def parse_args(argv)
     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
@@ -170,9 +162,7 @@ begin
     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

data/exe/exa-ai-import-create

@@ -0,0 +1,253 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+VALID_FORMATS = Exa::Constants::Websets::IMPORT_FORMATS
+VALID_ENTITY_TYPES = Exa::Constants::Websets::ENTITY_TYPES
+
+# 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 import-create FILE [OPTIONS]
+
+      Create a new import and upload external data file
+
+      Arguments:
+        FILE                      Path to the CSV file to upload
+
+      Required:
+        --count N                 Number of entities in the import
+        --title TEXT              Display title
+        --format TYPE             Format type (default: csv, options: #{VALID_FORMATS.join(', ')})
+        --entity-type TYPE        Entity type (options: #{VALID_ENTITY_TYPES.join(', ')})
+
+      Options:
+        --entity-description TXT  Description for custom entity type (required with --entity-type custom)
+        --csv-identifier N        CSV column identifier (0-indexed)
+        --metadata JSON           Custom metadata (supports @file.json)
+        --quiet                   Suppress normal output (only show errors)
+        --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 import-create data.csv --count 100 --title "My Companies" --format csv --entity-type company
+        exa-ai import-create companies.csv --count 50 --title "Tech Startups" --format csv --entity-type company --csv-identifier 0
+        exa-ai import-create import.csv --count 100 --title "Import" --format csv --entity-type company --metadata '{"source":"crm"}' --quiet
+    HELP
+    exit 0
+  end
+
+  # First argument should be the file path
+  if argv.empty? || argv[0].start_with?("--")
+    $stderr.puts "Error: FILE argument is required"
+    $stderr.puts "Run 'exa-ai import-create --help' for usage information"
+    exit 1
+  end
+
+  args = {
+    file_path: argv[0],
+    output_format: "json",
+    api_key: nil,
+    format: "csv",
+    quiet: false
+  }
+
+  i = 1  # Start after the file path
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--count"
+      args[:count] = argv[i + 1].to_i
+      i += 2
+    when "--title"
+      args[:title] = argv[i + 1]
+      i += 2
+    when "--format"
+      args[:format] = argv[i + 1]
+      i += 2
+    when "--entity-type"
+      args[:entity_type] = argv[i + 1]
+      i += 2
+    when "--entity-description"
+      args[:entity_description] = argv[i + 1]
+      i += 2
+    when "--csv-identifier"
+      args[:csv_identifier] = argv[i + 1].to_i
+      i += 2
+    when "--metadata"
+      args[:metadata] = parse_json_or_file(argv[i + 1])
+      i += 2
+    when "--quiet"
+      args[:quiet] = 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[:count]
+    $stderr.puts "Error: --count is required"
+    $stderr.puts "Run 'exa-ai import-create --help' for usage information"
+    exit 1
+  end
+
+  unless args[:title]
+    $stderr.puts "Error: --title is required"
+    $stderr.puts "Run 'exa-ai import-create --help' for usage information"
+    exit 1
+  end
+
+  unless args[:entity_type]
+    $stderr.puts "Error: --entity-type is required"
+    $stderr.puts "Run 'exa-ai import-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 entity type
+  unless VALID_ENTITY_TYPES.include?(args[:entity_type])
+    $stderr.puts "Error: entity-type must be one of: #{VALID_ENTITY_TYPES.join(', ')}"
+    exit 1
+  end
+
+  # Validate entity-description for custom entity type
+  if args[:entity_type] == "custom"
+    unless args[:entity_description]
+      $stderr.puts "Error: --entity-description is required when --entity-type is 'custom'"
+      $stderr.puts "Run 'exa-ai import-create --help' for usage information"
+      exit 1
+    end
+  elsif args[:entity_description]
+    $stderr.puts "Warning: --entity-description is only used with --entity-type custom (ignoring)"
+  end
+
+  # Validate file exists
+  unless File.exist?(args[:file_path])
+    $stderr.puts "Error: File not found: #{args[:file_path]}"
+    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 import parameters
+  entity = { type: args[:entity_type] }
+  entity[:description] = args[:entity_description] if args[:entity_description]
+
+  import_params = {
+    file_path: args[:file_path],
+    count: args[:count],
+    title: args[:title],
+    format: args[:format],
+    entity: entity
+  }
+  import_params[:metadata] = args[:metadata] if args[:metadata]
+
+  # Add CSV config if csv_identifier provided
+  if args[:csv_identifier]
+    import_params[:csv] = { identifier: args[:csv_identifier] }
+  end
+
+  # Show upload message unless quiet
+  unless args[:quiet]
+    file_size = File.size(args[:file_path])
+    $stderr.puts "Uploading #{args[:file_path]} (#{file_size} bytes)..."
+  end
+
+  # Upload import
+  import = client.upload_import(**import_params)
+
+  # Show success message unless quiet
+  unless args[:quiet]
+    $stderr.puts "Upload complete. Import ID: #{import.id}"
+  end
+
+  # Format and output result (unless quiet)
+  unless args[:quiet]
+    output = Exa::CLI::Formatters::ImportFormatter.format(import, output_format)
+    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-import-delete

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+import_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 import-delete <import_id> [OPTIONS]
+
+      Delete an import
+
+      Arguments:
+        import_id              ID of the import to delete (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 import-delete imp_123
+        exa-ai import-delete imp_123 --output-format text
+    HELP
+    exit 0
+  else
+    # First positional argument is import_id
+    if import_id.nil?
+      import_id = arg
+    else
+      $stderr.puts "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+end
+
+# Validate
+if import_id.nil?
+  $stderr.puts "Error: import_id argument is required"
+  $stderr.puts "Usage: exa-ai import-delete <import_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai import-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 import
+  import = client.delete_import(import_id)
+
+  # Format and output
+  output = Exa::CLI::Formatters::ImportFormatter.format(import, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Import 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-import-get

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+import_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 import-get <import_id> [OPTIONS]
+
+      Get details of a specific import
+
+      Arguments:
+        import_id              ID of the import (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 import-get imp_123
+        exa-ai import-get imp_123 --output-format text
+    HELP
+    exit 0
+  else
+    # First positional argument is import_id
+    if import_id.nil?
+      import_id = arg
+    else
+      $stderr.puts "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+end
+
+# Validate
+if import_id.nil?
+  $stderr.puts "Error: import_id argument is required"
+  $stderr.puts "Usage: exa-ai import-get <import_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai import-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 import
+  import = client.get_import(import_id)
+
+  # Format and output
+  output = Exa::CLI::Formatters::ImportFormatter.format(import, output_format)
+  puts output
+
+rescue Exa::NotFound => e
+  $stderr.puts "Import 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-import-list

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse arguments
+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 import-list [OPTIONS]
+
+      List all imports
+
+      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 import-list
+        exa-ai import-list --output-format text
+    HELP
+    exit 0
+  else
+    $stderr.puts "Unknown option: #{arg}"
+    exit 1
+  end
+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)
+
+  # List imports
+  collection = client.list_imports
+
+  # Format and output
+  output = Exa::CLI::Formatters::ImportFormatter.format_collection(collection, output_format)
+  puts output
+
+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