exa-ai 0.12.2 → 0.14.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.
Files changed (159) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +120 -83
  3. data/exe/exa-ai +45 -152
  4. data/exe/exa-ai-agent-run-create +55 -20
  5. data/exe/exa-ai-agent-run-delete +1 -8
  6. data/exe/exa-ai-agent-run-events +21 -1
  7. data/exe/exa-ai-agent-run-list +1 -1
  8. data/exe/{exa-ai-research-list → exa-ai-agent-run-stop} +31 -32
  9. data/exe/exa-ai-answer +25 -0
  10. data/exe/exa-ai-context +6 -2
  11. data/exe/exa-ai-find-similar +26 -68
  12. data/exe/exa-ai-get-contents +138 -42
  13. data/exe/exa-ai-search +27 -104
  14. data/exe/exa-ai-search-monitor-batch +93 -0
  15. data/exe/exa-ai-search-monitor-create +104 -0
  16. data/exe/exa-ai-search-monitor-delete +69 -0
  17. data/exe/exa-ai-search-monitor-get +69 -0
  18. data/exe/exa-ai-search-monitor-list +73 -0
  19. data/exe/exa-ai-search-monitor-runs-get +68 -0
  20. data/exe/exa-ai-search-monitor-runs-list +75 -0
  21. data/exe/exa-ai-search-monitor-trigger +69 -0
  22. data/exe/exa-ai-search-monitor-update +102 -0
  23. data/lib/exa/cli/base.rb +57 -0
  24. data/lib/exa/cli/contents_flags.rb +199 -0
  25. data/lib/exa/cli/formatters/agent_run_formatter.rb +79 -3
  26. data/lib/exa/cli/formatters/search_formatter.rb +18 -2
  27. data/lib/exa/cli/formatters/search_monitor_formatter.rb +98 -0
  28. data/lib/exa/cli/search_parser.rb +46 -87
  29. data/lib/exa/client.rb +183 -333
  30. data/lib/exa/middleware/raise_error.rb +14 -0
  31. data/lib/exa/resources/agent_run.rb +5 -3
  32. data/lib/exa/resources/agent_run_deletion.rb +17 -0
  33. data/lib/exa/resources/answer.rb +3 -3
  34. data/lib/exa/resources/contents_result.rb +5 -1
  35. data/lib/exa/resources/find_similar_result.rb +5 -1
  36. data/lib/exa/resources/search_monitor.rb +42 -0
  37. data/lib/exa/resources/search_monitor_batch_result.rb +11 -0
  38. data/lib/exa/resources/{research_list.rb → search_monitor_list.rb} +3 -2
  39. data/lib/exa/resources/search_monitor_run.rb +46 -0
  40. data/lib/exa/resources/search_monitor_trigger_result.rb +11 -0
  41. data/lib/exa/resources/search_result.rb +11 -1
  42. data/lib/exa/services/agent_run_cancel.rb +1 -12
  43. data/lib/exa/services/agent_run_create.rb +1 -12
  44. data/lib/exa/services/agent_run_delete.rb +6 -14
  45. data/lib/exa/services/agent_run_events.rb +33 -4
  46. data/lib/exa/services/agent_run_get.rb +1 -12
  47. data/lib/exa/services/agent_run_list.rb +1 -12
  48. data/lib/exa/services/agent_run_stop.rb +21 -0
  49. data/lib/exa/services/agent_run_stream.rb +56 -52
  50. data/lib/exa/services/answer.rb +5 -2
  51. data/lib/exa/services/answer_stream.rb +57 -46
  52. data/lib/exa/services/context.rb +3 -1
  53. data/lib/exa/services/find_similar.rb +9 -2
  54. data/lib/exa/services/get_contents.rb +14 -15
  55. data/lib/exa/services/parameter_converter.rb +128 -111
  56. data/lib/exa/services/search.rb +58 -19
  57. data/lib/exa/services/search_monitors/batch.rb +36 -0
  58. data/lib/exa/services/search_monitors/create.rb +37 -0
  59. data/lib/exa/services/search_monitors/delete.rb +22 -0
  60. data/lib/exa/services/search_monitors/get.rb +22 -0
  61. data/lib/exa/services/search_monitors/list.rb +29 -0
  62. data/lib/exa/services/search_monitors/runs_get.rb +23 -0
  63. data/lib/exa/services/search_monitors/runs_list.rb +29 -0
  64. data/lib/exa/services/search_monitors/trigger.rb +22 -0
  65. data/lib/exa/services/search_monitors/update.rb +42 -0
  66. data/lib/exa/services/search_stream.rb +38 -0
  67. data/lib/exa/version.rb +1 -1
  68. data/lib/exa.rb +18 -56
  69. metadata +31 -94
  70. data/exe/exa-ai-enrichment-cancel +0 -108
  71. data/exe/exa-ai-enrichment-create +0 -226
  72. data/exe/exa-ai-enrichment-delete +0 -122
  73. data/exe/exa-ai-enrichment-get +0 -104
  74. data/exe/exa-ai-enrichment-list +0 -99
  75. data/exe/exa-ai-enrichment-update +0 -171
  76. data/exe/exa-ai-import-create +0 -253
  77. data/exe/exa-ai-import-delete +0 -92
  78. data/exe/exa-ai-import-get +0 -92
  79. data/exe/exa-ai-import-list +0 -72
  80. data/exe/exa-ai-import-update +0 -164
  81. data/exe/exa-ai-monitor-create +0 -223
  82. data/exe/exa-ai-monitor-delete +0 -101
  83. data/exe/exa-ai-monitor-get +0 -92
  84. data/exe/exa-ai-monitor-list +0 -90
  85. data/exe/exa-ai-monitor-runs-get +0 -103
  86. data/exe/exa-ai-monitor-runs-list +0 -110
  87. data/exe/exa-ai-monitor-update +0 -207
  88. data/exe/exa-ai-research-get +0 -109
  89. data/exe/exa-ai-research-start +0 -174
  90. data/exe/exa-ai-webset-cancel +0 -97
  91. data/exe/exa-ai-webset-create +0 -254
  92. data/exe/exa-ai-webset-delete +0 -111
  93. data/exe/exa-ai-webset-get +0 -93
  94. data/exe/exa-ai-webset-item-delete +0 -111
  95. data/exe/exa-ai-webset-item-get +0 -105
  96. data/exe/exa-ai-webset-item-list +0 -108
  97. data/exe/exa-ai-webset-list +0 -91
  98. data/exe/exa-ai-webset-search-cancel +0 -104
  99. data/exe/exa-ai-webset-search-create +0 -247
  100. data/exe/exa-ai-webset-search-get +0 -105
  101. data/exe/exa-ai-webset-update +0 -143
  102. data/lib/exa/cli/formatters/enrichment_formatter.rb +0 -125
  103. data/lib/exa/cli/formatters/import_formatter.rb +0 -153
  104. data/lib/exa/cli/formatters/monitor_formatter.rb +0 -144
  105. data/lib/exa/cli/formatters/monitor_run_formatter.rb +0 -126
  106. data/lib/exa/cli/formatters/research_formatter.rb +0 -124
  107. data/lib/exa/cli/formatters/webset_formatter.rb +0 -134
  108. data/lib/exa/cli/formatters/webset_item_formatter.rb +0 -131
  109. data/lib/exa/cli/formatters/webset_search_formatter.rb +0 -57
  110. data/lib/exa/constants/websets.rb +0 -19
  111. data/lib/exa/resources/import.rb +0 -86
  112. data/lib/exa/resources/import_collection.rb +0 -33
  113. data/lib/exa/resources/monitor.rb +0 -48
  114. data/lib/exa/resources/monitor_collection.rb +0 -30
  115. data/lib/exa/resources/monitor_run.rb +0 -52
  116. data/lib/exa/resources/monitor_run_collection.rb +0 -30
  117. data/lib/exa/resources/research_task.rb +0 -39
  118. data/lib/exa/resources/webset.rb +0 -74
  119. data/lib/exa/resources/webset_collection.rb +0 -33
  120. data/lib/exa/resources/webset_enrichment.rb +0 -71
  121. data/lib/exa/resources/webset_enrichment_collection.rb +0 -28
  122. data/lib/exa/resources/webset_item_collection.rb +0 -33
  123. data/lib/exa/resources/webset_search.rb +0 -112
  124. data/lib/exa/services/research_get.rb +0 -30
  125. data/lib/exa/services/research_list.rb +0 -37
  126. data/lib/exa/services/research_start.rb +0 -26
  127. data/lib/exa/services/websets/cancel.rb +0 -36
  128. data/lib/exa/services/websets/cancel_enrichment.rb +0 -35
  129. data/lib/exa/services/websets/cancel_search.rb +0 -44
  130. data/lib/exa/services/websets/create.rb +0 -45
  131. data/lib/exa/services/websets/create_enrichment.rb +0 -35
  132. data/lib/exa/services/websets/create_search.rb +0 -48
  133. data/lib/exa/services/websets/create_search_validator.rb +0 -128
  134. data/lib/exa/services/websets/create_validator.rb +0 -213
  135. data/lib/exa/services/websets/delete.rb +0 -36
  136. data/lib/exa/services/websets/delete_enrichment.rb +0 -35
  137. data/lib/exa/services/websets/delete_item.rb +0 -20
  138. data/lib/exa/services/websets/get_item.rb +0 -20
  139. data/lib/exa/services/websets/get_search.rb +0 -43
  140. data/lib/exa/services/websets/import_create.rb +0 -40
  141. data/lib/exa/services/websets/import_delete.rb +0 -37
  142. data/lib/exa/services/websets/import_get.rb +0 -37
  143. data/lib/exa/services/websets/import_list.rb +0 -25
  144. data/lib/exa/services/websets/import_update.rb +0 -38
  145. data/lib/exa/services/websets/import_upload.rb +0 -58
  146. data/lib/exa/services/websets/list.rb +0 -25
  147. data/lib/exa/services/websets/list_items.rb +0 -26
  148. data/lib/exa/services/websets/monitors/create.rb +0 -42
  149. data/lib/exa/services/websets/monitors/delete.rb +0 -32
  150. data/lib/exa/services/websets/monitors/get.rb +0 -33
  151. data/lib/exa/services/websets/monitors/list.rb +0 -27
  152. data/lib/exa/services/websets/monitors/runs/get.rb +0 -37
  153. data/lib/exa/services/websets/monitors/runs/list.rb +0 -30
  154. data/lib/exa/services/websets/monitors/update.rb +0 -33
  155. data/lib/exa/services/websets/retrieve.rb +0 -47
  156. data/lib/exa/services/websets/retrieve_enrichment.rb +0 -35
  157. data/lib/exa/services/websets/update.rb +0 -37
  158. data/lib/exa/services/websets/update_enrichment.rb +0 -36
  159. data/lib/exa/services/websets_parameter_converter.rb +0 -45
@@ -3,15 +3,12 @@
3
3
 
4
4
  require "exa-ai"
5
5
 
6
- # Parse a JSON flag value: inline JSON, or @path to read JSON from a file.
7
- def parse_json_arg(value, flag_name)
8
- json = value.to_s.start_with?("@") ? File.read(value.to_s[1..]) : value.to_s
9
- JSON.parse(json)
10
- rescue JSON::ParserError => e
11
- $stderr.puts "Error: #{flag_name} is not valid JSON (#{e.message})"
12
- exit 1
13
- rescue Errno::ENOENT
14
- $stderr.puts "Error: #{flag_name} file not found: #{value.to_s[1..]}"
6
+ # Parse --max-cost-dollars, the only option in the gem that takes a decimal
7
+ # number, so it stays here instead of in Exa::CLI::Base.
8
+ def parse_float(flag, value)
9
+ Float(Exa::CLI::Base.option_value(flag, value))
10
+ rescue ArgumentError
11
+ warn "Error: #{flag} must be a number (got #{value.inspect})"
15
12
  exit 1
16
13
  end
17
14
 
@@ -42,16 +39,33 @@ def parse_args(argv)
42
39
  args[:data_sources] = argv[i + 1].to_s.split(",").map { |s| { provider: s.strip } }
43
40
  i += 2
44
41
  when "--input-data"
45
- args[:input_data] = parse_json_arg(argv[i + 1], "--input-data")
42
+ args[:input_data] = Exa::CLI::Base.parse_json_or_file("--input-data", argv[i + 1])
46
43
  i += 2
47
44
  when "--input-exclusion"
48
- args[:input_exclusion] = parse_json_arg(argv[i + 1], "--input-exclusion")
45
+ args[:input_exclusion] = Exa::CLI::Base.parse_json_or_file("--input-exclusion", argv[i + 1])
49
46
  i += 2
50
47
  when "--previous-run-id"
51
48
  args[:previous_run_id] = argv[i + 1]
52
49
  i += 2
53
50
  when "--output-schema"
54
- args[:output_schema] = parse_json_arg(argv[i + 1], "--output-schema")
51
+ args[:output_schema] = Exa::CLI::Base.parse_json_or_file("--output-schema", argv[i + 1])
52
+ i += 2
53
+ when "--max-cost-dollars"
54
+ args[:max_cost_dollars] = parse_float("--max-cost-dollars", argv[i + 1])
55
+ i += 2
56
+ when "--max-duration-seconds"
57
+ args[:max_duration_seconds] = Exa::CLI::Base.parse_integer("--max-duration-seconds", argv[i + 1])
58
+ i += 2
59
+ when "--metadata"
60
+ metadata = Exa::CLI::Base.parse_json_or_file("--metadata", argv[i + 1])
61
+ unless metadata.is_a?(Hash)
62
+ $stderr.puts "Error: --metadata must be a JSON object"
63
+ exit 1
64
+ end
65
+ args[:metadata] = metadata
66
+ i += 2
67
+ when "--user-identifier"
68
+ args[:user_identifier] = argv[i + 1]
55
69
  i += 2
56
70
  when "--output-format"
57
71
  args[:output_format] = argv[i + 1]
@@ -73,9 +87,9 @@ def parse_args(argv)
73
87
  Options:
74
88
  --query TEXT Query for the agent run (required)
75
89
  --system-prompt TEXT System prompt to guide the agent
76
- --effort LEVEL Effort level: minimal, low, medium, high, xhigh, auto (default: auto)
77
- --data-sources LIST Comma-separated partner slugs to attach (see
78
- "Data sources" below), e.g. fiber_ai,similarweb
90
+ --effort LEVEL Effort level: minimal, low, medium, high, xhigh, ultra, auto (default: auto)
91
+ --data-sources LIST Comma-separated partner slugs to attach, up to 5
92
+ (see "Data sources" below), e.g. fiber,similarweb
79
93
  --input-data JSON JSON array of objects for the agent to process,
80
94
  or @file.json to read from a file. Each element
81
95
  is a record the agent enriches or acts on.
@@ -87,6 +101,18 @@ def parse_args(argv)
87
101
  to read it from a file. Recommended alongside
88
102
  --data-sources so the agent knows which fields
89
103
  each partner should fill.
104
+ --max-cost-dollars N Cost cap in dollars ($1 to $100). For auto and
105
+ ultra it caps the total run cost (default caps
106
+ $5 and $20). For fixed efforts it caps
107
+ contact-enrichment calls.
108
+ --max-duration-seconds N
109
+ Soft time limit in seconds (300 to 10800, which
110
+ is 5 minutes to 3 hours). Applies only to ultra.
111
+ --metadata JSON JSON object of string values stored with the
112
+ run, or @file.json to read it from a file
113
+ --user-identifier ID Opaque ID for the end user this run is for
114
+ (1 to 64 letters, digits, _ or -). Do not put
115
+ personal information here.
90
116
  --wait Stream the run and wait for it to complete
91
117
  --api-key KEY Exa API key (or set EXA_API_KEY env var)
92
118
  --output-format FMT Output format: json, pretty, or text (default: json)
@@ -96,7 +122,7 @@ def parse_args(argv)
96
122
  Each attached partner is billed per call on top of normal agent costs.
97
123
  The agent picks the right source per step and cites everything.
98
124
 
99
- fiber_ai GTM & recruiting. 40M+ companies, 850M+ people,
125
+ fiber GTM & recruiting. 40M+ companies, 850M+ people,
100
126
  work/personal emails and phones. Use for B2B
101
127
  prospecting, CRM enrichment, finding contacts.
102
128
  similarweb Web analytics. Traffic estimates, global rankings,
@@ -105,10 +131,15 @@ def parse_args(argv)
105
131
  baselayer Compliance & KYB. Verify US businesses: officers,
106
132
  state registrations, risk scores. Use for KYB and
107
133
  vendor/customer screening.
134
+ polymarket Prediction markets. Market odds, price history,
135
+ and trader positions from Polymarket.
136
+ macrobond Macroeconomic data. Global economic and financial
137
+ time series, entity metadata, and release
138
+ calendars.
108
139
  affiliate Commerce. Product catalog with live pricing,
109
140
  brands, and merchant links. Use for price
110
141
  comparison and shopping assistants.
111
- particle_news Media intelligence. Podcast transcripts with
142
+ particle Media intelligence. Podcast transcripts with
112
143
  speaker attribution and timestamps. Use to find
113
144
  who said what on podcasts.
114
145
  financial_datasets Finance. Ticker-based news for US public
@@ -130,7 +161,7 @@ def parse_args(argv)
130
161
  # Company profile blending two partners + web, as structured JSON:
131
162
  exa-ai agent-run-create --wait \\
132
163
  --query "Profile Anthropic: total funding and monthly web traffic" \\
133
- --data-sources fiber_ai,similarweb \\
164
+ --data-sources fiber,similarweb \\
134
165
  --output-schema '{"type":"object","properties":{"name":{"type":"string"},"totalFunding":{"type":"string"},"monthlyVisits":{"type":"number"}}}'
135
166
 
136
167
  # KYB check with a larger schema read from a file:
@@ -179,6 +210,10 @@ begin
179
210
  end
180
211
  run_params[:previous_run_id] = args[:previous_run_id] if args[:previous_run_id]
181
212
  run_params[:output_schema] = args[:output_schema] if args[:output_schema]
213
+ budget = { max_cost_dollars: args[:max_cost_dollars], max_duration_seconds: args[:max_duration_seconds] }.compact
214
+ run_params[:budget] = budget unless budget.empty?
215
+ run_params[:metadata] = args[:metadata] if args[:metadata]
216
+ run_params[:user_identifier] = args[:user_identifier] if args[:user_identifier]
182
217
 
183
218
  if args[:wait]
184
219
  # Stream the run and watch it to completion. The SSE stream creates the run
@@ -225,12 +260,12 @@ begin
225
260
  if final.nil? && run_id
226
261
  $stderr.print "\r(stream interrupted; polling #{run_id}) "
227
262
  begin
228
- final = Exa::CLI::Polling.poll(max_duration: 300, initial_delay: 2, max_delay: 10) do
263
+ final = Exa::CLI::Polling.poll(max_duration: 10_800, initial_delay: 2, max_delay: 10) do
229
264
  current = client.agent_run_get(run_id)
230
265
  { done: current.finished?, result: current, status: current.status }
231
266
  end
232
267
  rescue Exa::CLI::Polling::TimeoutError
233
- $stderr.puts "\nError: run did not complete within 5 minutes"
268
+ $stderr.puts "\nError: run did not complete within 3 hours"
234
269
  $stderr.puts "Run ID: #{run_id} — check later with: exa-ai agent-run-get #{run_id}"
235
270
  exit 1
236
271
  end
@@ -65,14 +65,7 @@ begin
65
65
  result = client.agent_run_delete(run_id)
66
66
 
67
67
  # Format output
68
- if result.respond_to?(:to_h)
69
- formatted = Exa::CLI::Formatters::AgentRunFormatter.format_run(result, output_format)
70
- puts formatted
71
- else
72
- puts({ deleted: true, id: run_id }.to_json) if output_format == "json"
73
- puts "Deleted agent run: #{run_id}" if output_format == "pretty"
74
- puts run_id if output_format == "text"
75
- end
68
+ puts Exa::CLI::Formatters::AgentRunFormatter.format_deletion(result, output_format)
76
69
 
77
70
  rescue Exa::NotFound => e
78
71
  warn "Agent run not found: #{e.message}"
@@ -3,10 +3,19 @@
3
3
 
4
4
  require "exa-ai"
5
5
 
6
+ # The line that tells the user how to get the next page, or nil when there
7
+ # are no more events.
8
+ def next_page_hint(events)
9
+ return nil unless events.has_more && events.next_cursor
10
+
11
+ "More events available. Use --cursor #{events.next_cursor} for the next page."
12
+ end
13
+
6
14
  # Parse command-line arguments
7
15
  api_key = nil
8
16
  run_id = nil
9
17
  output_format = "json"
18
+ list_params = {}
10
19
 
11
20
  args = ARGV.dup
12
21
  while args.any?
@@ -16,6 +25,10 @@ while args.any?
16
25
  api_key = args.shift
17
26
  when "--output-format"
18
27
  output_format = args.shift
28
+ when "--limit"
29
+ list_params[:limit] = Exa::CLI::Base.parse_integer("--limit", args.shift)
30
+ when "--cursor"
31
+ list_params[:cursor] = args.shift
19
32
  when "--help", "-h"
20
33
  puts <<~HELP
21
34
  Usage: exa-ai agent-run-events <run_id> [options]
@@ -27,12 +40,15 @@ while args.any?
27
40
 
28
41
  Options:
29
42
  --api-key KEY Exa API key (or use EXA_API_KEY env var)
43
+ --limit N Maximum number of events to return
44
+ --cursor CURSOR Cursor from a previous page, to get the next page
30
45
  --output-format FORMAT Output format: json, pretty, or text (default: json)
31
46
  --help, -h Show this help message
32
47
 
33
48
  Examples:
34
49
  exa-ai agent-run-events run_123
35
50
  exa-ai agent-run-events run_123 --output-format pretty
51
+ exa-ai agent-run-events run_123 --limit 50 --cursor CURSOR
36
52
  HELP
37
53
  exit 0
38
54
  else
@@ -62,7 +78,7 @@ begin
62
78
  client = Exa::CLI::Base.build_client(api_key)
63
79
 
64
80
  # Call API
65
- events = client.agent_run_events(run_id)
81
+ events = client.agent_run_events(run_id, **list_params)
66
82
 
67
83
  # Format output
68
84
  items = events.respond_to?(:data) ? events.data : events
@@ -75,10 +91,14 @@ begin
75
91
  items.each_with_index do |event, i|
76
92
  puts "#{i + 1}. #{event.respond_to?(:to_h) ? event.to_h.inspect : event}"
77
93
  end
94
+ hint = next_page_hint(events)
95
+ puts "", hint if hint
78
96
  when "text"
79
97
  items.each do |event|
80
98
  puts event.respond_to?(:to_h) ? event.to_h.inspect : event.to_s
81
99
  end
100
+ hint = next_page_hint(events)
101
+ puts hint if hint
82
102
  else
83
103
  puts JSON.pretty_generate(events.respond_to?(:to_h) ? events.to_h : events)
84
104
  end
@@ -18,7 +18,7 @@ while args.any?
18
18
  when "--cursor"
19
19
  cursor = args.shift
20
20
  when "--limit"
21
- limit = args.shift.to_i
21
+ limit = Exa::CLI::Base.parse_integer("--limit", args.shift)
22
22
  when "--output-format"
23
23
  output_format = args.shift
24
24
  when "--help", "-h"
@@ -5,8 +5,7 @@ require "exa-ai"
5
5
 
6
6
  # Parse command-line arguments
7
7
  api_key = nil
8
- cursor = nil
9
- limit = 10
8
+ run_id = nil
10
9
  output_format = "json"
11
10
 
12
11
  args = ARGV.dup
@@ -15,38 +14,49 @@ while args.any?
15
14
  case arg
16
15
  when "--api-key"
17
16
  api_key = args.shift
18
- when "--cursor"
19
- cursor = args.shift
20
- when "--limit"
21
- limit = args.shift.to_i
22
17
  when "--output-format"
23
18
  output_format = args.shift
24
19
  when "--help", "-h"
25
20
  puts <<~HELP
26
- Usage: exa-ai research-list [options]
21
+ Usage: exa-ai agent-run-stop <run_id> [options]
27
22
 
28
- List research tasks with cursor-based pagination.
23
+ Stop an in-progress agent run early. The run completes with stop
24
+ reason "stopped" and keeps the results gathered so far. Supported only
25
+ for runs with effort high, xhigh or ultra. To end a run at once with no
26
+ results, use agent-run-cancel.
27
+
28
+ Arguments:
29
+ run_id ID of the agent run to stop
29
30
 
30
31
  Options:
31
32
  --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
33
  --output-format FORMAT Output format: json, pretty, or text (default: json)
35
34
  --help, -h Show this help message
36
35
 
37
36
  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
37
+ exa-ai agent-run-stop run_123
38
+ exa-ai agent-run-stop run_123 --output-format pretty
42
39
  HELP
43
40
  exit 0
44
41
  else
45
- warn "Unknown option: #{arg}"
46
- exit 1
42
+ # First positional argument is the run_id
43
+ if run_id.nil?
44
+ run_id = arg
45
+ else
46
+ warn "Unknown option: #{arg}"
47
+ exit 1
48
+ end
47
49
  end
48
50
  end
49
51
 
52
+ # Validate required arguments
53
+ if run_id.nil?
54
+ warn "Error: Run ID argument required"
55
+ warn "Usage: exa-ai agent-run-stop <run_id> [options]"
56
+ warn "Try 'exa-ai agent-run-stop --help' for more information"
57
+ exit 1
58
+ end
59
+
50
60
  begin
51
61
  # Resolve API key
52
62
  api_key = Exa::CLI::Base.resolve_api_key(api_key)
@@ -54,27 +64,16 @@ begin
54
64
  # Build client
55
65
  client = Exa::CLI::Base.build_client(api_key)
56
66
 
57
- # Build parameters
58
- params = {limit: limit}
59
- params[:cursor] = cursor if cursor
60
-
61
67
  # Call API
62
- result = client.research_list(**params)
68
+ result = client.agent_run_stop(run_id)
63
69
 
64
70
  # Format output
65
- formatted = Exa::CLI::Formatters::ResearchFormatter.format_list(result, output_format)
71
+ formatted = Exa::CLI::Formatters::AgentRunFormatter.format_run(result, output_format)
66
72
  puts formatted
67
73
 
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
-
74
+ rescue Exa::NotFound => e
75
+ warn "Agent run not found: #{e.message}"
76
+ exit 1
78
77
  rescue Exa::Unauthorized => e
79
78
  warn "Authentication failed: #{e.message}"
80
79
  warn "Please provide a valid API key via --api-key or EXA_API_KEY environment variable"
data/exe/exa-ai-answer CHANGED
@@ -2,6 +2,9 @@
2
2
  # frozen_string_literal: true
3
3
 
4
4
  require "exa-ai"
5
+ require_relative "../lib/exa/cli/search_parser"
6
+
7
+ VALID_ANSWER_MODELS = %w[exa exa-pro exa-research exa-fast].freeze
5
8
 
6
9
  # Parse command-line arguments
7
10
  def parse_args(argv)
@@ -34,6 +37,15 @@ def parse_args(argv)
34
37
  when "--system-prompt"
35
38
  args[:system_prompt] = argv[i + 1]
36
39
  i += 2
40
+ when "--model"
41
+ args[:model] = argv[i + 1]
42
+ i += 2
43
+ when "--user-location"
44
+ args[:user_location] = argv[i + 1]
45
+ i += 2
46
+ when "--user-identifier"
47
+ args[:user_identifier] = argv[i + 1]
48
+ i += 2
37
49
  when "--api-key"
38
50
  args[:api_key] = argv[i + 1]
39
51
  i += 2
@@ -56,6 +68,10 @@ def parse_args(argv)
56
68
  --no-citations Alias for --skip-citations
57
69
  --output-schema JSON JSON schema for structured output
58
70
  --system-prompt TEXT System prompt to guide answer generation
71
+ --model MODEL Model: exa, exa-pro, exa-research, or exa-fast (default: exa)
72
+ --user-location LOC User location: ISO country code (US), or a JSON object
73
+ with country, latitude, longitude (@file syntax)
74
+ --user-identifier ID Your identifier for the end user
59
75
  --api-key KEY Exa API key (or set EXA_API_KEY env var)
60
76
  --output-format FMT Output format: json, pretty, or text (default: json)
61
77
  --help, -h Show this help message
@@ -90,6 +106,11 @@ begin
90
106
  exit 1
91
107
  end
92
108
 
109
+ if args[:model] && !VALID_ANSWER_MODELS.include?(args[:model])
110
+ $stderr.puts "Error: --model must be one of: #{VALID_ANSWER_MODELS.join(', ')}"
111
+ exit 1
112
+ end
113
+
93
114
  # Resolve API key
94
115
  api_key = Exa::CLI::Base.resolve_api_key(args[:api_key])
95
116
 
@@ -103,6 +124,10 @@ begin
103
124
  answer_params = {}
104
125
  answer_params[:text] = args[:text] if args[:text]
105
126
  answer_params[:system_prompt] = args[:system_prompt] if args[:system_prompt]
127
+ answer_params[:model] = args[:model] if args[:model]
128
+ answer_params[:user_identifier] = args[:user_identifier] if args[:user_identifier]
129
+
130
+ answer_params[:user_location] = Exa::CLI::SearchParser.parse_user_location(args[:user_location]) if args[:user_location]
106
131
 
107
132
  # Parse output_schema as JSON if provided
108
133
  if args[:output_schema]
data/exe/exa-ai-context CHANGED
@@ -20,9 +20,9 @@ def parse_args(args)
20
20
  api_key = args[i]
21
21
  when "--tokens-num"
22
22
  i += 1
23
- tokens_num = args[i]
23
+ tokens_num = Exa::CLI::Base.option_value("--tokens-num", args[i])
24
24
  # Convert to integer if it's not "dynamic"
25
- tokens_num = tokens_num.to_i unless tokens_num.downcase == "dynamic"
25
+ tokens_num = Exa::CLI::Base.parse_integer("--tokens-num", tokens_num) unless tokens_num.downcase == "dynamic"
26
26
  when "--output-format"
27
27
  i += 1
28
28
  output_format = args[i]
@@ -45,6 +45,10 @@ def print_help
45
45
  puts ""
46
46
  puts "Usage: exa-ai context <query> [options]"
47
47
  puts ""
48
+ puts "Deprecated: the Exa API spec no longer lists the /context endpoint."
49
+ puts "It still works, but no replacement is named. For code lookup, use"
50
+ puts "exa-ai search with a query that describes the code."
51
+ puts ""
48
52
  puts "Arguments:"
49
53
  puts " query Search query for code context (required)"
50
54
  puts ""
@@ -3,6 +3,7 @@
3
3
 
4
4
  require "exa-ai"
5
5
  require_relative "../lib/exa/cli/search_parser"
6
+ require_relative "../lib/exa/cli/contents_flags"
6
7
 
7
8
  # Parse command-line arguments
8
9
  def parse_args(argv)
@@ -16,9 +17,15 @@ def parse_args(argv)
16
17
  i = 0
17
18
  while i < argv.length
18
19
  arg = argv[i]
20
+ next_index = Exa::CLI::ContentsFlags.parse(argv, i, args)
21
+ if next_index
22
+ i = next_index
23
+ next
24
+ end
25
+
19
26
  case arg
20
27
  when "--num-results"
21
- args[:num_results] = argv[i + 1].to_i
28
+ args[:num_results] = Exa::CLI::Base.parse_integer("--num-results", argv[i + 1])
22
29
  i += 2
23
30
  when "--exclude-source-domain"
24
31
  args[:exclude_source_domain] = true
@@ -33,10 +40,10 @@ def parse_args(argv)
33
40
  args[:category] = category
34
41
  i += 2
35
42
  when "--include-domains"
36
- args[:include_domains] = argv[i + 1].split(",").map(&:strip)
43
+ args[:include_domains] = Exa::CLI::Base.option_value("--include-domains", argv[i + 1]).split(",").map(&:strip)
37
44
  i += 2
38
45
  when "--exclude-domains"
39
- args[:exclude_domains] = argv[i + 1].split(",").map(&:strip)
46
+ args[:exclude_domains] = Exa::CLI::Base.option_value("--exclude-domains", argv[i + 1]).split(",").map(&:strip)
40
47
  i += 2
41
48
  when "--start-published-date"
42
49
  args[:start_published_date] = argv[i + 1]
@@ -58,29 +65,6 @@ def parse_args(argv)
58
65
  args[:exclude_text] ||= []
59
66
  args[:exclude_text] << argv[i + 1]
60
67
  i += 2
61
- when "--text"
62
- args[:text] = true
63
- i += 1
64
- when "--text-max-characters"
65
- args[:text_max_characters] = argv[i + 1].to_i
66
- i += 2
67
- when "--include-html-tags"
68
- args[:include_html_tags] = true
69
- i += 1
70
- when "--summary"
71
- args[:summary] = true
72
- i += 1
73
- when "--summary-query"
74
- args[:summary_query] = argv[i + 1]
75
- i += 2
76
- when "--summary-schema"
77
- schema_arg = argv[i + 1]
78
- args[:summary_schema] = if schema_arg.start_with?("@")
79
- JSON.parse(File.read(schema_arg[1..]))
80
- else
81
- JSON.parse(schema_arg)
82
- end
83
- i += 2
84
68
  when "--api-key"
85
69
  args[:api_key] = argv[i + 1]
86
70
  i += 2
@@ -93,6 +77,9 @@ def parse_args(argv)
93
77
 
94
78
  Find content similar to a given URL
95
79
 
80
+ Deprecated: the API marks /findSimilar as deprecated. Use exa-ai search
81
+ with a query that describes the source page instead.
82
+
96
83
  Arguments:
97
84
  URL URL to find similar content for (required)
98
85
 
@@ -100,24 +87,21 @@ def parse_args(argv)
100
87
  --num-results N Number of results to return (default: 10)
101
88
  --exclude-source-domain Exclude results from the source URL's domain
102
89
  --category CAT Focus on specific data category
103
- Options: "company", "publication", "news", "github",
90
+ Options: "company", "publication", "news",
104
91
  "personal site", "people", "financial report"
105
92
  --include-domains D Comma-separated list of domains to include
106
93
  --exclude-domains D Comma-separated list of domains to exclude
107
94
  --start-published-date DATE Filter by published date (ISO 8601 format)
108
95
  --end-published-date DATE Filter by published date (ISO 8601 format)
109
- --start-crawl-date DATE Filter by crawl date (ISO 8601 format)
110
- --end-crawl-date DATE Filter by crawl date (ISO 8601 format)
111
- --include-text PHRASE Include results with exact phrase (repeatable)
112
- --exclude-text PHRASE Exclude results with exact phrase (repeatable)
96
+ --start-crawl-date DATE Deprecated: the API ignores it
97
+ --end-crawl-date DATE Deprecated: the API ignores it
98
+ --include-text PHRASE Deprecated: include results that contain the phrase
99
+ (approximate match, repeatable)
100
+ --exclude-text PHRASE Deprecated: exclude results that contain the phrase
101
+ (approximate match, repeatable)
113
102
 
114
103
  Content Extraction:
115
- --text Include full webpage text
116
- --text-max-characters N Max characters for webpage text
117
- --include-html-tags Include HTML tags in text extraction
118
- --summary Include AI-generated summary
119
- --summary-query PROMPT Custom prompt for summary generation
120
- --summary-schema FILE JSON schema for summary structure (@file syntax)
104
+ #{Exa::CLI::ContentsFlags::HELP}
121
105
 
122
106
  General Options:
123
107
  --api-key KEY Exa API key (or set EXA_API_KEY env var)
@@ -133,6 +117,8 @@ def parse_args(argv)
133
117
  HELP
134
118
  exit 0
135
119
  else
120
+ Exa::CLI::Base.reject_unknown_option(arg) if arg.start_with?("--")
121
+
136
122
  unless url_found
137
123
  args[:url] = arg
138
124
  url_found = true
@@ -144,35 +130,6 @@ def parse_args(argv)
144
130
  args
145
131
  end
146
132
 
147
- # Build contents parameter from extracted flags
148
- def build_contents(args)
149
- contents = {}
150
-
151
- # Text options
152
- if args[:text]
153
- if args[:text_max_characters] || args[:include_html_tags]
154
- contents[:text] = {}
155
- contents[:text][:max_characters] = args[:text_max_characters] if args[:text_max_characters]
156
- contents[:text][:include_html_tags] = args[:include_html_tags] if args[:include_html_tags]
157
- else
158
- contents[:text] = true
159
- end
160
- end
161
-
162
- # Summary options
163
- if args[:summary]
164
- if args[:summary_query] || args[:summary_schema]
165
- contents[:summary] = {}
166
- contents[:summary][:query] = args[:summary_query] if args[:summary_query]
167
- contents[:summary][:schema] = args[:summary_schema] if args[:summary_schema]
168
- else
169
- contents[:summary] = true
170
- end
171
- end
172
-
173
- contents.empty? ? nil : contents
174
- end
175
-
176
133
  # Main execution
177
134
  begin
178
135
  args = parse_args(ARGV)
@@ -206,8 +163,9 @@ begin
206
163
  params[:end_crawl_date] = args[:end_crawl_date] if args[:end_crawl_date]
207
164
  params[:include_text] = args[:include_text] if args[:include_text]
208
165
  params[:exclude_text] = args[:exclude_text] if args[:exclude_text]
209
- contents = build_contents(args)
210
- params.merge!(contents) if contents
166
+ params[:snapshot_as_of] = args[:snapshot_as_of] if args[:snapshot_as_of]
167
+ contents = Exa::CLI::ContentsFlags.build(args)
168
+ params[:contents] = contents if contents
211
169
 
212
170
  # Execute find_similar
213
171
  result = client.find_similar(args[:url], **params)