exa-ai 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8604fda006df666f4162cf8d76e83ef294c9a24d8a759e23c926e48479b97ca
-  data.tar.gz: 2bf1a0a4f601e8da648f4eb4e72e66a40312c93ec6d0950c1cf04a9207fd70d6
+  metadata.gz: ffa1108ddff0ff951dc18d12eeef57f74020a4c0425916a394fac95e4699fef5
+  data.tar.gz: 43c40cc61a7bee139dc3c179fe9d11c40b04dd506d53c22f88e312705ae9dfe3
 SHA512:
-  metadata.gz: ad102f8404ed8195bb345843b76b8287da5a29d2d50988fb0bd6bcbf5d1681c10344c1e95dab9891c7aebdd5f3989b9216ed15e32389e395f5471ddc166ccda8
-  data.tar.gz: 8ec9279adc183c8a101b359aa4213828559aac9c434f16a0128f409c939d489905f3a59d601885e9438d63409426e675473e8df345db7f8e6a56b6a84d0cac8a
+  metadata.gz: 5745df2cf4664fff7b8a507fb82662cd1e448a51dba7a0a0ac30485d624ac1bb3624e85b6086a6bd511a9485636b0d5a9804c561e9476106679a7458572fcf62
+  data.tar.gz: 637d5150a3b0d192b1c68288c83c4e0ad13827d4d60ac9deb4a974397ab9b0c2ab86dd9281f33bc11dc5e1fd7ba06b22daa4c8d0f80c8927c108946e4c8ffe46

data/exe/exa-ai-search

@@ -15,7 +15,8 @@ def print_help
 
     Options:
       --num-results N              Number of results to return (default: 10)
-      --type TYPE                  Search type: fast, deep, keyword, or auto (default: fast)
+      --type TYPE                  Search type: auto, neural, fast, deep, deep-reasoning,
+                                   or instant (default: auto)
       --category CAT               Focus on specific data category
                                    Options: "company", "research paper", "news", "pdf",
                                    "github", "tweet", "personal site", "financial report",
@@ -42,6 +43,19 @@ def print_help
       --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
+      --highlights                 Include text highlights in results
+      --highlights-max-characters N  Max characters per highlight
+      --highlights-num-sentences N   Number of sentences per highlight
+      --highlights-per-url N       Number of highlights per URL
+      --highlights-query QUERY     Custom query for highlight extraction
+      --livecrawl MODE             Livecrawl mode: always, fallback, never, auto, or preferred
+      --livecrawl-timeout N        Livecrawl timeout in milliseconds
+      --max-age-hours N            Maximum age of results in hours
+
+    Search Options:
+      --additional-queries QUERY   Additional search queries (repeatable)
+      --output-schema JSON         JSON schema for output structure (@file syntax)
+      --user-location CODE         User location (ISO country code)
 
     General Options:
       --api-key KEY                Exa API key (or set EXA_API_KEY env var)
@@ -105,6 +119,25 @@ def build_contents(args)
     contents[:extras][:image_links] = args[:image_links] if args[:image_links]
   end
 
+  # Highlights options
+  if args[:highlights]
+    highlight_opts = %i[highlights_max_characters highlights_num_sentences highlights_per_url highlights_query]
+    if highlight_opts.any? { |k| args[k] }
+      contents[:highlights] = {}
+      contents[:highlights][:max_characters] = args[:highlights_max_characters] if args[:highlights_max_characters]
+      contents[:highlights][:num_sentences] = args[:highlights_num_sentences] if args[:highlights_num_sentences]
+      contents[:highlights][:highlights_per_url] = args[:highlights_per_url] if args[:highlights_per_url]
+      contents[:highlights][:query] = args[:highlights_query] if args[:highlights_query]
+    else
+      contents[:highlights] = true
+    end
+  end
+
+  # Livecrawl options
+  contents[:livecrawl] = args[:livecrawl] if args[:livecrawl]
+  contents[:livecrawl_timeout] = args[:livecrawl_timeout] if args[:livecrawl_timeout]
+  contents[:max_age_hours] = args[:max_age_hours] if args[:max_age_hours]
+
   contents.empty? ? nil : contents
 end
 
@@ -130,17 +163,20 @@ begin
 
   # Prepare search parameters
   search_params = {}
-  search_params[:numResults] = args[:num_results] if args[:num_results]
+  search_params[:num_results] = args[:num_results] if args[:num_results]
   search_params[:type] = args[:type] if args[:type]
   search_params[:category] = args[:category] if args[:category]
-  search_params[:includeDomains] = args[:include_domains] if args[:include_domains]
-  search_params[:excludeDomains] = args[:exclude_domains] if args[:exclude_domains]
+  search_params[:include_domains] = args[:include_domains] if args[:include_domains]
+  search_params[:exclude_domains] = args[:exclude_domains] if args[:exclude_domains]
   search_params[:start_published_date] = args[:start_published_date] if args[:start_published_date]
   search_params[:end_published_date] = args[:end_published_date] if args[:end_published_date]
   search_params[:start_crawl_date] = args[:start_crawl_date] if args[:start_crawl_date]
   search_params[:end_crawl_date] = args[:end_crawl_date] if args[:end_crawl_date]
   search_params[:include_text] = args[:include_text] if args[:include_text]
   search_params[:exclude_text] = args[:exclude_text] if args[:exclude_text]
+  search_params[:additional_queries] = args[:additional_queries] if args[:additional_queries]
+  search_params[:output_schema] = args[:output_schema] if args[:output_schema]
+  search_params[:user_location] = args[:user_location] if args[:user_location]
   contents = build_contents(args)
   search_params.merge!(contents) if contents
 

data/exe/exa-ai-webset-create

@@ -61,6 +61,9 @@ def parse_args(argv)
     when "--external-id"
       args[:external_id] = argv[i + 1]
       i += 2
+    when "--title"
+      args[:title] = argv[i + 1]
+      i += 2
     when "--metadata"
       args[:metadata] = parse_json_or_file(argv[i + 1])
       i += 2
@@ -93,6 +96,7 @@ def parse_args(argv)
           --exclude JSON             Sources to exclude from searches (supports @file.json)
                                      Format: [{"source":"import|webset","id":"..."}]
           --external-id ID           External identifier for the webset
+          --title TITLE              Title for the webset
           --metadata JSON            Custom metadata (supports @file.json)
                                      Format: {"key":"value"}
           --wait                     Wait for webset to reach idle status
@@ -185,6 +189,7 @@ begin
   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[:title] = args[:title] if args[:title]
   webset_params[:metadata] = args[:metadata] if args[:metadata]
 
   # Create webset

data/exe/exa-ai-webset-update

@@ -6,6 +6,7 @@ require "json"
 
 # Parse arguments
 webset_id = nil
+title = nil
 metadata = nil
 api_key = nil
 output_format = "json"
@@ -45,6 +46,8 @@ args = ARGV.dup
 while args.any?
   arg = args.shift
   case arg
+  when "--title"
+    title = args.shift
   when "--metadata"
     metadata = parse_json_or_file(args.shift)
   when "--api-key"
@@ -55,12 +58,13 @@ while args.any?
     puts <<~HELP
       Usage: exa-ai webset-update <webset_id> [OPTIONS]
 
-      Update a webset's metadata
+      Update a webset's title and/or metadata
 
       Arguments:
         webset_id              ID of the webset to update (required)
 
       Options:
+        --title TITLE          Title for the webset
         --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)
@@ -68,6 +72,8 @@ while args.any?
 
       Examples:
         exa-ai webset-update ws_abc123 --metadata '{"project":"Q1-2025"}'
+        exa-ai webset-update ws_abc123 --title "Q1 Research"
+        exa-ai webset-update ws_abc123 --title "Q1 Research" --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
@@ -91,12 +97,6 @@ if webset_id.nil?
   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)
@@ -106,7 +106,10 @@ begin
   client = Exa::CLI::Base.build_client(api_key)
 
   # Update webset
-  webset = client.update_webset(webset_id, metadata: metadata)
+  update_params = {}
+  update_params[:title] = title if title
+  update_params[:metadata] = metadata if metadata
+  webset = client.update_webset(webset_id, **update_params)
 
   # Format and output
   output = Exa::CLI::Formatters::WebsetFormatter.format(webset, output_format)

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

@@ -38,6 +38,7 @@ module Exa
           lines = []
           lines << "Webset: #{webset.id}"
           lines << "Status: #{webset.status}"
+          lines << "Title: #{webset.title}" if webset.title
           lines << "Created: #{webset.created_at}" if webset.created_at
           lines << "Updated: #{webset.updated_at}" if webset.updated_at
 
@@ -61,6 +62,7 @@ module Exa
           collection.data.each do |ws|
             lines << "\n  #{ws['id']}"
             lines << "  Status: #{ws['status']}"
+            lines << "  Title: #{ws['title']}" if ws['title']
             lines << "  Created: #{ws['createdAt']}" if ws['createdAt']
           end
           lines.join("\n")

data/lib/exa/cli/search_parser.rb

@@ -3,7 +3,8 @@
 module Exa
   module CLI
     class SearchParser
-      VALID_SEARCH_TYPES = ["fast", "deep", "keyword", "auto"].freeze
+      VALID_SEARCH_TYPES = ["auto", "neural", "fast", "deep", "deep-reasoning", "instant"].freeze
+      VALID_LIVECRAWL_MODES = ["always", "fallback", "never", "auto", "preferred"].freeze
       VALID_CATEGORIES = [
         "company", "research paper", "news", "pdf", "github",
         "tweet", "personal site", "financial report", "people"
@@ -123,6 +124,47 @@ module Exa
           when "--image-links"
             @args[:image_links] = @argv[i + 1].to_i
             i += 2
+          when "--highlights"
+            @args[:highlights] = true
+            i += 1
+          when "--highlights-max-characters"
+            @args[:highlights_max_characters] = @argv[i + 1].to_i
+            i += 2
+          when "--highlights-num-sentences"
+            @args[:highlights_num_sentences] = @argv[i + 1].to_i
+            i += 2
+          when "--highlights-per-url"
+            @args[:highlights_per_url] = @argv[i + 1].to_i
+            i += 2
+          when "--highlights-query"
+            @args[:highlights_query] = @argv[i + 1]
+            i += 2
+          when "--livecrawl"
+            livecrawl = @argv[i + 1]
+            validate_livecrawl(livecrawl)
+            @args[:livecrawl] = livecrawl
+            i += 2
+          when "--livecrawl-timeout"
+            @args[:livecrawl_timeout] = @argv[i + 1].to_i
+            i += 2
+          when "--max-age-hours"
+            @args[:max_age_hours] = @argv[i + 1].to_i
+            i += 2
+          when "--additional-queries"
+            @args[:additional_queries] ||= []
+            @args[:additional_queries] << @argv[i + 1]
+            i += 2
+          when "--output-schema"
+            schema_arg = @argv[i + 1]
+            @args[:output_schema] = if schema_arg.start_with?("@")
+                                      JSON.parse(File.read(schema_arg[1..]))
+                                    else
+                                      JSON.parse(schema_arg)
+                                    end
+            i += 2
+          when "--user-location"
+            @args[:user_location] = @argv[i + 1]
+            i += 2
           else
             query_parts << arg
             i += 1
@@ -142,6 +184,12 @@ module Exa
         raise ArgumentError, "Search type must be one of: #{VALID_SEARCH_TYPES.join(', ')}"
       end
 
+      def validate_livecrawl(mode)
+        return if VALID_LIVECRAWL_MODES.include?(mode)
+
+        raise ArgumentError, "Livecrawl mode must be one of: #{VALID_LIVECRAWL_MODES.join(', ')}"
+      end
+
       def validate_category(category)
         return if VALID_CATEGORIES.include?(category)
 

data/lib/exa/client.rb

@@ -158,10 +158,11 @@ module Exa
       Services::Websets::Cancel.new(connection, id: id).call
     end
 
-    # Update a webset's metadata
+    # Update a webset's title and/or metadata
     #
     # @param id [String] Webset ID
     # @param params [Hash] Update parameters
+    # @option params [String] :title Title for the webset
     # @option params [Hash] :metadata Metadata to update
     # @return [Resources::Webset] The updated webset
     def update_webset(id, **params)

data/lib/exa/resources/search_result.rb

@@ -11,9 +11,10 @@ module Exa
       :search_type,
       :context,
       :cost_dollars,
+      :output,
       keyword_init: true
     )
-      def initialize(results:, request_id: nil, resolved_search_type: nil, search_type: nil, context: nil, cost_dollars: nil)
+      def initialize(results:, request_id: nil, resolved_search_type: nil, search_type: nil, context: nil, cost_dollars: nil, output: nil)
         super
         freeze
       end

data/lib/exa/services/parameter_converter.rb

@@ -36,18 +36,26 @@ module Exa
         when :include_text then :includeText
         when :exclude_text then :excludeText
         when :external_id then :externalId
+        when :additional_queries then :additionalQueries
+        when :output_schema then :outputSchema
+        when :user_location then :userLocation
+        when :num_results then :numResults
+        when :include_domains then :includeDomains
+        when :exclude_domains then :excludeDomains
         else
           key
         end
       end
 
       def content_key?(key)
-        %i[text summary context subpages subpage_target extras].include?(key)
+        %i[text summary context subpages subpage_target extras highlights livecrawl livecrawl_timeout max_age_hours].include?(key)
       end
 
       def convert_content_key(key)
         case key
         when :subpage_target then :subpageTarget
+        when :livecrawl_timeout then :livecrawlTimeout
+        when :max_age_hours then :maxAgeHours
         else
           key
         end
@@ -79,6 +87,12 @@ module Exa
           else
             value
           end
+        when :highlights
+          if value.is_a?(Hash)
+            convert_hash_value(value, highlights_hash_mappings)
+          else
+            value
+          end
         else
           value
         end
@@ -96,7 +110,9 @@ module Exa
       def text_hash_mappings
         {
           max_characters: :maxCharacters,
-          include_html_tags: :includeHtmlTags
+          include_html_tags: :includeHtmlTags,
+          include_sections: :includeSections,
+          exclude_sections: :excludeSections
         }
       end
 
@@ -118,6 +134,15 @@ module Exa
           image_links: :imageLinks
         }
       end
+
+      def highlights_hash_mappings
+        {
+          max_characters: :maxCharacters,
+          num_sentences: :numSentences,
+          highlights_per_url: :highlightsPerUrl,
+          query: :query
+        }
+      end
     end
   end
 end

data/lib/exa/services/search.rb

@@ -5,7 +5,7 @@ require_relative "parameter_converter"
 module Exa
   module Services
     class Search
-      VALID_SEARCH_TYPES = ["fast", "deep", "keyword", "auto"].freeze
+      VALID_SEARCH_TYPES = ["auto", "neural", "fast", "deep", "deep-reasoning", "instant"].freeze
       DEFAULT_SEARCH_TYPE = "auto"
 
       def initialize(connection, **params)
@@ -24,7 +24,8 @@ module Exa
           resolved_search_type: body["resolvedSearchType"],
           search_type: body["searchType"],
           context: body["context"],
-          cost_dollars: body["costDollars"]
+          cost_dollars: body["costDollars"],
+          output: body["output"]
         )
       end
 

data/lib/exa/services/websets/create_validator.rb

@@ -19,6 +19,7 @@ module Exa
             validate_enrichments!(params[:enrichments]) if params[:enrichments]
             validate_exclude!(params[:exclude]) if params[:exclude]
             validate_external_id!(params[:externalId]) if params[:externalId]
+            validate_title!(params[:title]) if params[:title]
             validate_metadata!(params[:metadata]) if params[:metadata]
             validate_no_duplicate_ids_in_import_and_scope!(params)
           end
@@ -158,6 +159,12 @@ module Exa
             raise ArgumentError, "externalId cannot exceed 300 characters" if external_id.length > 300
           end
 
+          def validate_title!(title)
+            raise ArgumentError, "title must be a String" unless title.is_a?(String)
+            raise ArgumentError, "title cannot be empty" if title.strip.empty?
+            raise ArgumentError, "title cannot exceed 1000 characters" if title.length > 1000
+          end
+
           def validate_metadata!(metadata)
             raise ArgumentError, "metadata must be a Hash" unless metadata.is_a?(Hash)
 

data/lib/exa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Exa
-  VERSION = "0.8.0"
+  VERSION = "0.10.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exa-ai
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Benjamin Jackson