exa-ai 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca5a6bcb0b981d51fcc93e1dc9f1e7037d1d6346e082826e1b1c003d586cce45
-  data.tar.gz: e598e0c91c2815a5abea958adb9f5112def140b78f13ba29872d07009c4056cc
+  metadata.gz: 5cfcc57c0090503ea4b27748c7ade968fea3768f0793bd4939fd4debfb8bd7e0
+  data.tar.gz: 2cff698538f70030cfccdcd3a91305e4696e8f5d78c7c0d4b110e44625109a6e
 SHA512:
-  metadata.gz: 4b648ebe500a28dbb8d31aa936fd0d30a09ff94c372a3f3caec463d648993ae26473fc9724aea0157395b8e78ac9a25fc3f2752c8d6fd1cc68745bb8758b0ca7
-  data.tar.gz: 512d79543838b4b82ba263586c9cd029f8e19f350ff9c744b85dcb5b8f4e62236b442b70d07316721bc844f6ca9ac79bac6c1b42d57d5f0ef1214c5be407818e
+  metadata.gz: 4bd5ff3554ae0b7b8159411e516531a7b3bdb5ae1249c95a88a8522cfb7c0c51d904e41e2fb5d3b1e3f19c9f61ab3f154c53e76e05aa7220971ec4e160edf141
+  data.tar.gz: 56233afd37573951715d5747585e3fb3ae59c3df38236d75a9f75a31459a38fa459386702487fbf01217fae72aa833b61a2a0968b903f19ab7f88e5d45a41cbd

data/README.md

@@ -214,7 +214,7 @@ exa-ai search "tutorials" \
 exa-ai search "AI" --output-format pretty
 ```
 
-**Options:**
+**Basic Options:**
 - `QUERY` - Search query (required)
 - `--num-results N` - Number of results (default: 10)
 - `--type TYPE` - Search type: keyword, neural, or auto (default: auto)
@@ -224,6 +224,141 @@ exa-ai search "AI" --output-format pretty
 - `--output-format FORMAT` - json or pretty (default: json)
 - `--api-key KEY` - API key (or set EXA_API_KEY env var)
 
+#### Advanced Search Options
+
+**Date Filtering:**
+```bash
+# Filter by published date
+exa-ai search "AI research" \
+  --start-published-date "2025-01-01T00:00:00.000Z" \
+  --end-published-date "2025-12-31T23:59:59.999Z"
+
+# Filter by crawl date
+exa-ai search "news" \
+  --start-crawl-date "2025-10-01T00:00:00.000Z" \
+  --end-crawl-date "2025-10-31T23:59:59.999Z"
+```
+
+**Text Filtering:**
+```bash
+# Results must include specific phrase
+exa-ai search "machine learning" --include-text "neural networks"
+
+# Results must exclude specific phrase
+exa-ai search "programming" --exclude-text "paid-partnership"
+
+# Combine inclusion and exclusion
+exa-ai search "Python" \
+  --include-text "open source" \
+  --exclude-text "deprecated"
+```
+
+**Content Extraction:**
+```bash
+# Extract full webpage text
+exa-ai search "Ruby" --text
+
+# Extract text with options
+exa-ai search "AI" \
+  --text \
+  --text-max-characters 3000 \
+  --include-html-tags
+
+# Generate AI summaries
+exa-ai search "climate change" \
+  --summary \
+  --summary-query "What are the main points?"
+
+# Format results as context for LLM RAG
+exa-ai search "kubernetes" \
+  --context \
+  --context-max-characters 5000
+
+# Crawl subpages
+exa-ai search "documentation" \
+  --subpages 1 \
+  --subpage-target about \
+  --subpage-target docs
+
+# Extract links from results
+exa-ai search "web development" \
+  --links 3 \
+  --image-links 2
+```
+
+**Advanced Ruby API:**
+```ruby
+client = Exa::Client.new(api_key: "your-key")
+
+# Date range filtering
+results = client.search("AI research",
+  start_published_date: "2025-01-01T00:00:00.000Z",
+  end_published_date: "2025-12-31T23:59:59.999Z"
+)
+
+# Text filtering
+results = client.search("machine learning",
+  include_text: ["neural networks"],
+  exclude_text: ["cryptocurrency"]
+)
+
+# Full webpage text extraction
+results = client.search("Ruby",
+  text: {
+    max_characters: 3000,
+    include_html_tags: true
+  }
+)
+
+# AI-powered summaries
+results = client.search("climate change",
+  summary: {
+    query: "What are the main points?"
+  }
+)
+
+# Context for RAG pipelines
+results = client.search("kubernetes",
+  context: {
+    max_characters: 5000
+  }
+)
+
+# Subpage crawling
+results = client.search("documentation",
+  subpages: 1,
+  subpage_target: ["about", "docs", "guide"]
+)
+
+# Links and image extraction
+results = client.search("web development",
+  extras: {
+    links: 3,
+    image_links: 2
+  }
+)
+
+# Combine multiple features
+results = client.search("AI",
+  num_results: 5,
+  start_published_date: "2025-01-01T00:00:00.000Z",
+  text: { max_characters: 3000 },
+  summary: { query: "Main developments?" },
+  context: { max_characters: 5000 },
+  subpages: 1,
+  subpage_target: ["research"],
+  extras: { links: 3, image_links: 2 }
+)
+
+# Access extracted content
+results.results.each do |result|
+  puts result["title"]
+  puts result["text"] if result["text"]        # Full webpage text
+  puts result["summary"] if result["summary"]  # AI summary
+  puts result["links"] if result["links"]      # Extracted links
+end
+```
+
 ### Answer Command
 
 Generate comprehensive answers to questions using Exa's answer generation feature:

data/exe/exa-ai-search

@@ -24,6 +24,15 @@ def parse_args(argv)
     when "--type"
       args[:type] = argv[i + 1]
       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
@@ -39,6 +48,77 @@ def parse_args(argv)
     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-api search QUERY [OPTIONS]
@@ -49,18 +129,50 @@ def parse_args(argv)
           QUERY                 Search query (required)
 
         Options:
-          --num-results N       Number of results to return (default: 10)
-          --type TYPE           Search type: keyword, neural, or auto (default: auto)
-          --include-domains D   Comma-separated list of domains to include
-          --exclude-domains D   Comma-separated list of domains to exclude
-          --use-autoprompt      Use Exa's autoprompt feature
-          --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
+          --num-results N              Number of results to return (default: 10)
+          --type TYPE                  Search type: keyword, neural, fast, or auto (default: auto)
+          --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:
+          --use-autoprompt             Use Exa's autoprompt feature
+          --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-api search "ruby programming"
           exa-api search "machine learning" --num-results 5 --type keyword
+          exa-api search "Latest LLM research" --category "research paper"
+          exa-api search "AI startups" --category company
+          exa-api search "Anthropic" --linkedin company
+          exa-api search "Dario Amodei" --linkedin person
+          exa-api search "AI" --linkedin all
           exa-api search "AI research" --include-domains arxiv.org,scholar.google.com
           exa-api search "tutorials" --output-format pretty
       HELP
@@ -75,6 +187,55 @@ def parse_args(argv)
   args
 end
 
+# Build contents parameter from extracted flags
+def build_contents(args)
+  contents = {}
+
+  # Text options
+  if args[:text]
+    if args[:text_max_characters] || args[:include_html_tags]
+      contents[:text] = {}
+      contents[:text][:max_characters] = args[:text_max_characters] if args[:text_max_characters]
+      contents[:text][:include_html_tags] = args[:include_html_tags] if args[:include_html_tags]
+    else
+      contents[:text] = true
+    end
+  end
+
+  # Summary options
+  if args[:summary]
+    if args[:summary_query] || args[:summary_schema]
+      contents[:summary] = {}
+      contents[:summary][:query] = args[:summary_query] if args[:summary_query]
+      contents[:summary][:schema] = args[:summary_schema] if args[:summary_schema]
+    else
+      contents[:summary] = true
+    end
+  end
+
+  # Context options
+  if args[:context]
+    if args[:context_max_characters]
+      contents[:context] = { max_characters: args[:context_max_characters] }
+    else
+      contents[:context] = true
+    end
+  end
+
+  # Subpages options
+  contents[:subpages] = args[:subpages] if args[:subpages]
+  contents[:subpage_target] = args[:subpage_target] if args[:subpage_target]
+
+  # Extras options
+  if args[:links] || args[:image_links]
+    contents[:extras] = {}
+    contents[:extras][:links] = args[:links] if args[:links]
+    contents[:extras][:image_links] = args[:image_links] if args[:image_links]
+  end
+
+  contents.empty? ? nil : contents
+end
+
 # Main execution
 begin
   args = parse_args(ARGV)
@@ -97,14 +258,32 @@ begin
 
   # Prepare search parameters
   search_params = {}
-  search_params[:num_results] = args[:num_results] if args[:num_results]
+  search_params[:numResults] = args[:num_results] if args[:num_results]
   search_params[:type] = args[:type] if args[:type]
-  search_params[:include_domains] = args[:include_domains] if args[:include_domains]
-  search_params[:exclude_domains] = args[:exclude_domains] if args[:exclude_domains]
-  search_params[:use_autoprompt] = args[:use_autoprompt] if args[:use_autoprompt]
+  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[: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]
+  contents = build_contents(args)
+  search_params.merge!(contents) if contents
+  search_params[:useAutoprompt] = args[:use_autoprompt] if args[:use_autoprompt]
 
-  # Execute search
-  result = client.search(args[:query], **search_params)
+  # 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
 
   # Format and output result
   output = Exa::CLI::Formatters::SearchFormatter.format(result, output_format)

data/lib/exa/client.rb

@@ -107,6 +107,32 @@ module Exa
       Services::Context.new(connection, query: query, **params).call
     end
 
+    # Search for LinkedIn company pages
+    #
+    # Convenience method that restricts search to LinkedIn company profiles
+    # using keyword search for precise name matching.
+    #
+    # @param query [String] Company name to search
+    # @param params [Hash] Additional search parameters
+    # @option params [Integer] :numResults Number of results to return
+    # @return [Resources::SearchResult] LinkedIn company results
+    def linkedin_company(query, **params)
+      search(query, type: "keyword", includeDomains: ["linkedin.com/company"], **params)
+    end
+
+    # Search for LinkedIn profiles
+    #
+    # Convenience method that restricts search to LinkedIn individual profiles
+    # using keyword search for precise name matching.
+    #
+    # @param query [String] Person name to search
+    # @param params [Hash] Additional search parameters
+    # @option params [Integer] :numResults Number of results to return
+    # @return [Resources::SearchResult] LinkedIn profile results
+    def linkedin_person(query, **params)
+      search(query, type: "keyword", includeDomains: ["linkedin.com/in"], **params)
+    end
+
     private
 
     def connection

data/lib/exa/services/parameter_converter.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Exa
+  module Services
+    # Converts Ruby parameter names (snake_case) to API format (camelCase)
+    # Handles both simple parameters and nested content parameters
+    class ParameterConverter
+      def self.convert(params)
+        new.convert(params)
+      end
+
+      def convert(params)
+        converted = {}
+        contents = {}
+
+        params.each do |key, value|
+          if content_key?(key)
+            contents[convert_content_key(key)] = convert_content_value(key, value)
+          else
+            converted[convert_key(key)] = value
+          end
+        end
+
+        converted[:contents] = contents if contents.any?
+        converted
+      end
+
+      private
+
+      def convert_key(key)
+        case key
+        when :start_published_date then :startPublishedDate
+        when :end_published_date then :endPublishedDate
+        when :start_crawl_date then :startCrawlDate
+        when :end_crawl_date then :endCrawlDate
+        when :include_text then :includeText
+        when :exclude_text then :excludeText
+        else
+          key
+        end
+      end
+
+      def content_key?(key)
+        %i[text summary context subpages subpage_target extras].include?(key)
+      end
+
+      def convert_content_key(key)
+        case key
+        when :subpage_target then :subpageTarget
+        else
+          key
+        end
+      end
+
+      def convert_content_value(key, value)
+        case key
+        when :text
+          if value.is_a?(Hash)
+            convert_hash_value(value, text_hash_mappings)
+          else
+            value
+          end
+        when :summary
+          if value.is_a?(Hash)
+            convert_hash_value(value, summary_hash_mappings)
+          else
+            value
+          end
+        when :context
+          if value.is_a?(Hash)
+            convert_hash_value(value, context_hash_mappings)
+          else
+            value
+          end
+        when :extras
+          if value.is_a?(Hash)
+            convert_hash_value(value, extras_hash_mappings)
+          else
+            value
+          end
+        else
+          value
+        end
+      end
+
+      def convert_hash_value(hash, mappings)
+        converted = {}
+        hash.each do |k, v|
+          converted_key = mappings[k] || k
+          converted[converted_key] = v
+        end
+        converted
+      end
+
+      def text_hash_mappings
+        {
+          max_characters: :maxCharacters,
+          include_html_tags: :includeHtmlTags
+        }
+      end
+
+      def summary_hash_mappings
+        {
+          query: :query,
+          schema: :schema
+        }
+      end
+
+      def context_hash_mappings
+        {
+          max_characters: :maxCharacters
+        }
+      end
+
+      def extras_hash_mappings
+        {
+          image_links: :imageLinks
+        }
+      end
+    end
+  end
+end

data/lib/exa/services/search.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "parameter_converter"
+
 module Exa
   module Services
     class Search
@@ -9,7 +11,7 @@ module Exa
       end
 
       def call
-        response = @connection.post("/search", @params)
+        response = @connection.post("/search", ParameterConverter.convert(@params))
         body = response.body
 
         Resources::SearchResult.new(

data/lib/exa/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exa-ai
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Benjamin Jackson
@@ -142,6 +142,7 @@ files:
 - lib/exa/services/context.rb
 - lib/exa/services/find_similar.rb
 - lib/exa/services/get_contents.rb
+- lib/exa/services/parameter_converter.rb
 - lib/exa/services/research_get.rb
 - lib/exa/services/research_list.rb
 - lib/exa/services/research_start.rb