exa-ai 0.12.1 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8f2ec6d5b6e263466f5125722a28e9c0625aae9cc3342cc8cabbbc6fe5ae260b
4
- data.tar.gz: 06a79cb7b742df7a5bd49f0267c32f93ab76c4acc260bbfc0cbdf6b8478bdc33
3
+ metadata.gz: c27b667bcdbd00173088ba535ad3ecc2ef249431703e7666739d0c74a59c3fc1
4
+ data.tar.gz: 4067fe462f41c1be33acdb455a2b6ca0d1871fa362650a18293785b37f41df2f
5
5
  SHA512:
6
- metadata.gz: 7f35b340937f7580d21517e7d8b60cc39048bbedbd8092815f8c5ed9fb974b5746ad4832dee65e6743ba6492e28b09f82ced416e27463889b0271d3eae6e1d28
7
- data.tar.gz: eedbb8580d6103b78d6fbbb4c4f41e89d0f48c713705537096cbf33de8a8da9818ee40309b76c974f8897769f0190d17dbec82ae3c7c52edd4a73bb3306fcdda
6
+ metadata.gz: a0d7722513aefbdc19e1f17fb9d66b72e79669fae2b56ab9116b94fbb5e865622f2d810cae560ec65d6163f692ad21b37e3efeba6929cc4f6d3b9d6b95992082
7
+ data.tar.gz: a1f7611e929b6542036fcac93584cd1888a26f1f4e09fe3dbd1d942364efc32da607709cf9dc146e3d65259abdcd6099660abdad9c360296e9c4556daff4c67f
data/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # exa-ruby
2
2
 
3
- Ruby client for the Exa.ai API. Search and analyze web content using neural search, question answering, code discovery, and research automation.
3
+ Ruby client for the Exa.ai API. Search and analyze web content using neural search, question answering, code discovery, and agent-based research.
4
4
 
5
5
  ## Table of Contents
6
6
 
@@ -161,11 +161,6 @@ exa-ai answer "What is machine learning?"
161
161
  exa-ai context "React hooks" --tokens-num 5000
162
162
  exa-ai get-contents "https://ruby-lang.org"
163
163
 
164
- # Research Commands
165
- exa-ai research-start --instructions "What species of ant are similar to honeypot ants?"
166
- exa-ai research-get RESEARCH_ID
167
- exa-ai research-list
168
-
169
164
  # Webset Management
170
165
  exa-ai webset-create --search '{"query":"technology companies","count":1}'
171
166
  exa-ai webset-list --limit 5
@@ -216,10 +211,6 @@ The gem provides complete access to Exa's API endpoints:
216
211
  - **Context** — Find relevant code and documentation snippets
217
212
  - **Get Contents** — Extract full text content from web pages
218
213
 
219
- ### Research
220
- - **Research Tasks** — Start and manage long-running research tasks with AI
221
- - **Task Management** — Get status updates and list all research tasks
222
-
223
214
  ### Websets
224
215
  - **Webset Management** — Create, update, delete, and list datasets of web pages
225
216
  - **Webset Searches** — Run searches within websets and manage search tasks
@@ -232,7 +223,7 @@ The gem provides complete access to Exa's API endpoints:
232
223
 
233
224
  ## Agent
234
225
 
235
- Exa's Agent API runs asynchronous research agents that search the web, synthesize findings, and return structured output with source citations. Runs are long-lived — create one, poll for completion, and stream events as it progresses.
226
+ Exa's Agent API runs asynchronous research agents that search the web, synthesize findings, and return structured output with source citations. Runs are long-lived — create one, poll for completion, and stream events as it progresses. Exa retired the Research API; the Agent API (`exa-ai agent-run-create` and related commands) is its replacement. Pass your prompt as `--query` (Ruby: `query:`), not `--instructions`.
236
227
 
237
228
  ### Ruby API
238
229
 
data/exe/exa-ai CHANGED
@@ -12,9 +12,6 @@ module ExaCLI
12
12
  "answer" => "Generate an answer to a question",
13
13
  "context" => "Get code context from repositories",
14
14
  "get-contents" => "Retrieve page contents",
15
- "research-start" => "Start a research task",
16
- "research-get" => "Get research task status",
17
- "research-list" => "List research tasks",
18
15
  "webset-create" => "Create a new webset",
19
16
  "webset-get" => "Get webset details",
20
17
  "webset-list" => "List websets",
@@ -74,12 +71,6 @@ module ExaCLI
74
71
  exec File.expand_path("../exa-ai-context", __FILE__), *ARGV[1..]
75
72
  when "get-contents"
76
73
  exec File.expand_path("../exa-ai-get-contents", __FILE__), *ARGV[1..]
77
- when "research-start"
78
- exec File.expand_path("../exa-ai-research-start", __FILE__), *ARGV[1..]
79
- when "research-get"
80
- exec File.expand_path("../exa-ai-research-get", __FILE__), *ARGV[1..]
81
- when "research-list"
82
- exec File.expand_path("../exa-ai-research-list", __FILE__), *ARGV[1..]
83
74
  when "webset-create"
84
75
  exec File.expand_path("../exa-ai-webset-create", __FILE__), *ARGV[1..]
85
76
  when "webset-get"
@@ -152,6 +143,9 @@ module ExaCLI
152
143
  exec File.expand_path("../exa-ai-agent-run-delete", __FILE__), *ARGV[1..]
153
144
  when "agent-run-events"
154
145
  exec File.expand_path("../exa-ai-agent-run-events", __FILE__), *ARGV[1..]
146
+ when "research-start", "research-get", "research-list"
147
+ $stderr.puts "Error: Exa retired the Research API. Use 'exa-ai agent-run-create --query TEXT' instead."
148
+ exit 1
155
149
  else
156
150
  print_error_for_command(ARGV[0])
157
151
  exit 1
@@ -172,12 +166,6 @@ module ExaCLI
172
166
  ["get-contents", "Retrieve page contents"]
173
167
  ])
174
168
 
175
- print_command_section("Research", [
176
- ["research-start", "Start a research task"],
177
- ["research-get", "Get research task status"],
178
- ["research-list", "List research tasks"]
179
- ])
180
-
181
169
  print_command_section("Websets", [
182
170
  ["webset-create", "Create a new webset"],
183
171
  ["webset-get", "Get webset details"],
@@ -242,7 +230,7 @@ module ExaCLI
242
230
  puts "Examples:"
243
231
  puts " exa-ai search 'ruby programming'"
244
232
  puts " exa-ai context 'React hooks' --tokens-num 5000"
245
- puts " exa-ai research-start --instructions 'Find AI papers'"
233
+ puts " exa-ai agent-run-create --query 'Find AI papers'"
246
234
  end
247
235
 
248
236
  def self.print_command_section(title, commands)
@@ -2,6 +2,7 @@
2
2
  # frozen_string_literal: true
3
3
 
4
4
  require "exa-ai"
5
+ require_relative "../lib/exa/cli/search_parser"
5
6
 
6
7
  # Parse command-line arguments
7
8
  def parse_args(argv)
@@ -24,7 +25,7 @@ def parse_args(argv)
24
25
  i += 1
25
26
  when "--category"
26
27
  category = argv[i + 1]
27
- valid_categories = ["company", "research paper", "news", "pdf", "github", "tweet", "personal site", "linkedin profile", "financial report"]
28
+ valid_categories = Exa::CLI::SearchParser::VALID_CATEGORIES
28
29
  unless valid_categories.include?(category)
29
30
  $stderr.puts "Error: Category must be one of: #{valid_categories.map { |c| "\"#{c}\"" }.join(', ')}"
30
31
  exit 1
@@ -99,9 +100,8 @@ def parse_args(argv)
99
100
  --num-results N Number of results to return (default: 10)
100
101
  --exclude-source-domain Exclude results from the source URL's domain
101
102
  --category CAT Focus on specific data category
102
- Options: "company", "research paper", "news", "pdf",
103
- "github", "tweet", "personal site", "linkedin profile",
104
- "financial report"
103
+ Options: "company", "publication", "news", "github",
104
+ "personal site", "people", "financial report"
105
105
  --include-domains D Comma-separated list of domains to include
106
106
  --exclude-domains D Comma-separated list of domains to exclude
107
107
  --start-published-date DATE Filter by published date (ISO 8601 format)
@@ -127,7 +127,7 @@ def parse_args(argv)
127
127
  Examples:
128
128
  exa-ai find-similar "https://example.com/article"
129
129
  exa-ai find-similar "https://techcrunch.com/ai-startup" --num-results 5
130
- exa-ai find-similar "https://arxiv.org/paper" --category "research paper"
130
+ exa-ai find-similar "https://arxiv.org/paper" --category publication
131
131
  exa-ai find-similar "https://example.com" --exclude-source-domain
132
132
  exa-ai find-similar "https://example.com" --output-format pretty
133
133
  HELP
data/exe/exa-ai-search CHANGED
@@ -17,9 +17,11 @@ def print_help
17
17
  --num-results N Number of results to return (default: 10)
18
18
  --type TYPE Search type: auto, neural, fast, deep, deep-reasoning,
19
19
  or instant (default: auto)
20
+ deep/deep-reasoning synthesize an 'output' field
21
+ only when --output-schema is provided
20
22
  --category CAT Focus on specific data category
21
- Options: "company", "research paper", "news", "github",
22
- "tweet", "personal site", "financial report", "people"
23
+ Options: "company", "publication", "news", "github",
24
+ "personal site", "people", "financial report"
23
25
  --include-domains D Comma-separated list of domains to include
24
26
  --exclude-domains D Comma-separated list of domains to exclude
25
27
  --start-published-date DATE Filter by published date (ISO 8601 format)
@@ -55,6 +57,7 @@ def print_help
55
57
  Search Options:
56
58
  --additional-queries QUERY Additional search queries (repeatable)
57
59
  --output-schema JSON JSON schema for output structure (@file syntax)
60
+ Required to get synthesized 'output' from deep/deep-reasoning
58
61
  --user-location CODE User location (ISO country code)
59
62
  --system-prompt PROMPT System prompt for AI-powered search
60
63
  --moderation Enable content moderation
@@ -67,7 +70,7 @@ def print_help
67
70
  Examples:
68
71
  exa-ai search "ruby programming"
69
72
  exa-ai search "machine learning" --num-results 5 --type deep
70
- exa-ai search "Latest LLM research" --category "research paper"
73
+ exa-ai search "Latest LLM research" --category publication
71
74
  exa-ai search "AI startups" --category company
72
75
  exa-ai search "Dario Amodei" --category people
73
76
  exa-ai search "AI research" --include-domains arxiv.org,scholar.google.com
@@ -6,8 +6,8 @@ module Exa
6
6
  VALID_SEARCH_TYPES = ["auto", "neural", "fast", "deep", "deep-reasoning", "instant"].freeze
7
7
  VALID_TEXT_VERBOSITY = ["compact", "standard", "full"].freeze
8
8
  VALID_CATEGORIES = [
9
- "company", "research paper", "news", "github",
10
- "tweet", "personal site", "financial report", "people"
9
+ "company", "publication", "news", "github",
10
+ "personal site", "people", "financial report"
11
11
  ].freeze
12
12
 
13
13
  def self.parse(argv)
data/lib/exa/client.rb CHANGED
@@ -4,7 +4,7 @@ module Exa
4
4
  # Main client for interacting with the Exa.ai API
5
5
  #
6
6
  # Provides methods for all supported Exa.ai operations including search,
7
- # content retrieval, answer generation, and async research tasks.
7
+ # content retrieval, answer generation, and agent runs.
8
8
  #
9
9
  # @example Basic usage
10
10
  # client = Exa::Client.new(api_key: "your-key")
@@ -86,32 +86,6 @@ module Exa
86
86
  Services::AnswerStream.new(connection, query: query, **options).call(&block)
87
87
  end
88
88
 
89
- # Start an asynchronous research task
90
- #
91
- # @param params [Hash] Research parameters
92
- # @return [Resources::Research] Research task with ID
93
- def research_start(**params)
94
- Services::ResearchStart.new(connection, **params).call
95
- end
96
-
97
- # List all research tasks
98
- #
99
- # @param params [Hash] Listing parameters
100
- # @option params [Integer] :limit Maximum number of tasks to return
101
- # @return [Resources::ResearchList] List of research tasks
102
- def research_list(**params)
103
- Services::ResearchList.new(connection, **params).call
104
- end
105
-
106
- # Get status and results of a research task
107
- #
108
- # @param research_id [String] Research task ID
109
- # @param params [Hash] Fetch options
110
- # @return [Resources::Research] Research task with current status and results
111
- def research_get(research_id, **params)
112
- Services::ResearchGet.new(connection, research_id: research_id, **params).call
113
- end
114
-
115
89
  # Create a new agent run
116
90
  #
117
91
  # @param query [String] The query or task for the agent to execute (required)
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require "faraday"
4
+ require "json"
4
5
 
5
6
  module Exa
6
7
  module Middleware
@@ -29,6 +30,10 @@ module Exa
29
30
  handle_error(env, Exa::ServiceUnavailable)
30
31
  when 504
31
32
  handle_error(env, Exa::GatewayTimeout)
33
+ when 400..499
34
+ handle_error(env, Exa::ClientError)
35
+ when 500..599
36
+ handle_error(env, Exa::ServerError)
32
37
  end
33
38
  end
34
39
 
@@ -41,6 +46,7 @@ module Exa
41
46
 
42
47
  def extract_error_message(env)
43
48
  body = env[:body]
49
+ body = parse_streamed_error_body(env) if body.nil? || body == ""
44
50
 
45
51
  if body.is_a?(Hash)
46
52
  # Prioritize "message" field for detailed error descriptions
@@ -54,6 +60,14 @@ module Exa
54
60
 
55
61
  "HTTP #{env[:status]}"
56
62
  end
63
+
64
+ # Streaming requests hand the body to on_data, so the adapter leaves
65
+ # env[:body] empty. Stream services keep error chunks in env[:error_body].
66
+ def parse_streamed_error_body(env)
67
+ JSON.parse(env[:error_body].to_s)
68
+ rescue JSON::ParserError
69
+ nil
70
+ end
57
71
  end
58
72
  end
59
73
  end
@@ -33,7 +33,9 @@ module Exa
33
33
 
34
34
  @connection.post("/agent/runs", body) do |req|
35
35
  req.headers["Accept"] = "text/event-stream"
36
- req.options.on_data = proc do |chunk|
36
+ req.options.on_data = proc do |chunk, _size, env|
37
+ next env[:error_body] = "#{env[:error_body]}#{chunk}" if env&.status.to_i >= 400
38
+
37
39
  @buffer += chunk
38
40
  process_sse_buffer(&interceptor)
39
41
  end
@@ -16,7 +16,9 @@ module Exa
16
16
 
17
17
  # Configure the request to stream chunks via on_data callback
18
18
  @connection.post("/answer", @params) do |req|
19
- req.options.on_data = proc do |chunk|
19
+ req.options.on_data = proc do |chunk, _size, env|
20
+ next env[:error_body] = "#{env[:error_body]}#{chunk}" if env&.status.to_i >= 400
21
+
20
22
  # Add chunk to buffer and process complete SSE events
21
23
  @buffer += chunk
22
24
  process_sse_buffer(&block)
@@ -44,6 +44,7 @@ module Exa
44
44
  file_content = File.read(@file_path)
45
45
 
46
46
  upload_connection = Faraday.new do |f|
47
+ f.response :raise_error
47
48
  f.adapter Faraday.default_adapter
48
49
  end
49
50
 
data/lib/exa/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Exa
4
- VERSION = "0.12.1"
4
+ VERSION = "0.13.0"
5
5
  end
data/lib/exa.rb CHANGED
@@ -10,8 +10,6 @@ require_relative "exa/connection"
10
10
  require_relative "exa/resources/search_result"
11
11
  require_relative "exa/resources/find_similar_result"
12
12
  require_relative "exa/resources/contents_result"
13
- require_relative "exa/resources/research_task"
14
- require_relative "exa/resources/research_list"
15
13
  require_relative "exa/resources/agent_run"
16
14
  require_relative "exa/resources/agent_run_list"
17
15
  require_relative "exa/resources/agent_run_event_list"
@@ -32,9 +30,6 @@ require_relative "exa/resources/monitor_run_collection"
32
30
  require_relative "exa/services/search"
33
31
  require_relative "exa/services/find_similar"
34
32
  require_relative "exa/services/get_contents"
35
- require_relative "exa/services/research_get"
36
- require_relative "exa/services/research_start"
37
- require_relative "exa/services/research_list"
38
33
  require_relative "exa/services/agent_run_create"
39
34
  require_relative "exa/services/agent_run_stream"
40
35
  require_relative "exa/services/agent_run_get"
@@ -83,7 +78,6 @@ require_relative "exa/cli/formatters/search_formatter"
83
78
  require_relative "exa/cli/formatters/webset_search_formatter"
84
79
  require_relative "exa/cli/formatters/context_formatter"
85
80
  require_relative "exa/cli/formatters/contents_formatter"
86
- require_relative "exa/cli/formatters/research_formatter"
87
81
  require_relative "exa/cli/formatters/agent_run_formatter"
88
82
  require_relative "exa/cli/formatters/answer_formatter"
89
83
  require_relative "exa/cli/formatters/webset_formatter"
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: exa-ai
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.12.1
4
+ version: 0.13.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Benjamin Jackson
@@ -174,9 +174,6 @@ files:
174
174
  - exe/exa-ai-monitor-runs-get
175
175
  - exe/exa-ai-monitor-runs-list
176
176
  - exe/exa-ai-monitor-update
177
- - exe/exa-ai-research-get
178
- - exe/exa-ai-research-list
179
- - exe/exa-ai-research-start
180
177
  - exe/exa-ai-search
181
178
  - exe/exa-ai-webset-cancel
182
179
  - exe/exa-ai-webset-create
@@ -202,7 +199,6 @@ files:
202
199
  - lib/exa/cli/formatters/import_formatter.rb
203
200
  - lib/exa/cli/formatters/monitor_formatter.rb
204
201
  - lib/exa/cli/formatters/monitor_run_formatter.rb
205
- - lib/exa/cli/formatters/research_formatter.rb
206
202
  - lib/exa/cli/formatters/search_formatter.rb
207
203
  - lib/exa/cli/formatters/webset_formatter.rb
208
204
  - lib/exa/cli/formatters/webset_item_formatter.rb
@@ -227,8 +223,6 @@ files:
227
223
  - lib/exa/resources/monitor_collection.rb
228
224
  - lib/exa/resources/monitor_run.rb
229
225
  - lib/exa/resources/monitor_run_collection.rb
230
- - lib/exa/resources/research_list.rb
231
- - lib/exa/resources/research_task.rb
232
226
  - lib/exa/resources/search_result.rb
233
227
  - lib/exa/resources/webset.rb
234
228
  - lib/exa/resources/webset_collection.rb
@@ -249,9 +243,6 @@ files:
249
243
  - lib/exa/services/find_similar.rb
250
244
  - lib/exa/services/get_contents.rb
251
245
  - lib/exa/services/parameter_converter.rb
252
- - lib/exa/services/research_get.rb
253
- - lib/exa/services/research_list.rb
254
- - lib/exa/services/research_start.rb
255
246
  - lib/exa/services/search.rb
256
247
  - lib/exa/services/websets/cancel.rb
257
248
  - lib/exa/services/websets/cancel_enrichment.rb
@@ -308,7 +299,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
308
299
  - !ruby/object:Gem::Version
309
300
  version: '0'
310
301
  requirements: []
311
- rubygems_version: 3.7.2
302
+ rubygems_version: 3.6.9
312
303
  specification_version: 4
313
304
  summary: Ruby client for the Exa.ai API
314
305
  test_files: []
@@ -1,109 +0,0 @@
1
- #!/usr/bin/env ruby
2
- # frozen_string_literal: true
3
-
4
- require "exa-ai"
5
-
6
- # Parse command-line arguments
7
- api_key = nil
8
- research_id = nil
9
- events = false
10
- stream = false
11
- output_format = "json"
12
-
13
- args = ARGV.dup
14
- while args.any?
15
- arg = args.shift
16
- case arg
17
- when "--api-key"
18
- api_key = args.shift
19
- when "--events"
20
- events = true
21
- when "--stream"
22
- stream = true
23
- when "--output-format"
24
- output_format = args.shift
25
- when "--help", "-h"
26
- puts <<~HELP
27
- Usage: exa-ai research-get <research_id> [options]
28
-
29
- Get the status and results of a research task.
30
-
31
- Arguments:
32
- research_id ID of the research task to retrieve
33
-
34
- Options:
35
- --api-key KEY Exa API key (or use EXA_API_KEY env var)
36
- --events Include task execution events in response
37
- --stream Stream the response (for real-time updates)
38
- --output-format FORMAT Output format: json, pretty, or text (default: json)
39
- --help, -h Show this help message
40
-
41
- Examples:
42
- exa-ai research-get research_123
43
- exa-ai research-get research_123 --events
44
- exa-ai research-get research_123 --stream
45
- exa-ai research-get research_123 --output-format pretty
46
- HELP
47
- exit 0
48
- else
49
- # First positional argument is the research_id
50
- if research_id.nil?
51
- research_id = arg
52
- else
53
- warn "Unknown option: #{arg}"
54
- exit 1
55
- end
56
- end
57
- end
58
-
59
- # Validate required arguments
60
- if research_id.nil?
61
- warn "Error: Research ID argument required"
62
- warn "Usage: exa-ai research-get <research_id> [options]"
63
- warn "Try 'exa-ai research-get --help' for more information"
64
- exit 1
65
- end
66
-
67
- begin
68
- # Resolve API key
69
- api_key = Exa::CLI::Base.resolve_api_key(api_key)
70
-
71
- # Build client
72
- client = Exa::CLI::Base.build_client(api_key)
73
-
74
- # Build parameters
75
- params = {}
76
- params[:events] = events if events
77
- params[:stream] = stream if stream
78
-
79
- # Call API
80
- result = client.research_get(research_id, **params)
81
-
82
- # Format output
83
- formatted = Exa::CLI::Formatters::ResearchFormatter.format_task(
84
- result,
85
- output_format,
86
- show_events: events
87
- )
88
- puts formatted
89
-
90
- rescue Exa::NotFound => e
91
- warn "Research task not found: #{e.message}"
92
- exit 1
93
- rescue Exa::Unauthorized => e
94
- warn "Authentication failed: #{e.message}"
95
- warn "Please provide a valid API key via --api-key or EXA_API_KEY environment variable"
96
- exit 1
97
- rescue Exa::ClientError => e
98
- warn "Client error: #{e.message}"
99
- exit 1
100
- rescue Exa::ServerError => e
101
- warn "Server error: #{e.message}"
102
- exit 1
103
- rescue Exa::Error => e
104
- warn "Error: #{e.message}"
105
- exit 1
106
- rescue StandardError => e
107
- warn "Unexpected error: #{e.message}"
108
- exit 1
109
- end
@@ -1,94 +0,0 @@
1
- #!/usr/bin/env ruby
2
- # frozen_string_literal: true
3
-
4
- require "exa-ai"
5
-
6
- # Parse command-line arguments
7
- api_key = nil
8
- cursor = nil
9
- limit = 10
10
- output_format = "json"
11
-
12
- args = ARGV.dup
13
- while args.any?
14
- arg = args.shift
15
- case arg
16
- when "--api-key"
17
- api_key = args.shift
18
- when "--cursor"
19
- cursor = args.shift
20
- when "--limit"
21
- limit = args.shift.to_i
22
- when "--output-format"
23
- output_format = args.shift
24
- when "--help", "-h"
25
- puts <<~HELP
26
- Usage: exa-ai research-list [options]
27
-
28
- List research tasks with cursor-based pagination.
29
-
30
- Options:
31
- --api-key KEY Exa API key (or use EXA_API_KEY env var)
32
- --cursor CURSOR Pagination cursor for next page
33
- --limit LIMIT Number of results per page (default: 10)
34
- --output-format FORMAT Output format: json, pretty, or text (default: json)
35
- --help, -h Show this help message
36
-
37
- Examples:
38
- exa-ai research-list
39
- exa-ai research-list --limit 20
40
- exa-ai research-list --cursor next_page_cursor
41
- exa-ai research-list --output-format pretty
42
- HELP
43
- exit 0
44
- else
45
- warn "Unknown option: #{arg}"
46
- exit 1
47
- end
48
- end
49
-
50
- begin
51
- # Resolve API key
52
- api_key = Exa::CLI::Base.resolve_api_key(api_key)
53
-
54
- # Build client
55
- client = Exa::CLI::Base.build_client(api_key)
56
-
57
- # Build parameters
58
- params = {limit: limit}
59
- params[:cursor] = cursor if cursor
60
-
61
- # Call API
62
- result = client.research_list(**params)
63
-
64
- # Format output
65
- formatted = Exa::CLI::Formatters::ResearchFormatter.format_list(result, output_format)
66
- puts formatted
67
-
68
- # Show pagination info if there are more results
69
- if result.has_more && result.next_cursor
70
- if output_format == "pretty"
71
- puts "\n" + "=" * 80
72
- puts "More results available. Use --cursor #{result.next_cursor} to get next page."
73
- else
74
- warn "More results available. Use --cursor #{result.next_cursor} to get next page."
75
- end
76
- end
77
-
78
- rescue Exa::Unauthorized => e
79
- warn "Authentication failed: #{e.message}"
80
- warn "Please provide a valid API key via --api-key or EXA_API_KEY environment variable"
81
- exit 1
82
- rescue Exa::ClientError => e
83
- warn "Client error: #{e.message}"
84
- exit 1
85
- rescue Exa::ServerError => e
86
- warn "Server error: #{e.message}"
87
- exit 1
88
- rescue Exa::Error => e
89
- warn "Error: #{e.message}"
90
- exit 1
91
- rescue StandardError => e
92
- warn "Unexpected error: #{e.message}"
93
- exit 1
94
- end
@@ -1,174 +0,0 @@
1
- #!/usr/bin/env ruby
2
- # frozen_string_literal: true
3
-
4
- require "exa-ai"
5
-
6
- # Parse command-line arguments
7
- def parse_args(argv)
8
- args = {
9
- output_format: "json",
10
- api_key: nil,
11
- events: false,
12
- wait: false
13
- }
14
-
15
- i = 0
16
- while i < argv.length
17
- arg = argv[i]
18
- case arg
19
- when "--instructions"
20
- args[:instructions] = argv[i + 1]
21
- i += 2
22
- when "--model"
23
- args[:model] = argv[i + 1]
24
- i += 2
25
- when "--output-schema"
26
- args[:output_schema] = argv[i + 1]
27
- i += 2
28
- when "--wait"
29
- args[:wait] = true
30
- i += 1
31
- when "--events"
32
- args[:events] = true
33
- i += 1
34
- when "--api-key"
35
- args[:api_key] = argv[i + 1]
36
- i += 2
37
- when "--output-format"
38
- args[:output_format] = argv[i + 1]
39
- i += 2
40
- when "--help", "-h"
41
- puts <<~HELP
42
- Usage: exa-ai research-start --instructions "TEXT" [OPTIONS]
43
-
44
- Start a research task using Exa AI
45
-
46
- Options:
47
- --instructions TEXT Research instructions (required)
48
- --model MODEL Research model: exa-research (default), exa-research-pro, exa-research-fast
49
- --output-schema JSON JSON schema string for structured output
50
- --wait Wait for task to complete (polls until done)
51
- --events Include event log in output (only with --wait)
52
- --api-key KEY Exa API key (or set EXA_API_KEY env var)
53
- --output-format FMT Output format: json, pretty, or text (default: json)
54
- --help, -h Show this help message
55
-
56
- Examples:
57
- exa-ai research-start --instructions "Find Ruby performance tips"
58
- exa-ai research-start --instructions "Analyze AI trends" --wait --events
59
- exa-ai research-start --instructions "Summarize papers" --model exa-research-pro --wait
60
- exa-ai research-start --instructions "Find stats" --output-schema '{"type":"object"}'
61
- HELP
62
- exit 0
63
- else
64
- i += 1
65
- end
66
- end
67
-
68
- args
69
- end
70
-
71
- # Main execution
72
- begin
73
- args = parse_args(ARGV)
74
-
75
- # Validate instructions
76
- if args[:instructions].nil? || args[:instructions].empty?
77
- $stderr.puts "Error: --instructions flag is required"
78
- $stderr.puts "Run 'exa-ai research-start --help' for usage information"
79
- exit 1
80
- end
81
-
82
- # Resolve API key
83
- api_key = Exa::CLI::Base.resolve_api_key(args[:api_key])
84
-
85
- # Resolve output format
86
- output_format = Exa::CLI::Base.resolve_output_format(args[:output_format])
87
-
88
- # Build client
89
- client = Exa::CLI::Base.build_client(api_key)
90
-
91
- # Prepare research parameters
92
- research_params = { instructions: args[:instructions] }
93
- research_params[:model] = args[:model] if args[:model]
94
-
95
- # Parse output_schema as JSON if provided
96
- if args[:output_schema]
97
- begin
98
- research_params[:output_schema] = JSON.parse(args[:output_schema])
99
- rescue JSON::ParserError => e
100
- $stderr.puts "Error: Invalid JSON in --output-schema: #{e.message}"
101
- exit 1
102
- end
103
- end
104
-
105
- # Start research task
106
- task = client.research_start(**research_params)
107
-
108
- # If --wait flag is set, poll until task completes
109
- if args[:wait]
110
- $stderr.print "Starting research task... "
111
-
112
- begin
113
- final_task = Exa::CLI::Polling.poll(max_duration: 300, initial_delay: 2, max_delay: 10) do
114
- # Get current task status
115
- current_task = client.research_get(task.research_id, events: args[:events])
116
-
117
- # Show progress indicator
118
- case current_task.status
119
- when "pending"
120
- $stderr.print "⏳"
121
- when "running"
122
- $stderr.print "⚙️"
123
- end
124
-
125
- # Check if done
126
- done = current_task.finished?
127
-
128
- { done: done, result: current_task, status: current_task.status }
129
- end
130
-
131
- $stderr.puts " #{final_task.status.upcase}"
132
-
133
- # Format and output final result
134
- output = Exa::CLI::Formatters::ResearchFormatter.format_task(final_task, output_format, show_events: args[:events])
135
- puts output
136
- $stdout.flush
137
-
138
- # Exit with error code if task failed
139
- exit 1 if final_task.failed?
140
-
141
- rescue Exa::CLI::Polling::TimeoutError => e
142
- $stderr.puts "\nError: Task did not complete within timeout period (5 minutes)"
143
- $stderr.puts "Task ID: #{task.research_id}"
144
- $stderr.puts "You can check the status later with: exa-ai research-get #{task.research_id}"
145
- exit 1
146
- end
147
- else
148
- # Just return the initial task (with status "pending")
149
- output = Exa::CLI::Formatters::ResearchFormatter.format_task(task, output_format, show_events: false)
150
- puts output
151
- end
152
-
153
- rescue Exa::ConfigurationError => e
154
- $stderr.puts "Configuration error: #{e.message}"
155
- exit 1
156
- rescue Exa::Unauthorized => e
157
- $stderr.puts "Authentication error: #{e.message}"
158
- $stderr.puts "Check your API key (set EXA_API_KEY or use --api-key)"
159
- exit 1
160
- rescue Exa::ClientError => e
161
- $stderr.puts "Client error: #{e.message}"
162
- exit 1
163
- rescue Exa::ServerError => e
164
- $stderr.puts "Server error: #{e.message}"
165
- $stderr.puts "The Exa API may be experiencing issues. Please try again later."
166
- exit 1
167
- rescue Exa::Error => e
168
- $stderr.puts "Error: #{e.message}"
169
- exit 1
170
- rescue StandardError => e
171
- $stderr.puts "Unexpected error: #{e.message}"
172
- $stderr.puts e.backtrace.first(5) if ENV["DEBUG"]
173
- exit 1
174
- end
@@ -1,124 +0,0 @@
1
- module Exa
2
- module CLI
3
- module Formatters
4
- class ResearchFormatter
5
- def self.format_task(task, format, show_events: false)
6
- case format
7
- when "json"
8
- JSON.pretty_generate(task.to_h)
9
- when "pretty"
10
- format_task_pretty(task, show_events: show_events)
11
- when "text"
12
- format_task_text(task, show_events: show_events)
13
- when "toon"
14
- Exa::CLI::Base.encode_as_toon(task.to_h)
15
- else
16
- JSON.pretty_generate(task.to_h)
17
- end
18
- end
19
-
20
- def self.format_list(list, format)
21
- case format
22
- when "json"
23
- JSON.pretty_generate(list.to_h)
24
- when "pretty"
25
- format_list_pretty(list)
26
- when "text"
27
- format_list_text(list)
28
- when "toon"
29
- Exa::CLI::Base.encode_as_toon(list.to_h)
30
- else
31
- JSON.pretty_generate(list.to_h)
32
- end
33
- end
34
-
35
- private
36
-
37
- def self.format_task_pretty(task, show_events: false)
38
- output = []
39
- output << "Research Task: #{task.research_id}"
40
- output << "Status: #{task.status.upcase}"
41
- output << "Created: #{task.created_at}"
42
- output << ""
43
-
44
- case task.status
45
- when "pending"
46
- output << "Task is pending execution..."
47
- when "running"
48
- output << "Task is running... ⚙️"
49
- when "completed"
50
- output << "Output:"
51
- output << "--------"
52
- output << task.output.to_s
53
- output << ""
54
- output << "Cost: $#{task.cost_dollars}" if task.cost_dollars
55
- when "failed"
56
- output << "Error: #{task.error}"
57
- when "canceled"
58
- output << "Task was canceled"
59
- output << "Finished: #{task.finished_at}" if task.finished_at
60
- end
61
-
62
- if show_events && task.events && !task.events.empty?
63
- output << ""
64
- output << "Events:"
65
- output << "-------"
66
- task.events.each do |event|
67
- output << "- #{event}"
68
- end
69
- end
70
-
71
- output.join("\n")
72
- end
73
-
74
- def self.format_list_pretty(list)
75
- output = []
76
- output << "Research Tasks (#{list.data.length}):"
77
- output << ""
78
-
79
- if list.data.empty?
80
- output << "No tasks found."
81
- else
82
- # Simple table format
83
- output << "%-40s %-15s %s" % ["Task ID", "Status", "Created"]
84
- output << "-" * 70
85
-
86
- list.data.each do |task|
87
- task_id = task.research_id.to_s[0..38]
88
- status = task.status.upcase[0..14]
89
- created = task.created_at.to_s[0..19]
90
- output << "%-40s %-15s %s" % [task_id, status, created]
91
- end
92
- end
93
-
94
- output << ""
95
- if list.has_more
96
- output << "More results available. Use --cursor #{list.next_cursor} for next page."
97
- else
98
- output << "End of results."
99
- end
100
-
101
- output.join("\n")
102
- end
103
-
104
- def self.format_task_text(task, show_events: false)
105
- output = []
106
- output << "#{task.research_id} #{task.status.upcase} #{task.created_at}"
107
- if task.status == "completed"
108
- output << task.output.to_s
109
- elsif task.status == "failed"
110
- output << "Error: #{task.error}"
111
- end
112
- output.join("\n")
113
- end
114
-
115
- def self.format_list_text(list)
116
- output = list.data.map do |task|
117
- "#{task.research_id} #{task.status.upcase} #{task.created_at}"
118
- end
119
- output.join("\n")
120
- end
121
- end
122
- end
123
- end
124
- end
@@ -1,18 +0,0 @@
1
- module Exa
2
- module Resources
3
- class ResearchList < Struct.new(:data, :has_more, :next_cursor, keyword_init: true)
4
- def initialize(data:, has_more:, next_cursor: nil)
5
- super
6
- freeze
7
- end
8
-
9
- def to_h
10
- {
11
- data: data.map { |item| item.respond_to?(:to_h) ? item.to_h : item },
12
- has_more: has_more,
13
- next_cursor: next_cursor
14
- }
15
- end
16
- end
17
- end
18
- end
@@ -1,39 +0,0 @@
1
- module Exa
2
- module Resources
3
- class ResearchTask < Struct.new(
4
- :research_id, :created_at, :status, :model, :instructions,
5
- :output_schema, :events, :output, :cost_dollars, :finished_at,
6
- :error, keyword_init: true
7
- )
8
- def initialize(research_id:, created_at:, status:, instructions:, model: nil, output_schema: nil, events: nil, output: nil, cost_dollars: nil, finished_at: nil, error: nil)
9
- super
10
- freeze
11
- end
12
-
13
- def pending? = status == 'pending'
14
- def running? = status == 'running'
15
- def completed? = status == 'completed'
16
- def failed? = status == 'failed'
17
- def canceled? = status == 'canceled'
18
-
19
- def finished? = !running? && !pending?
20
-
21
- def to_h
22
- result = {
23
- research_id: research_id,
24
- created_at: created_at,
25
- status: status,
26
- instructions: instructions
27
- }
28
- result[:model] = model if model
29
- result[:output_schema] = output_schema if output_schema
30
- result[:events] = events if events
31
- result[:output] = output if output
32
- result[:cost_dollars] = cost_dollars if cost_dollars
33
- result[:finished_at] = finished_at if finished_at
34
- result[:error] = error if error
35
- result
36
- end
37
- end
38
- end
39
- end
@@ -1,30 +0,0 @@
1
- module Exa
2
- module Services
3
- class ResearchGet
4
- def initialize(connection, research_id:, **params)
5
- @connection = connection
6
- @research_id = research_id
7
- @params = params
8
- end
9
-
10
- def call
11
- response = @connection.get("/research/v1/#{@research_id}", @params)
12
- body = response.body
13
-
14
- Resources::ResearchTask.new(
15
- research_id: body["researchId"],
16
- created_at: body["createdAt"],
17
- status: body["status"],
18
- instructions: body["instructions"],
19
- model: body["model"],
20
- output_schema: body["outputSchema"],
21
- events: body["events"],
22
- output: body["output"],
23
- cost_dollars: body["costDollars"],
24
- finished_at: body["finishedAt"],
25
- error: body["error"]
26
- )
27
- end
28
- end
29
- end
30
- end
@@ -1,37 +0,0 @@
1
- module Exa
2
- module Services
3
- class ResearchList
4
- def initialize(connection, **params)
5
- @connection = connection
6
- @params = params
7
- end
8
-
9
- def call
10
- response = @connection.get("/research/v1", @params)
11
- body = response.body
12
-
13
- data = body["data"].map do |task_data|
14
- Resources::ResearchTask.new(
15
- research_id: task_data["researchId"],
16
- created_at: task_data["createdAt"],
17
- status: task_data["status"],
18
- instructions: task_data["instructions"],
19
- model: task_data["model"],
20
- output_schema: task_data["outputSchema"],
21
- events: task_data["events"],
22
- output: task_data["output"],
23
- cost_dollars: task_data["costDollars"],
24
- finished_at: task_data["finishedAt"],
25
- error: task_data["error"]
26
- )
27
- end
28
-
29
- Resources::ResearchList.new(
30
- data: data,
31
- has_more: body["hasMore"],
32
- next_cursor: body["nextCursor"]
33
- )
34
- end
35
- end
36
- end
37
- end
@@ -1,26 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module Exa
4
- module Services
5
- class ResearchStart
6
- def initialize(connection, **params)
7
- @connection = connection
8
- @params = params
9
- end
10
-
11
- def call
12
- response = @connection.post("/research/v1", @params)
13
- body = response.body
14
-
15
- Resources::ResearchTask.new(
16
- research_id: body["researchId"],
17
- created_at: body["createdAt"],
18
- status: body["status"],
19
- instructions: body["instructions"],
20
- model: body["model"],
21
- output_schema: body["outputSchema"]
22
- )
23
- end
24
- end
25
- end
26
- end