exa-ai 0.3.1 → 0.4.1

data/exe/exa-ai-webset-search-create

@@ -0,0 +1,233 @@
+#!/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
+  }
+
+  # First positional argument is webset_id
+  webset_id_found = false
+
+  i = 0
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--query"
+      args[:query] = argv[i + 1]
+      i += 2
+    when "--count"
+      args[:count] = argv[i + 1].to_i
+      i += 2
+    when "--entity"
+      args[:entity] = argv[i + 1]
+      i += 2
+    when "--entity-description"
+      args[:entity_description] = argv[i + 1]
+      i += 2
+    when "--criteria"
+      args[:criteria] = parse_json_or_file(argv[i + 1])
+      i += 2
+    when "--exclude"
+      args[:exclude] = parse_json_or_file(argv[i + 1])
+      i += 2
+    when "--scope"
+      args[:scope] = parse_json_or_file(argv[i + 1])
+      i += 2
+    when "--recall"
+      args[:recall] = true
+      i += 1
+    when "--behavior"
+      behavior = argv[i + 1]
+      unless ["override", "append"].include?(behavior)
+        $stderr.puts "Error: Behavior must be 'override' or 'append'"
+        exit 1
+      end
+      args[:behavior] = behavior
+      i += 2
+    when "--metadata"
+      args[:metadata] = parse_json_or_file(argv[i + 1])
+      i += 2
+    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-search-create <webset_id> [OPTIONS]
+
+        Create a new search within a webset
+
+        Arguments:
+          webset_id                ID of the webset (required)
+
+        Options:
+          --query QUERY            Search query (required)
+          --count N                Number of results to find
+          --entity TYPE            Entity type: person, company, article, research_paper, custom
+          --entity-description TXT Description for custom entity type (required with --entity custom)
+          --criteria JSON          Search criteria array (supports @file.json)
+          --exclude JSON           Items to exclude from results (supports @file.json)
+          --scope JSON             Limit search to specific sources (supports @file.json)
+          --recall                 Estimate total available results
+          --behavior TYPE          "override" or "append" (default: override)
+          --metadata JSON          Custom metadata (supports @file.json)
+          --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:
+          # Basic search
+          exa-ai webset-search-create ws_123 --query "AI startups"
+
+          # Search with entity type
+          exa-ai webset-search-create ws_123 --query "tech CEOs" --entity person
+          exa-ai webset-search-create ws_123 --query "Silicon Valley firms" --entity company
+
+          # Search with custom entity type
+          exa-ai webset-search-create ws_123 --query "Ford Mustang" \\
+            --entity custom --entity-description "vintage cars"
+
+          # Other options
+          exa-ai webset-search-create ws_123 --query "machine learning" --count 50
+          exa-ai webset-search-create ws_123 --query "research" --behavior append --recall
+      HELP
+      exit 0
+    else
+      # First positional argument is webset_id
+      unless webset_id_found
+        args[:webset_id] = arg
+        webset_id_found = true
+      else
+        $stderr.puts "Unknown option: #{arg}"
+        exit 1
+      end
+      i += 1
+    end
+  end
+
+  args
+end
+
+# Main execution
+begin
+  args = parse_args(ARGV)
+
+  # Validate required parameters
+  unless args[:webset_id]
+    $stderr.puts "Error: webset_id argument is required"
+    $stderr.puts "Run 'exa-ai webset-search-create --help' for usage information"
+    exit 1
+  end
+
+  unless args[:query]
+    $stderr.puts "Error: --query is required"
+    $stderr.puts "Run 'exa-ai webset-search-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)
+
+  # Build entity parameter from --entity and --entity-description
+  entity = nil
+  if args[:entity]
+    # Build entity hash from string type
+    entity = { type: args[:entity] }
+    if args[:entity] == "custom"
+      unless args[:entity_description]
+        $stderr.puts "Error: --entity-description is required when --entity is 'custom'"
+        exit 1
+      end
+      entity[:description] = args[:entity_description]
+    elsif args[:entity_description]
+      $stderr.puts "Warning: --entity-description is only used with --entity custom (ignoring)"
+    end
+  end
+
+  # Prepare search parameters
+  search_params = { query: args[:query] }
+  search_params[:count] = args[:count] if args[:count]
+  search_params[:entity] = entity if entity
+  search_params[:criteria] = args[:criteria] if args[:criteria]
+  search_params[:exclude] = args[:exclude] if args[:exclude]
+  search_params[:scope] = args[:scope] if args[:scope]
+  search_params[:recall] = args[:recall] if args[:recall]
+  search_params[:behavior] = args[:behavior] if args[:behavior]
+  search_params[:metadata] = args[:metadata] if args[:metadata]
+
+  # Create search
+  search = client.create_webset_search(webset_id: args[:webset_id], **search_params)
+
+  # Format and output result
+  output = Exa::CLI::Formatters::SearchFormatter.format(search, 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::NotFound => e
+  $stderr.puts "Webset not found: #{e.message}"
+  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-search-get

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

@@ -0,0 +1,139 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+require "json"
+
+# Parse arguments
+webset_id = nil
+metadata = nil
+api_key = nil
+output_format = "json"
+
+# 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
+
+# Helper to parse JSON string or load from file
+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
+
+args = ARGV.dup
+while args.any?
+  arg = args.shift
+  case arg
+  when "--metadata"
+    metadata = parse_json_or_file(args.shift)
+  when "--api-key"
+    api_key = args.shift
+  when "--output-format"
+    output_format = args.shift
+  when "--help", "-h"
+    puts <<~HELP
+      Usage: exa-ai webset-update <webset_id> [OPTIONS]
+
+      Update a webset's metadata
+
+      Arguments:
+        webset_id              ID of the webset to update (required)
+
+      Options:
+        --metadata JSON        Custom metadata to update (supports @file.json)
+        --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-update ws_abc123 --metadata '{"project":"Q1-2025"}'
+        exa-ai webset-update ws_abc123 --metadata @metadata.json
+        exa-ai webset-update ws_abc123 --metadata '{"tags":["important"]}' --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 required arguments
+if webset_id.nil?
+  $stderr.puts "Error: webset_id argument is required"
+  $stderr.puts "Usage: exa-ai webset-update <webset_id> [OPTIONS]"
+  $stderr.puts "Try 'exa-ai webset-update --help' for more information"
+  exit 1
+end
+
+if metadata.nil?
+  $stderr.puts "Error: --metadata is required"
+  $stderr.puts "Try 'exa-ai webset-update --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)
+
+  # Update webset
+  webset = client.update_webset(webset_id, metadata: metadata)
+
+  # 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/lib/exa/cli/formatters/enrichment_formatter.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class EnrichmentFormatter
+        def self.format(enrichment, output_format)
+          case output_format
+          when "json"
+            JSON.generate(enrichment.to_h)
+          when "pretty"
+            JSON.pretty_generate(enrichment.to_h)
+          when "text"
+            format_as_text(enrichment)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_collection(collection, output_format)
+          case output_format
+          when "json"
+            JSON.generate(collection.to_h)
+          when "pretty"
+            JSON.pretty_generate(collection.to_h)
+          when "text"
+            format_collection_as_text(collection)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_as_text(enrichment)
+          lines = []
+          lines << "Enrichment: #{enrichment.id}"
+          lines << "Webset: #{enrichment.webset_id}" if enrichment.webset_id
+          lines << "Status: #{enrichment.status}"
+          lines << "Title: #{enrichment.title}" if enrichment.title
+          lines << "Description: #{enrichment.description}" if enrichment.description
+          lines << "Format: #{enrichment.format}" if enrichment.format
+
+          if enrichment.options && !enrichment.options.empty?
+            lines << "\nOptions:"
+            enrichment.options.each do |option|
+              lines << "  - #{option['label']}" if option['label']
+            end
+          end
+
+          lines << "Created: #{enrichment.created_at}" if enrichment.created_at
+          lines << "Updated: #{enrichment.updated_at}" if enrichment.updated_at
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_text
+
+        def self.format_collection_as_text(collection)
+          lines = ["Enrichments (#{collection.data.length} items):"]
+          collection.data.each do |enr|
+            lines << "\n  #{enr['id']}"
+            lines << "  Status: #{enr['status']}"
+            lines << "  Title: #{enr['title']}" if enr['title']
+          end
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_text
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class WebsetFormatter
+        def self.format(webset, output_format)
+          case output_format
+          when "json"
+            JSON.generate(webset.to_h)
+          when "pretty"
+            JSON.pretty_generate(webset.to_h)
+          when "text"
+            format_as_text(webset)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_collection(collection, output_format)
+          case output_format
+          when "json"
+            JSON.generate(collection.to_h)
+          when "pretty"
+            JSON.pretty_generate(collection.to_h)
+          when "text"
+            format_collection_as_text(collection)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_as_text(webset)
+          lines = []
+          lines << "Webset: #{webset.id}"
+          lines << "Status: #{webset.status}"
+          lines << "Created: #{webset.created_at}" if webset.created_at
+          lines << "Updated: #{webset.updated_at}" if webset.updated_at
+
+          if webset.searches && !webset.searches.empty?
+            lines << "\nSearches:"
+            webset.searches.each do |search|
+              lines << "  - #{search['query']}" if search['query']
+            end
+          end
+
+          if webset.enrichments && !webset.enrichments.empty?
+            lines << "\nEnrichments: #{webset.enrichments.length}"
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_text
+
+        def self.format_collection_as_text(collection)
+          lines = ["Websets (#{collection.data.length} items):"]
+          collection.data.each do |ws|
+            lines << "\n  #{ws['id']}"
+            lines << "  Status: #{ws['status']}"
+            lines << "  Created: #{ws['createdAt']}" if ws['createdAt']
+          end
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_text
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Exa
+  module CLI
+    module Formatters
+      class WebsetItemFormatter
+        def self.format(item, output_format)
+          case output_format
+          when "json"
+            JSON.generate(item)
+          when "pretty"
+            JSON.pretty_generate(item)
+          when "text"
+            format_as_text(item)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_collection(items, output_format)
+          case output_format
+          when "json"
+            JSON.generate(items)
+          when "pretty"
+            JSON.pretty_generate(items)
+          when "text"
+            format_collection_as_text(items)
+          else
+            raise ArgumentError, "Unknown output format: #{output_format}"
+          end
+        end
+
+        def self.format_as_text(item)
+          lines = []
+          lines << "Item: #{item['id']}"
+          lines << "URL: #{item['url']}" if item['url']
+          lines << "Title: #{item['title']}" if item['title']
+          lines << "Status: #{item['status']}" if item['status']
+          lines << "Created: #{item['createdAt']}" if item['createdAt']
+          lines << "Updated: #{item['updatedAt']}" if item['updatedAt']
+
+          if item['entity']
+            lines << "\nEntity:"
+            lines << "  Type: #{item['entity']['type']}" if item['entity']['type']
+            lines << "  Name: #{item['entity']['name']}" if item['entity']['name']
+          end
+
+          lines.join("\n")
+        end
+        private_class_method :format_as_text
+
+        def self.format_collection_as_text(items)
+          lines = ["Items (#{items.length} total):"]
+          items.each_with_index do |item, idx|
+            lines << "\n#{idx + 1}. #{item['id']}"
+            lines << "   URL: #{item['url']}" if item['url']
+            lines << "   Title: #{item['title']}" if item['title']
+            lines << "   Status: #{item['status']}" if item['status']
+            if item['entity'] && item['entity']['name']
+              lines << "   Entity: #{item['entity']['name']}"
+            end
+          end
+          lines.join("\n")
+        end
+        private_class_method :format_collection_as_text
+      end
+    end
+  end
+end