exa-ai 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cfcc57c0090503ea4b27748c7ade968fea3768f0793bd4939fd4debfb8bd7e0
-  data.tar.gz: 2cff698538f70030cfccdcd3a91305e4696e8f5d78c7c0d4b110e44625109a6e
+  metadata.gz: ae8ad5762410325124acdcada89aed1a88b18dcbecc8b85431b99b0c05e0f354
+  data.tar.gz: b1d8ec27baf9bdf324af7183a6088e22e2437ef5d0bb0c97edee47eadeeed7de
 SHA512:
-  metadata.gz: 4bd5ff3554ae0b7b8159411e516531a7b3bdb5ae1249c95a88a8522cfb7c0c51d904e41e2fb5d3b1e3f19c9f61ab3f154c53e76e05aa7220971ec4e160edf141
-  data.tar.gz: 56233afd37573951715d5747585e3fb3ae59c3df38236d75a9f75a31459a38fa459386702487fbf01217fae72aa833b61a2a0968b903f19ab7f88e5d45a41cbd
+  metadata.gz: 1803b1811bc368be4d83bd9b02aa095c4f77f0dd97e05f3bd96ab9bc380d54b9a9bb7e17f5e3fca78c7a2f7348000f61bc55ec4875273eafa6dd0762fb09f7aa
+  data.tar.gz: 0ec026a9d5b4d05c8779aa3e10df8c25c48e5a728f92608941e28f2b18a46238908af53837dfa234b22f2ad595922f03d1ce25f98f6b9f932ecce8570914a8aa

data/README.md

@@ -220,7 +220,6 @@ exa-ai search "AI" --output-format pretty
 - `--type TYPE` - Search type: keyword, neural, or auto (default: auto)
 - `--include-domains DOMAINS` - Comma-separated domains to include
 - `--exclude-domains DOMAINS` - Comma-separated domains to exclude
-- `--use-autoprompt` - Use Exa's autoprompt feature
 - `--output-format FORMAT` - json or pretty (default: json)
 - `--api-key KEY` - API key (or set EXA_API_KEY env var)
 
@@ -619,8 +618,7 @@ client = Exa::Client.new
 results = client.search("kubernetes tutorial",
   num_results: 20,
   type: "neural",
-  include_domains: ["kubernetes.io", "github.com"],
-  use_autoprompt: true
+  include_domains: ["kubernetes.io", "github.com"]
 )
 
 results.results.each do |item|

data/exe/exa-ai-answer

@@ -12,7 +12,8 @@ def parse_args(argv)
   args = {
     output_format: "json",
     api_key: nil,
-    text: false
+    text: false,
+    stream: false
   }
 
   # Extract query (first non-flag argument)
@@ -24,9 +25,15 @@ def parse_args(argv)
     when "--text"
       args[:text] = true
       i += 1
+    when "--stream"
+      args[:stream] = true
+      i += 1
     when "--output-schema"
       args[:output_schema] = argv[i + 1]
       i += 2
+    when "--system-prompt"
+      args[:system_prompt] = argv[i + 1]
+      i += 2
     when "--api-key"
       args[:api_key] = argv[i + 1]
       i += 2
@@ -43,17 +50,21 @@ def parse_args(argv)
           QUERY                 Question or query to answer (required)
 
         Options:
+          --stream              Stream answer chunks in real-time
           --text                Include full text content from sources
           --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)
           --output-format FMT   Output format: json, pretty, or text (default: json)
           --help, -h            Show this help message
 
         Examples:
           exa-api answer "What is the capital of France?"
+          exa-api answer "Latest AI breakthroughs" --stream
           exa-api answer "Latest AI breakthroughs" --text
           exa-api answer "Ruby best practices" --output-format pretty
           exa-api answer "What is the capital of France?" --output-schema '{"type":"object","properties":{"city":{"type":"string"},"state":{"type":"string"}}}'
+          exa-api answer "What is Paris?" --system-prompt "Respond in the voice of a pirate"
       HELP
       exit 0
     else
@@ -89,6 +100,7 @@ begin
   # Prepare answer parameters
   answer_params = {}
   answer_params[:text] = args[:text] if args[:text]
+  answer_params[:system_prompt] = args[:system_prompt] if args[:system_prompt]
 
   # Parse output_schema as JSON if provided
   if args[:output_schema]
@@ -100,12 +112,24 @@ begin
     end
   end
 
-  # Execute answer
-  result = client.answer(args[:query], **answer_params)
-
-  # Format and output result
-  output = Exa::CLI::Formatters::AnswerFormatter.format(result, output_format)
-  puts output
+  # Execute answer or streaming answer
+  if args[:stream]
+    # Streaming mode - output chunks in real-time
+    client.answer_stream(args[:query], **answer_params) do |chunk|
+      # Extract content from the streaming response format
+      # API returns: {"choices":[{"delta":{"content":"..."}}]}
+      if chunk["choices"]&.first&.dig("delta", "content")
+        print chunk["choices"][0]["delta"]["content"]
+        $stdout.flush
+      end
+    end
+    puts # Add newline at the end
+  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)
+    puts output
+  end
 
 rescue Exa::ConfigurationError => e
   $stderr.puts "Configuration error: #{e.message}"

data/exe/exa-ai-get-contents

@@ -11,8 +11,18 @@ def parse_args(args)
   ids = []
   api_key = nil
   text = false
-  highlights = false
+  text_max_characters = nil
+  include_html_tags = false
   summary = false
+  summary_query = nil
+  summary_schema = nil
+  subpages = nil
+  subpage_target = []
+  links = nil
+  image_links = nil
+  context = false
+  context_max_characters = nil
+  livecrawl_timeout = nil
   output_format = nil
 
   i = 0
@@ -25,10 +35,48 @@ def parse_args(args)
       api_key = args[i]
     when "--text"
       text = true
-    when "--highlights"
-      highlights = true
+      i += 1
+    when "--text-max-characters"
+      i += 1
+      text_max_characters = args[i].to_i
+    when "--include-html-tags"
+      include_html_tags = true
+      i += 1
     when "--summary"
       summary = true
+      i += 1
+    when "--summary-query"
+      i += 1
+      summary_query = args[i]
+    when "--summary-schema"
+      i += 1
+      schema_arg = args[i]
+      summary_schema = if schema_arg.start_with?("@")
+                         JSON.parse(File.read(schema_arg[1..]))
+                       else
+                         JSON.parse(schema_arg)
+                       end
+    when "--subpages"
+      i += 1
+      subpages = args[i].to_i
+    when "--subpage-target"
+      i += 1
+      subpage_target << args[i]
+    when "--links"
+      i += 1
+      links = args[i].to_i
+    when "--image-links"
+      i += 1
+      image_links = args[i].to_i
+    when "--context"
+      context = true
+      i += 1
+    when "--context-max-characters"
+      i += 1
+      context_max_characters = args[i].to_i
+    when "--livecrawl-timeout"
+      i += 1
+      livecrawl_timeout = args[i].to_i
     when "--output-format"
       i += 1
       output_format = args[i]
@@ -41,34 +89,130 @@ def parse_args(args)
         ids_arg = arg
         ids = ids_arg.include?(",") ? ids_arg.split(",").map(&:strip) : [ids_arg]
       end
+      i += 1
+    end
+  end
+
+  {
+    ids: ids,
+    api_key: api_key,
+    text: text,
+    text_max_characters: text_max_characters,
+    include_html_tags: include_html_tags,
+    summary: summary,
+    summary_query: summary_query,
+    summary_schema: summary_schema,
+    subpages: subpages,
+    subpage_target: subpage_target,
+    links: links,
+    image_links: image_links,
+    context: context,
+    context_max_characters: context_max_characters,
+    livecrawl_timeout: livecrawl_timeout,
+    output_format: output_format
+  }
+end
+
+# Build contents parameters from extracted flags
+def build_contents_params(args)
+  params = {}
+
+  # Text options
+  if args[:text]
+    if args[:text_max_characters] || args[:include_html_tags]
+      params[:text] = {}
+      params[:text][:max_characters] = args[:text_max_characters] if args[:text_max_characters]
+      params[:text][:include_html_tags] = args[:include_html_tags] if args[:include_html_tags]
+    else
+      params[:text] = true
+    end
+  end
+
+  # Summary options
+  if args[:summary]
+    if args[:summary_query] || args[:summary_schema]
+      params[:summary] = {}
+      params[:summary][:query] = args[:summary_query] if args[:summary_query]
+      params[:summary][:schema] = args[:summary_schema] if args[:summary_schema]
+    else
+      params[:summary] = true
+    end
+  end
+
+  # Context options
+  if args[:context]
+    if args[:context_max_characters]
+      params[:context] = { max_characters: args[:context_max_characters] }
+    else
+      params[:context] = true
     end
+  end
+
+  # Subpages options
+  params[:subpages] = args[:subpages] if args[:subpages]
+  params[:subpage_target] = args[:subpage_target] if args[:subpage_target].any?
 
-    i += 1
+  # Extras options
+  if args[:links] || args[:image_links]
+    params[:extras] = {}
+    params[:extras][:links] = args[:links] if args[:links]
+    params[:extras][:image_links] = args[:image_links] if args[:image_links]
   end
 
-  { ids: ids, api_key: api_key, text: text, highlights: highlights, summary: summary, output_format: output_format }
+  # Livecrawl options
+  params[:livecrawl_timeout] = args[:livecrawl_timeout] if args[:livecrawl_timeout]
+
+  params.empty? ? nil : params
 end
 
 def print_help
-  puts "Exa Get-Contents - Retrieve page contents"
-  puts ""
-  puts "Usage: exa-api get-contents <ids> [options]"
-  puts ""
-  puts "Arguments:"
-  puts "  ids                    Comma-separated list of IDs or URLs (required)"
-  puts ""
-  puts "Options:"
-  puts "  --text                 Include page text in response"
-  puts "  --highlights           Include highlights in response"
-  puts "  --summary              Include summary in response"
-  puts "  --api-key KEY          Exa API key (or set EXA_API_KEY env var)"
-  puts "  --output-format FMT    Output format: json, pretty, or text (default: json)"
-  puts "  --help, -h             Show this help message"
-  puts ""
-  puts "Examples:"
-  puts "  exa-api get-contents 'https://example.com'"
-  puts "  exa-api get-contents 'id1,id2,id3' --text"
-  puts "  exa-api get-contents 'https://example.com' --highlights --output-format pretty"
+  puts <<~HELP
+    Usage: exa-api get-contents <urls> [options]
+
+    Retrieve full page contents from URLs
+
+    Arguments:
+      urls                   Comma-separated list of URLs (required)
+
+    Options:
+      Text Extraction:
+        --text                       Include page text in response
+        --text-max-characters N      Max characters for page text
+        --include-html-tags          Include HTML tags in text extraction
+
+      Summary:
+        --summary                    Include AI-generated summary
+        --summary-query PROMPT       Custom prompt for summary generation
+        --summary-schema FILE        JSON schema for summary structure (@file syntax)
+
+      Context:
+        --context                    Format results as context for LLM RAG
+        --context-max-characters N   Max characters for context string
+
+      Subpages:
+        --subpages N                 Number of subpages to crawl
+        --subpage-target PHRASE      Subpage target phrases (repeatable)
+
+      Extras:
+        --links N                    Number of links to extract per result
+        --image-links N              Number of image links to extract
+
+      Livecrawl:
+        --livecrawl-timeout N        Timeout for livecrawling in milliseconds
+
+      General:
+        --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 get-contents 'https://example.com'
+      exa-api get-contents 'https://example.com' --text
+      exa-api get-contents 'https://example.com' --text --text-max-characters 3000 --include-html-tags
+      exa-api get-contents 'url1,url2' --summary --summary-query "Be terse"
+      exa-api get-contents 'https://example.com' --subpages 1 --subpage-target about
+      exa-api get-contents 'https://example.com' --links 5 --image-links 10
+  HELP
 end
 
 begin
@@ -77,9 +221,9 @@ begin
 
   # Validate IDs
   if options[:ids].empty?
-    puts "Error: IDs argument required"
-    puts ""
-    puts "Run 'exa-api get-contents --help' for usage information."
+    $stderr.puts "Error: URLs argument required"
+    $stderr.puts ""
+    $stderr.puts "Run 'exa-api get-contents --help' for usage information."
     exit 1
   end
 
@@ -93,10 +237,8 @@ begin
   client = Exa::CLI::Base.build_client(api_key)
 
   # Build request parameters
-  params = {}
-  params[:text] = true if options[:text]
-  params[:highlights] = true if options[:highlights]
-  params[:summary] = true if options[:summary]
+  params = build_contents_params(options)
+  params ||= {}
 
   # Call API
   result = client.get_contents(options[:ids], **params)
@@ -104,11 +246,25 @@ begin
   # Format and output
   output = Exa::CLI::Formatters::ContentsFormatter.format(result, 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
-  puts "Error: #{e.message}"
+  $stderr.puts "Error: #{e.message}"
   exit 1
 rescue StandardError => e
-  puts "Unexpected error: #{e.message}"
-  puts e.backtrace.first(5) if ENV["DEBUG"]
+  $stderr.puts "Unexpected error: #{e.message}"
+  $stderr.puts e.backtrace.first(5) if ENV["DEBUG"]
   exit 1
 end

data/exe/exa-ai-research-start

@@ -47,7 +47,7 @@ def parse_args(argv)
 
         Options:
           --instructions TEXT   Research instructions (required)
-          --model MODEL         Model to use (e.g., gpt-4, gpt-3.5-turbo)
+          --model MODEL         Research model: exa-research (default), exa-research-pro, exa-research-fast
           --output-schema JSON  JSON schema string for structured output
           --wait                Wait for task to complete (polls until done)
           --events              Include event log in output (only with --wait)
@@ -58,7 +58,7 @@ def parse_args(argv)
         Examples:
           exa-api research-start --instructions "Find Ruby performance tips"
           exa-api research-start --instructions "Analyze AI trends" --wait --events
-          exa-api research-start --instructions "Summarize papers" --model gpt-4 --wait
+          exa-api research-start --instructions "Summarize papers" --model exa-research-pro --wait
           exa-api research-start --instructions "Find stats" --output-schema '{"type":"object"}'
       HELP
       exit 0

data/exe/exa-ai-search

@@ -39,9 +39,6 @@ def parse_args(argv)
     when "--exclude-domains"
       args[:exclude_domains] = argv[i + 1].split(",").map(&:strip)
       i += 2
-    when "--use-autoprompt"
-      args[:use_autoprompt] = true
-      i += 1
     when "--api-key"
       args[:api_key] = argv[i + 1]
       i += 2
@@ -159,7 +156,6 @@ def parse_args(argv)
           --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)
@@ -271,7 +267,6 @@ begin
   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 based on LinkedIn type
   result = case args[:linkedin]

data/lib/exa/client.rb

@@ -71,6 +71,21 @@ module Exa
       Services::Answer.new(connection, query: query, **options).call
     end
 
+    # Stream AI-generated answers to a query
+    #
+    # Returns partial answer chunks as they are generated by the API.
+    #
+    # @param query [String] Question or query
+    # @param options [Hash] Answer options
+    # @option options [Boolean] :text Include full text content (default: false)
+    # @option options [Hash] :output_schema JSON schema for structured output
+    # @yield [chunk] Yields each answer chunk as it arrives
+    # @yieldparam chunk [Hash] Partial answer data with {"answer" => "text"}
+    # @return [void]
+    def answer_stream(query, **options, &block)
+      Services::AnswerStream.new(connection, query: query, **options).call(&block)
+    end
+
     # Start an asynchronous research task
     #
     # @param params [Hash] Research parameters

data/lib/exa/services/answer_stream.rb

@@ -0,0 +1,90 @@
+require "json"
+
+module Exa
+  module Services
+    class AnswerStream
+      def initialize(connection, **params)
+        @connection = connection
+        @params = params.merge(stream: true)
+      end
+
+      def call(&block)
+        raise ArgumentError, "block required for streaming" unless block_given?
+
+        # Use instance variable to track buffer across on_data callbacks
+        @buffer = ""
+
+        # Configure the request to stream chunks via on_data callback
+        @connection.post("/answer", @params) do |req|
+          req.options.on_data = proc do |chunk|
+            # Add chunk to buffer and process complete SSE events
+            @buffer += chunk
+            process_sse_buffer(&block)
+          end
+        end
+
+        # Process any remaining data in buffer after stream ends
+        process_remaining_buffer(&block) if @buffer.length.positive?
+      end
+
+      private
+
+      def process_sse_buffer
+        # Extract and process complete SSE events (separated by \n\n)
+        # If buffer ends with \n\n, all parts are complete.
+        # Otherwise, keep the last part in buffer for next chunk.
+
+        return if @buffer.empty?
+
+        parts = @buffer.split("\n\n")
+
+        # When split by a delimiter, if the string ends with the delimiter,
+        # split doesn't add a trailing empty string. So we need to track
+        # whether the buffer ended with \n\n to know if the last part is incomplete.
+        if @buffer.end_with?("\n\n")
+          # All parts are complete, clear buffer
+          complete_parts = parts
+          @buffer = ""
+        else
+          # Last part is incomplete, keep it for next chunk
+          complete_parts = parts[0...-1]
+          @buffer = parts.last || ""
+        end
+
+        # Process all complete events
+        complete_parts.each do |event|
+          next if event.empty?
+
+          lines = event.split("\n")
+          lines.each do |line|
+            if line.start_with?("data: ")
+              json_str = line.sub(/^data: /, "").strip
+              begin
+                data = JSON.parse(json_str)
+                yield(data)
+              rescue JSON::ParserError
+                # Skip lines that aren't valid JSON
+              end
+            end
+          end
+        end
+      end
+
+      def process_remaining_buffer
+        # Process any remaining incomplete buffer
+        lines = @buffer.split("\n")
+        lines.each do |line|
+          if line.start_with?("data: ")
+            json_str = line.sub(/^data: /, "").strip
+            begin
+              data = JSON.parse(json_str)
+              yield(data)
+            rescue JSON::ParserError
+              # Skip lines that aren't valid JSON
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/exa/version.rb

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

data/lib/exa.rb

@@ -18,6 +18,7 @@ require_relative "exa/services/research_get"
 require_relative "exa/services/research_start"
 require_relative "exa/services/research_list"
 require_relative "exa/services/answer"
+require_relative "exa/services/answer_stream"
 require_relative "exa/services/context"
 require_relative "exa/client"
 require_relative "exa/cli/base"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exa-ai
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Benjamin Jackson
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ld-eventsource
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -139,6 +153,7 @@ files:
 - lib/exa/resources/research_task.rb
 - lib/exa/resources/search_result.rb
 - lib/exa/services/answer.rb
+- lib/exa/services/answer_stream.rb
 - lib/exa/services/context.rb
 - lib/exa/services/find_similar.rb
 - lib/exa/services/get_contents.rb