exa-ai 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4458cc74fb6924d5e7e57300ba28ae1db399d0d89bf68495b1203f5fe29d73d2
-  data.tar.gz: 00b7f59be62aad198438660acdec2e1a2e3c86539bd1a462c4ea03f45c08a87b
+  metadata.gz: 1a5fb5324a2ae6dfb4380d91bce7d8d41a3f3b14e471e43bf254a5e763ef0113
+  data.tar.gz: 539a8486ec5e639c4f43fd3e81071ff0f1e5951b3e42c31bc1915d8e00d1df36
 SHA512:
-  metadata.gz: b45e4d6a35d33910e9ce4b154b1b432efba13732b9c237ab94da5962944fae65bf3562a426dc9fa9c18af8c820e8db5d1a4ae3417605d171a136de2d01f149db
-  data.tar.gz: 98f082e62eeef3cf7851abcda1cdd61ee5edd548c2cd0d5a65b7645510248ebd0a2274b743e83b7ff354e1ebb4016a92ab83e8a4f93300c255d298fdb9a2683b
+  metadata.gz: dd87558e4a7428b56d9e513478e9d02f88cc845bf7d14fa9c0822e4042dd73d100e686ce3c151bc755d680cc283017311ba2b5109eedfcffef03bd99d4457700
+  data.tar.gz: 49eac46680edc76e6bfa9a2032b9871841095e052cc6e21eac174675f4060149ddc3a690cdd5b6506f39dbaf621f124d7a288f227f99d1637979729e23d63042

data/README.md

@@ -2,6 +2,57 @@
 
 Ruby client for the Exa.ai API. Search and analyze web content using neural search, question answering, code discovery, and research automation.
 
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Error Handling](#error-handling)
+- [Documentation](#documentation)
+- [Development](#development)
+- [Testing](#testing)
+- [Support](#support)
+- [License](#license)
+
+## Requirements
+
+- **Ruby 3.0.0 or higher**
+
+### Installing Ruby on macOS
+
+If you're setting up on a fresh macOS laptop, the easiest way to get Ruby 3.x is through Homebrew:
+
+**1. Install Homebrew** (if not already installed):
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+**2. Install Ruby:**
+
+```bash
+brew install ruby
+```
+
+**3. Add Homebrew's Ruby to your PATH** (follow the instructions Homebrew prints, usually adding to `~/.zshrc`):
+
+```bash
+echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**4. Verify installation:**
+
+```bash
+ruby -v  # Should show Ruby 3.x
+```
+
+**Alternative: Using a version manager**
+
+For managing multiple Ruby versions, consider [rbenv](https://github.com/rbenv/rbenv) or [asdf](https://asdf-vm.com/).
+
 ## Installation
 
 Add to your Gemfile:
@@ -32,6 +83,20 @@ Get your API key from [dashboard.exa.ai](https://dashboard.exa.ai).
 export EXA_API_KEY="your-api-key-here"
 ```
 
+**Using .env file (local development)**
+
+Create a `.env` file in your project root:
+
+```bash
+# Copy the example file
+cp .env.example .env
+
+# Edit .env and add your API key
+EXA_API_KEY=your-api-key-here
+```
+
+The gem automatically loads `.env` files in development when the `dotenv` gem is installed.
+
 **Ruby Code**
 
 ```ruby
@@ -193,6 +258,46 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
 - Code conventions
 - Building and releasing
 
+## Testing
+
+### Running Tests
+
+```bash
+# Run unit tests (integration tests skip by default)
+bundle exec rake test
+
+# Run integration tests (VCR-based, no real API calls)
+RUN_INTEGRATION_TESTS=true bundle exec rake test
+
+# Run CLI integration tests (real API calls, requires explicit opt-in)
+RUN_CLI_INTEGRATION_TESTS=true bundle exec rake test
+```
+
+### Integration Tests
+
+**Integration tests are skipped by default** to prevent accidental API calls.
+
+**VCR-based integration tests (`RUN_INTEGRATION_TESTS`):**
+- Use recorded HTTP interactions (VCR cassettes)
+- No real API calls when replaying cassettes
+- Set `RUN_INTEGRATION_TESTS=true` to run them
+- Safe to run during development
+
+**CLI integration tests (`RUN_CLI_INTEGRATION_TESTS`):**
+- Make real API calls through shell commands
+- Consume Exa's concurrent search quota
+- Set `RUN_CLI_INTEGRATION_TESTS=true` AND `EXA_API_KEY` to run them
+- **Warning:** Can exhaust API quota and trigger rate limits lasting 1-2 days
+
+**When to run integration tests:**
+- VCR tests: Anytime (safe, no real API calls)
+- CLI tests: Only before releases or when testing CLI-specific functionality
+
+**Test Coverage:**
+- **Unit tests** - Fast, no API calls, always run
+- **VCR integration tests** - Replay cassettes, skipped by default
+- **CLI integration tests** - Real API calls via shell, skipped by default
+
 ## Support
 
 - **Documentation**: https://docs.exa.ai

data/exe/exa-ai-answer

@@ -9,7 +9,8 @@ def parse_args(argv)
     output_format: "json",
     api_key: nil,
     text: false,
-    stream: false
+    stream: false,
+    skip_citations: false
   }
 
   # Extract query (first non-flag argument)
@@ -24,6 +25,9 @@ def parse_args(argv)
     when "--stream"
       args[:stream] = true
       i += 1
+    when "--skip-citations", "--no-citations"
+      args[:skip_citations] = true
+      i += 1
     when "--output-schema"
       args[:output_schema] = argv[i + 1]
       i += 2
@@ -48,6 +52,8 @@ def parse_args(argv)
         Options:
           --stream              Stream answer chunks in real-time
           --text                Include full text content from sources
+          --skip-citations      Remove citations from output (saves tokens)
+          --no-citations        Alias for --skip-citations
           --output-schema JSON  JSON schema for structured output
           --system-prompt TEXT  System prompt to guide answer generation
           --api-key KEY         Exa API key (or set EXA_API_KEY env var)
@@ -123,7 +129,7 @@ begin
   else
     # Non-streaming mode - collect full response and format
     result = client.answer(args[:query], **answer_params)
-    output = Exa::CLI::Formatters::AnswerFormatter.format(result, output_format)
+    output = Exa::CLI::Formatters::AnswerFormatter.format(result, output_format, skip_citations: args[:skip_citations])
     puts output
     $stdout.flush
   end

data/exe/exa-ai-enrichment-create

@@ -3,7 +3,7 @@
 
 require "exa-ai"
 
-VALID_FORMATS = %w[text url options].freeze
+VALID_FORMATS = Exa::Constants::Websets::ENRICHMENT_FORMATS
 
 # Recursively convert hash keys from strings to symbols
 def deep_symbolize_keys(obj)
@@ -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

@@ -56,6 +56,7 @@ def parse_args(argv)
         --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)
@@ -102,6 +103,9 @@ def parse_args(argv)
     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
@@ -161,6 +165,17 @@ begin
     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]}"
@@ -177,12 +192,15 @@ begin
   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: { type: args[:entity_type] }
+    entity: entity
   }
   import_params[:metadata] = args[:metadata] if args[:metadata]
 

data/exe/exa-ai-search

@@ -2,189 +2,61 @@
 # frozen_string_literal: true
 
 require "exa-ai"
-
-# Parse command-line arguments
-def parse_args(argv)
-  args = {
-    output_format: "json",
-    api_key: nil
-  }
-
-  # Extract query (first non-flag argument)
-  query_parts = []
-  i = 0
-  while i < argv.length
-    arg = argv[i]
-    case arg
-    when "--num-results"
-      args[:num_results] = argv[i + 1].to_i
-      i += 2
-    when "--type"
-      search_type = argv[i + 1]
-      valid_types = ["fast", "deep", "keyword", "auto"]
-      unless valid_types.include?(search_type)
-        $stderr.puts "Error: Search type must be one of: #{valid_types.join(', ')}"
-        exit 1
-      end
-      args[:type] = search_type
-      i += 2
-    when "--category"
-      category = argv[i + 1]
-      valid_categories = ["company", "research paper", "news", "pdf", "github", "tweet", "personal site", "linkedin profile", "financial report"]
-      unless valid_categories.include?(category)
-        $stderr.puts "Error: Category must be one of: #{valid_categories.map { |c| "\"#{c}\"" }.join(', ')}"
-        exit 1
-      end
-      args[:category] = category
-      i += 2
-    when "--include-domains"
-      args[:include_domains] = argv[i + 1].split(",").map(&:strip)
-      i += 2
-    when "--exclude-domains"
-      args[:exclude_domains] = argv[i + 1].split(",").map(&:strip)
-      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 "--linkedin"
-      linkedin_type = argv[i + 1]
-      valid_types = ["company", "person", "all"]
-      unless valid_types.include?(linkedin_type)
-        $stderr.puts "Error: LinkedIn type must be one of: #{valid_types.join(', ')}"
-        exit 1
-      end
-      args[:linkedin] = linkedin_type
-      i += 2
-    when "--start-published-date"
-      args[:start_published_date] = argv[i + 1]
-      i += 2
-    when "--end-published-date"
-      args[:end_published_date] = argv[i + 1]
-      i += 2
-    when "--start-crawl-date"
-      args[:start_crawl_date] = argv[i + 1]
-      i += 2
-    when "--end-crawl-date"
-      args[:end_crawl_date] = argv[i + 1]
-      i += 2
-    when "--include-text"
-      args[:include_text] ||= []
-      args[:include_text] << argv[i + 1]
-      i += 2
-    when "--exclude-text"
-      args[:exclude_text] ||= []
-      args[:exclude_text] << argv[i + 1]
-      i += 2
-    when "--text"
-      args[:text] = true
-      i += 1
-    when "--text-max-characters"
-      args[:text_max_characters] = argv[i + 1].to_i
-      i += 2
-    when "--include-html-tags"
-      args[:include_html_tags] = true
-      i += 1
-    when "--summary"
-      args[:summary] = true
-      i += 1
-    when "--summary-query"
-      args[:summary_query] = argv[i + 1]
-      i += 2
-    when "--summary-schema"
-      schema_arg = argv[i + 1]
-      args[:summary_schema] = if schema_arg.start_with?("@")
-                               JSON.parse(File.read(schema_arg[1..]))
-                             else
-                               JSON.parse(schema_arg)
-                             end
-      i += 2
-    when "--context"
-      args[:context] = true
-      i += 1
-    when "--context-max-characters"
-      args[:context_max_characters] = argv[i + 1].to_i
-      i += 2
-    when "--subpages"
-      args[:subpages] = argv[i + 1].to_i
-      i += 2
-    when "--subpage-target"
-      args[:subpage_target] ||= []
-      args[:subpage_target] << argv[i + 1]
-      i += 2
-    when "--links"
-      args[:links] = argv[i + 1].to_i
-      i += 2
-    when "--image-links"
-      args[:image_links] = argv[i + 1].to_i
-      i += 2
-    when "--help", "-h"
-      puts <<~HELP
-        Usage: exa-ai search QUERY [OPTIONS]
-
-        Search the web using Exa AI
-
-        Arguments:
-          QUERY                 Search query (required)
-
-        Options:
-          --num-results N              Number of results to return (default: 10)
-          --type TYPE                  Search type: fast, deep, keyword, or auto (default: fast)
-          --category CAT               Focus on specific data category
-                                       Options: "company", "research paper", "news", "pdf",
-                                       "github", "tweet", "personal site", "linkedin profile",
-                                       "financial report"
-          --include-domains D          Comma-separated list of domains to include
-          --exclude-domains D          Comma-separated list of domains to exclude
-          --start-published-date DATE  Filter by published date (ISO 8601 format)
-          --end-published-date DATE    Filter by published date (ISO 8601 format)
-          --start-crawl-date DATE      Filter by crawl date (ISO 8601 format)
-          --end-crawl-date DATE        Filter by crawl date (ISO 8601 format)
-          --include-text PHRASE        Include results with exact phrase (repeatable)
-          --exclude-text PHRASE        Exclude results with exact phrase (repeatable)
-
-        Content Extraction:
-          --text                       Include full webpage text
-          --text-max-characters N      Max characters for webpage text
-          --include-html-tags          Include HTML tags in text extraction
-          --summary                    Include AI-generated summary
-          --summary-query PROMPT       Custom prompt for summary generation
-          --summary-schema FILE        JSON schema for summary structure (@file syntax)
-          --context                    Format results as context for LLM RAG
-          --context-max-characters N   Max characters for context string
-          --subpages N                 Number of subpages to crawl
-          --subpage-target PHRASE      Subpage target phrases (repeatable)
-          --links N                    Number of links to extract per result
-          --image-links N              Number of image links to extract
-
-        General Options:
-          --linkedin TYPE              Search LinkedIn: company, person, or all
-          --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 search "ruby programming"
-          exa-ai search "machine learning" --num-results 5 --type deep
-          exa-ai search "Latest LLM research" --category "research paper"
-          exa-ai search "AI startups" --category company
-          exa-ai search "Anthropic" --linkedin company
-          exa-ai search "Dario Amodei" --linkedin person
-          exa-ai search "AI" --linkedin all
-          exa-ai search "AI research" --include-domains arxiv.org,scholar.google.com
-          exa-ai search "tutorials" --output-format pretty
-      HELP
-      exit 0
-    else
-      query_parts << arg
-      i += 1
-    end
-  end
-
-  args[:query] = query_parts.join(" ")
-  args
+require_relative "../lib/exa/cli/search_parser"
+
+def print_help
+  puts <<~HELP
+    Usage: exa-ai search QUERY [OPTIONS]
+
+    Search the web using Exa AI
+
+    Arguments:
+      QUERY                 Search query (required)
+
+    Options:
+      --num-results N              Number of results to return (default: 10)
+      --type TYPE                  Search type: fast, deep, keyword, or auto (default: fast)
+      --category CAT               Focus on specific data category
+                                   Options: "company", "research paper", "news", "pdf",
+                                   "github", "tweet", "personal site", "financial report",
+                                   "people"
+      --include-domains D          Comma-separated list of domains to include
+      --exclude-domains D          Comma-separated list of domains to exclude
+      --start-published-date DATE  Filter by published date (ISO 8601 format)
+      --end-published-date DATE    Filter by published date (ISO 8601 format)
+      --start-crawl-date DATE      Filter by crawl date (ISO 8601 format)
+      --end-crawl-date DATE        Filter by crawl date (ISO 8601 format)
+      --include-text PHRASE        Include results with exact phrase (repeatable)
+      --exclude-text PHRASE        Exclude results with exact phrase (repeatable)
+
+    Content Extraction:
+      --text                       Include full webpage text
+      --text-max-characters N      Max characters for webpage text
+      --include-html-tags          Include HTML tags in text extraction
+      --summary                    Include AI-generated summary
+      --summary-query PROMPT       Custom prompt for summary generation
+      --summary-schema FILE        JSON schema for summary structure (@file syntax)
+      --context                    Format results as context for LLM RAG
+      --context-max-characters N   Max characters for context string
+      --subpages N                 Number of subpages to crawl
+      --subpage-target PHRASE      Subpage target phrases (repeatable)
+      --links N                    Number of links to extract per result
+      --image-links N              Number of image links to extract
+
+    General 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 search "ruby programming"
+      exa-ai search "machine learning" --num-results 5 --type deep
+      exa-ai search "Latest LLM research" --category "research paper"
+      exa-ai search "AI startups" --category company
+      exa-ai search "Dario Amodei" --category people
+      exa-ai search "AI research" --include-domains arxiv.org,scholar.google.com
+      exa-ai search "tutorials" --output-format pretty
+  HELP
 end
 
 # Build contents parameter from extracted flags
@@ -238,15 +110,15 @@ end
 
 # Main execution
 begin
-  args = parse_args(ARGV)
-
-  # Validate query
-  if args[:query].nil? || args[:query].empty?
-    $stderr.puts "Error: Query is required"
-    $stderr.puts "Run 'exa-ai search --help' for usage information"
-    exit 1
+  # Handle help flag
+  if ARGV.include?("--help") || ARGV.include?("-h")
+    print_help
+    exit 0
   end
 
+  # Parse command-line arguments
+  args = Exa::CLI::SearchParser.parse(ARGV)
+
   # Resolve API key
   api_key = Exa::CLI::Base.resolve_api_key(args[:api_key])
 
@@ -272,17 +144,8 @@ begin
   contents = build_contents(args)
   search_params.merge!(contents) if contents
 
-  # Execute search based on LinkedIn type
-  result = case args[:linkedin]
-           when "company"
-             client.linkedin_company(args[:query], **search_params)
-           when "person"
-             client.linkedin_person(args[:query], **search_params)
-           when "all"
-             client.search(args[:query], includeDomains: ["linkedin.com"], **search_params)
-           else
-             client.search(args[:query], **search_params)
-           end
+  # Execute search
+  result = client.search(args[:query], **search_params)
 
   # Format and output result
   output = Exa::CLI::Formatters::SearchFormatter.format(result, output_format)

data/exe/exa-ai-webset-create

@@ -80,32 +80,51 @@ def parse_args(argv)
         Create a new webset from search criteria or an import
 
         Required (choose one):
-          --search JSON              Search configuration (supports @file.json)
-          --import ID                Import or webset ID to create webset from
-                                     (accepts import_* or webset_* IDs)
+          --search JSON              Search configuration as JSON (supports @file.json)
+                                     Format: {"query":"...","count":10,"scope":[...]}
+                                     The 'scope' field limits search to specific sources
+          --import ID                Import/webset ID to attach data to this webset
+                                     (loads data but does NOT filter searches)
+                                     Format: import_abc123 or webset_xyz789
 
         Options:
           --enrichments JSON         Array of enrichment configs (supports @file.json)
-          --exclude JSON             Array of exclude configs (supports @file.json)
+                                     Format: [{"description":"...","format":"text"}]
+          --exclude JSON             Sources to exclude from searches (supports @file.json)
+                                     Format: [{"source":"import|webset","id":"..."}]
           --external-id ID           External identifier for the webset
           --metadata JSON            Custom metadata (supports @file.json)
+                                     Format: {"key":"value"}
           --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
 
+        JSON Format Details:
+          search.scope               Array of source references to limit search
+                                     Format: [{"source":"import|webset","id":"..."}]
+                                     With relationship (hop search):
+                                     [{"source":"webset","id":"ws_123",
+                                       "relationship":{"definition":"investors of","limit":3}}]
+
+          IMPORTANT: Cannot use the same import ID in both --import and search.scope
+                    (this will return a 400 error from the API)
+
         Examples:
           # Create webset from search
           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
 
+          # Create webset with scoped search (filter to specific import)
+          exa-ai webset-create --search '{"query":"CEOs","count":10,"scope":[{"source":"import","id":"import_abc"}]}'
+
           # Create webset from import
           exa-ai webset-create --import import_abc123
           exa-ai webset-create --import import_def456 --enrichments @enrichments.json
 
-          # Create webset from existing webset
-          exa-ai webset-create --import webset_xyz789
+          # Load import AND run search (search not scoped to import)
+          exa-ai webset-create --import import_abc123 --search '{"query":"investors","count":20}'
       HELP
       exit 0
     else