exa-ai 0.2.0 → 0.3.1

data/exe/exa-ai

@@ -1,9 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
-require "exa"
-require "exa/cli/base"
+require "exa-ai"
 
 # Global CLI interface for Exa API
 

data/exe/exa-ai-answer

@@ -1,18 +1,15 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Set up load paths
-require "bundler/setup"
-require "exa"
-require "exa/cli/base"
-require "exa/cli/formatters/answer_formatter"
+require "exa-ai"
 
 # Parse command-line arguments
 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 +21,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 +46,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 +96,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 +108,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-context

@@ -1,10 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
-require "exa"
-require "exa/cli/base"
-require "exa/cli/formatters/context_formatter"
+require "exa-ai"
 
 # Parse command line arguments
 def parse_args(args)

data/exe/exa-ai-get-contents

@@ -1,18 +1,25 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
-require "exa"
-require "exa/cli/base"
-require "exa/cli/formatters/contents_formatter"
+require "exa-ai"
 
 # Parse command line arguments
 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 +32,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 +86,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 +218,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 +234,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 +243,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-get

@@ -1,8 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
-require "exa"
+require "exa-ai"
 
 # Parse command-line arguments
 api_key = nil

data/exe/exa-ai-research-list

@@ -1,8 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
-require "exa"
+require "exa-ai"
 
 # Parse command-line arguments
 api_key = nil

data/exe/exa-ai-research-start

@@ -1,9 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Set up load paths
-require "bundler/setup"
-require "exa"
+require "exa-ai"
 
 # Parse command-line arguments
 def parse_args(argv)
@@ -47,7 +45,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 +56,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

@@ -1,9 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Set up load paths
-require "bundler/setup"
-require "exa"
+require "exa-ai"
 
 # Parse command-line arguments
 def parse_args(argv)
@@ -39,9 +37,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 +154,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 +265,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/cli/base.rb

@@ -11,7 +11,7 @@ module Exa
         env_key = ENV["EXA_API_KEY"]
         return env_key if env_key && !env_key.empty?
 
-        raise ConfigurationError,
+        raise Exa::ConfigurationError,
               "Missing API key. Set EXA_API_KEY environment variable or use --api-key flag"
       end
 
@@ -24,13 +24,13 @@ module Exa
 
         return format if valid_formats.include?(format)
 
-        raise ConfigurationError,
+        raise Exa::ConfigurationError,
               "Invalid output format: #{format}. Valid formats: #{valid_formats.join(', ')}"
       end
 
       # Build a client instance with the given API key
       def self.build_client(api_key, **options)
-        Client.new(api_key: api_key, **options)
+        Exa::Client.new(api_key: api_key, **options)
       end
 
       # Format output data based on format type

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
@@ -146,6 +161,7 @@ module Exa
       options = {}
       options[:base_url] = @options[:base_url] if @options[:base_url]
       options[:timeout] = @options[:timeout] if @options[:timeout]
+      options[:debug] = true if ENV["EXA_DEBUG"]
       options
     end
 

data/lib/exa/connection.rb

@@ -1,17 +1,24 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "logger"
 
 module Exa
   class Connection
+    DEFAULT_BASE_URL = "https://api.exa.ai"
     def self.build(api_key:, **options, &block)
       Faraday.new(url: options[:base_url] || DEFAULT_BASE_URL) do |conn|
         # Authentication
-        conn.request :authorization, "Bearer", api_key
+        conn.headers["x-api-key"] = api_key
 
         # Request/Response JSON encoding
         conn.request :json
 
+        # Debug logging (when enabled via option)
+        if options[:debug]
+          conn.response :logger, Logger.new($stdout), headers: true, bodies: true
+        end
+
         # Custom error handling (registered before JSON so it runs after in response chain)
         conn.response :raise_error
         conn.response :json, content_type: /\bjson$/

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.1"
 end

data/lib/exa-ai.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Main entry point for the exa-ai gem
+# This file exists to avoid conflicts with the unrelated "exa" gem
+require_relative "exa"