exa-ai 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a7200f1be7297291b6fa6ecddfb0e87d49a9ef570a6bb73c00b7993a459daea
-  data.tar.gz: ac3a183a8ac848007659ab36cc759780e9724c9f2fdc5159b149eaf0633402af
+  metadata.gz: 4cc4ccfc59e93013765b9289621cdb0447c4cc5bbc24e1585376ebae4b7b6ff0
+  data.tar.gz: 45cbb8655d636906d1230651896aeab9375720e655ca4d18c74f12a425ea5bd7
 SHA512:
-  metadata.gz: 1dff4bc2b63bf920a8b732c4c0f465566fab48c066d1cb9ebc1e6f7f779ee86a780225ac96197d835296c1e780ee914cde34e60cd6f83a04af805f82692d9019
-  data.tar.gz: 015e85d8c37a4731c170e57129f997a3ff4960e1464aaecc5a42c4ac45d43a475b628ee776a1c6f28d32fa74b73c1bdab5d32e9b66385cb673bce3c7ca09532a
+  metadata.gz: 4d569c43e3d9071accaeb081c6c8b51bbd0248258aa36331a8874ae17b648686bf22da5d73faee00b0a8d4a6b2b5a62dc47bcec5e4d4d7202d20870dca4ebb4e
+  data.tar.gz: 41c7f61f7de1dcc31fec84588cc2ed6287ddec597554cc18d7a9afbc0b044a790792a598ddfaef68e12174178a373081c3274e6240f6c91f908db14101fc4887

data/README.md

@@ -65,11 +65,15 @@ end
 client = Exa::Client.new
 
 # Search the web
-results = client.search("ruby programming")
+results = client.search("Ruby programming language")
 results.results.each { |item| puts "#{item['title']}: #{item['url']}" }
 
+# Find similar content
+similar = client.find_similar("https://arxiv.org/abs/2307.06435")
+similar.results.each { |item| puts item['url'] }
+
 # Get an answer to a question
-answer = client.answer("What are the latest trends in AI?")
+answer = client.answer("What is machine learning?")
 puts answer.answer
 
 # Find code examples
@@ -77,38 +81,75 @@ code = client.context("React hooks")
 puts code.response
 
 # Get page contents
-contents = client.get_contents(["https://example.com"])
+contents = client.get_contents(["https://ruby-lang.org"])
 puts contents.results.first["text"]
 ```
 
 ### Command Line
 
 ```bash
-# Search the web
-exa-ai search "ruby programming"
-
-# Answer a question
+# Core Search Commands
+exa-ai search "Ruby programming language"
+exa-ai find-similar "https://arxiv.org/abs/2307.06435"
 exa-ai answer "What is machine learning?"
-
-# Find code examples
-exa-ai context "async/await error handling"
-
-# Get page contents
-exa-ai get-contents "https://example.com"
-
-# Start a research task
-exa-ai research-start --instructions "Analyze recent ML papers" --wait
+exa-ai context "React hooks" --tokens-num 5000
+exa-ai get-contents "https://ruby-lang.org"
+
+# Research Commands
+exa-ai research-start --instructions "What species of ant are similar to honeypot ants?"
+exa-ai research-get RESEARCH_ID
+exa-ai research-list
+
+# Webset Management
+exa-ai webset-create --search '{"query":"technology companies","count":1}'
+exa-ai webset-list --limit 5
+exa-ai webset-get WEBSET_ID
+exa-ai webset-update WEBSET_ID --metadata '{"updated":"true","version":"2"}'
+exa-ai webset-delete WEBSET_ID --force
+exa-ai webset-cancel WEBSET_ID
+
+# Webset Searches
+exa-ai webset-search-create WEBSET_ID --query "Ford Mustang" --entity custom --entity-description "vintage cars"
+exa-ai webset-search-create WEBSET_ID --query "tech CEOs" --entity person --count 20
+exa-ai webset-search-create WEBSET_ID --query "Y Combinator startups" --entity company
+exa-ai webset-search-get WEBSET_ID SEARCH_ID
+exa-ai webset-search-cancel WEBSET_ID SEARCH_ID
+
+# Webset Items
+exa-ai webset-item-list WEBSET_ID
+exa-ai webset-item-get WEBSET_ID ITEM_ID
+exa-ai webset-item-delete WEBSET_ID ITEM_ID --force
+
+# Enrichments
+exa-ai enrichment-create WEBSET_ID --description "Find company email" --format text
+exa-ai enrichment-create WEBSET_ID --description "Company size category" --format options --options '[{"label":"Small (1-10)"},{"label":"Medium (11-50)"},{"label":"Large (51+)"}]'
+exa-ai enrichment-list WEBSET_ID
+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
 ```
 
 ## Features
 
 The gem provides complete access to Exa's API endpoints:
 
+### Core Search
 - **Search** — Neural and keyword search across billions of web pages
+- **Find Similar** — Discover content similar to a given URL
 - **Answer** — Generate comprehensive answers with source citations
 - **Context** — Find relevant code and documentation snippets
 - **Get Contents** — Extract full text content from web pages
-- **Research** — Start and manage long-running research tasks with AI
+
+### Research
+- **Research Tasks** — Start and manage long-running research tasks with AI
+- **Task Management** — Get status updates and list all research tasks
+
+### Websets
+- **Webset Management** — Create, update, delete, and list datasets of web pages
+- **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
 
 ## Error Handling
 

data/exe/exa-ai

@@ -8,12 +8,31 @@ require "exa-ai"
 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
@@ -29,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"
@@ -41,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
@@ -52,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"
@@ -67,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-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