exa-ai 0.13.0 → 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 (151) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +119 -73
  3. data/exe/exa-ai +41 -136
  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-agent-run-stop +93 -0
  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 +186 -310
  30. data/lib/exa/resources/agent_run.rb +5 -3
  31. data/lib/exa/resources/agent_run_deletion.rb +17 -0
  32. data/lib/exa/resources/answer.rb +3 -3
  33. data/lib/exa/resources/contents_result.rb +5 -1
  34. data/lib/exa/resources/find_similar_result.rb +5 -1
  35. data/lib/exa/resources/search_monitor.rb +42 -0
  36. data/lib/exa/resources/search_monitor_batch_result.rb +11 -0
  37. data/lib/exa/resources/search_monitor_list.rb +19 -0
  38. data/lib/exa/resources/search_monitor_run.rb +46 -0
  39. data/lib/exa/resources/search_monitor_trigger_result.rb +11 -0
  40. data/lib/exa/resources/search_result.rb +11 -1
  41. data/lib/exa/services/agent_run_cancel.rb +1 -12
  42. data/lib/exa/services/agent_run_create.rb +1 -12
  43. data/lib/exa/services/agent_run_delete.rb +6 -14
  44. data/lib/exa/services/agent_run_events.rb +33 -4
  45. data/lib/exa/services/agent_run_get.rb +1 -12
  46. data/lib/exa/services/agent_run_list.rb +1 -12
  47. data/lib/exa/services/agent_run_stop.rb +21 -0
  48. data/lib/exa/services/agent_run_stream.rb +53 -51
  49. data/lib/exa/services/answer.rb +5 -2
  50. data/lib/exa/services/answer_stream.rb +54 -45
  51. data/lib/exa/services/context.rb +3 -1
  52. data/lib/exa/services/find_similar.rb +9 -2
  53. data/lib/exa/services/get_contents.rb +14 -15
  54. data/lib/exa/services/parameter_converter.rb +128 -111
  55. data/lib/exa/services/search.rb +58 -19
  56. data/lib/exa/services/search_monitors/batch.rb +36 -0
  57. data/lib/exa/services/search_monitors/create.rb +37 -0
  58. data/lib/exa/services/search_monitors/delete.rb +22 -0
  59. data/lib/exa/services/search_monitors/get.rb +22 -0
  60. data/lib/exa/services/search_monitors/list.rb +29 -0
  61. data/lib/exa/services/search_monitors/runs_get.rb +23 -0
  62. data/lib/exa/services/search_monitors/runs_list.rb +29 -0
  63. data/lib/exa/services/search_monitors/trigger.rb +22 -0
  64. data/lib/exa/services/search_monitors/update.rb +42 -0
  65. data/lib/exa/services/search_stream.rb +38 -0
  66. data/lib/exa/version.rb +1 -1
  67. data/lib/exa.rb +18 -50
  68. metadata +30 -84
  69. data/exe/exa-ai-enrichment-cancel +0 -108
  70. data/exe/exa-ai-enrichment-create +0 -226
  71. data/exe/exa-ai-enrichment-delete +0 -122
  72. data/exe/exa-ai-enrichment-get +0 -104
  73. data/exe/exa-ai-enrichment-list +0 -99
  74. data/exe/exa-ai-enrichment-update +0 -171
  75. data/exe/exa-ai-import-create +0 -253
  76. data/exe/exa-ai-import-delete +0 -92
  77. data/exe/exa-ai-import-get +0 -92
  78. data/exe/exa-ai-import-list +0 -72
  79. data/exe/exa-ai-import-update +0 -164
  80. data/exe/exa-ai-monitor-create +0 -223
  81. data/exe/exa-ai-monitor-delete +0 -101
  82. data/exe/exa-ai-monitor-get +0 -92
  83. data/exe/exa-ai-monitor-list +0 -90
  84. data/exe/exa-ai-monitor-runs-get +0 -103
  85. data/exe/exa-ai-monitor-runs-list +0 -110
  86. data/exe/exa-ai-monitor-update +0 -207
  87. data/exe/exa-ai-webset-cancel +0 -97
  88. data/exe/exa-ai-webset-create +0 -254
  89. data/exe/exa-ai-webset-delete +0 -111
  90. data/exe/exa-ai-webset-get +0 -93
  91. data/exe/exa-ai-webset-item-delete +0 -111
  92. data/exe/exa-ai-webset-item-get +0 -105
  93. data/exe/exa-ai-webset-item-list +0 -108
  94. data/exe/exa-ai-webset-list +0 -91
  95. data/exe/exa-ai-webset-search-cancel +0 -104
  96. data/exe/exa-ai-webset-search-create +0 -247
  97. data/exe/exa-ai-webset-search-get +0 -105
  98. data/exe/exa-ai-webset-update +0 -143
  99. data/lib/exa/cli/formatters/enrichment_formatter.rb +0 -125
  100. data/lib/exa/cli/formatters/import_formatter.rb +0 -153
  101. data/lib/exa/cli/formatters/monitor_formatter.rb +0 -144
  102. data/lib/exa/cli/formatters/monitor_run_formatter.rb +0 -126
  103. data/lib/exa/cli/formatters/webset_formatter.rb +0 -134
  104. data/lib/exa/cli/formatters/webset_item_formatter.rb +0 -131
  105. data/lib/exa/cli/formatters/webset_search_formatter.rb +0 -57
  106. data/lib/exa/constants/websets.rb +0 -19
  107. data/lib/exa/resources/import.rb +0 -86
  108. data/lib/exa/resources/import_collection.rb +0 -33
  109. data/lib/exa/resources/monitor.rb +0 -48
  110. data/lib/exa/resources/monitor_collection.rb +0 -30
  111. data/lib/exa/resources/monitor_run.rb +0 -52
  112. data/lib/exa/resources/monitor_run_collection.rb +0 -30
  113. data/lib/exa/resources/webset.rb +0 -74
  114. data/lib/exa/resources/webset_collection.rb +0 -33
  115. data/lib/exa/resources/webset_enrichment.rb +0 -71
  116. data/lib/exa/resources/webset_enrichment_collection.rb +0 -28
  117. data/lib/exa/resources/webset_item_collection.rb +0 -33
  118. data/lib/exa/resources/webset_search.rb +0 -112
  119. data/lib/exa/services/websets/cancel.rb +0 -36
  120. data/lib/exa/services/websets/cancel_enrichment.rb +0 -35
  121. data/lib/exa/services/websets/cancel_search.rb +0 -44
  122. data/lib/exa/services/websets/create.rb +0 -45
  123. data/lib/exa/services/websets/create_enrichment.rb +0 -35
  124. data/lib/exa/services/websets/create_search.rb +0 -48
  125. data/lib/exa/services/websets/create_search_validator.rb +0 -128
  126. data/lib/exa/services/websets/create_validator.rb +0 -213
  127. data/lib/exa/services/websets/delete.rb +0 -36
  128. data/lib/exa/services/websets/delete_enrichment.rb +0 -35
  129. data/lib/exa/services/websets/delete_item.rb +0 -20
  130. data/lib/exa/services/websets/get_item.rb +0 -20
  131. data/lib/exa/services/websets/get_search.rb +0 -43
  132. data/lib/exa/services/websets/import_create.rb +0 -40
  133. data/lib/exa/services/websets/import_delete.rb +0 -37
  134. data/lib/exa/services/websets/import_get.rb +0 -37
  135. data/lib/exa/services/websets/import_list.rb +0 -25
  136. data/lib/exa/services/websets/import_update.rb +0 -38
  137. data/lib/exa/services/websets/import_upload.rb +0 -59
  138. data/lib/exa/services/websets/list.rb +0 -25
  139. data/lib/exa/services/websets/list_items.rb +0 -26
  140. data/lib/exa/services/websets/monitors/create.rb +0 -42
  141. data/lib/exa/services/websets/monitors/delete.rb +0 -32
  142. data/lib/exa/services/websets/monitors/get.rb +0 -33
  143. data/lib/exa/services/websets/monitors/list.rb +0 -27
  144. data/lib/exa/services/websets/monitors/runs/get.rb +0 -37
  145. data/lib/exa/services/websets/monitors/runs/list.rb +0 -30
  146. data/lib/exa/services/websets/monitors/update.rb +0 -33
  147. data/lib/exa/services/websets/retrieve.rb +0 -47
  148. data/lib/exa/services/websets/retrieve_enrichment.rb +0 -35
  149. data/lib/exa/services/websets/update.rb +0 -37
  150. data/lib/exa/services/websets/update_enrichment.rb +0 -36
  151. data/lib/exa/services/websets_parameter_converter.rb +0 -45
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c27b667bcdbd00173088ba535ad3ecc2ef249431703e7666739d0c74a59c3fc1
4
- data.tar.gz: 4067fe462f41c1be33acdb455a2b6ca0d1871fa362650a18293785b37f41df2f
3
+ metadata.gz: 4aa92257e4c27dbbd7cd5db638d95d40e76c8d75a92209069a769f1404ace64f
4
+ data.tar.gz: 33b82648f530fd688751fd2f48808b332efc420fcf4f7fd8360f9a2fca476da1
5
5
  SHA512:
6
- metadata.gz: a0d7722513aefbdc19e1f17fb9d66b72e79669fae2b56ab9116b94fbb5e865622f2d810cae560ec65d6163f692ad21b37e3efeba6929cc4f6d3b9d6b95992082
7
- data.tar.gz: a1f7611e929b6542036fcac93584cd1888a26f1f4e09fe3dbd1d942364efc32da607709cf9dc146e3d65259abdcd6099660abdad9c360296e9c4556daff4c67f
6
+ metadata.gz: 4127f458266b07c9f6989eca0a5b8333d98775fa488692af84488ebacfb3104dd23b5eaa5f72f3ab9d606d7ea76746bcb15598d213dc8b7e2154ff6a74f288e7
7
+ data.tar.gz: e8ada14ef4109d77e7c2bbb7647520b441005e68fb4a16c491464877d13d6a80d904b318a6ed8cbe4563de3bfcefd3f26c0c2e85a5f20b6a6eb34bdea18a453b
data/README.md CHANGED
@@ -10,6 +10,7 @@ Ruby client for the Exa.ai API. Search and analyze web content using neural sear
10
10
  - [Quick Start](#quick-start)
11
11
  - [Features](#features)
12
12
  - [Agent](#agent)
13
+ - [Search Monitors](#search-monitors)
13
14
  - [Error Handling](#error-handling)
14
15
  - [Documentation](#documentation)
15
16
  - [Development](#development)
@@ -134,7 +135,7 @@ client = Exa::Client.new
134
135
  results = client.search("Ruby programming language")
135
136
  results.results.each { |item| puts "#{item['title']}: #{item['url']}" }
136
137
 
137
- # Find similar content
138
+ # Find similar content (deprecated: prefer search with a query that describes the page)
138
139
  similar = client.find_similar("https://arxiv.org/abs/2307.06435")
139
140
  similar.results.each { |item| puts item['url'] }
140
141
 
@@ -142,13 +143,19 @@ similar.results.each { |item| puts item['url'] }
142
143
  answer = client.answer("What is machine learning?")
143
144
  puts answer.answer
144
145
 
145
- # Find code examples
146
+ # Find code examples (deprecated: /context is not in the API spec)
146
147
  code = client.context("React hooks")
147
148
  puts code.response
148
149
 
149
150
  # Get page contents
150
151
  contents = client.get_contents(["https://ruby-lang.org"])
151
152
  puts contents.results.first["text"]
153
+
154
+ # Stream a search with a synthesized answer (requires output_schema)
155
+ schema = { type: "object", properties: { summary: { type: "string" } } }
156
+ client.search_stream("Ruby 3.4 release highlights", output_schema: schema) do |chunk|
157
+ print chunk["delta"] if chunk["type"] == "text-delta"
158
+ end
152
159
  ```
153
160
 
154
161
  ### Command Line
@@ -156,48 +163,13 @@ puts contents.results.first["text"]
156
163
  ```bash
157
164
  # Core Search Commands
158
165
  exa-ai search "Ruby programming language"
159
- exa-ai find-similar "https://arxiv.org/abs/2307.06435"
166
+ exa-ai find-similar "https://arxiv.org/abs/2307.06435" # deprecated
160
167
  exa-ai answer "What is machine learning?"
161
- exa-ai context "React hooks" --tokens-num 5000
168
+ exa-ai context "React hooks" --tokens-num 5000 # deprecated
162
169
  exa-ai get-contents "https://ruby-lang.org"
163
-
164
- # Webset Management
165
- exa-ai webset-create --search '{"query":"technology companies","count":1}'
166
- exa-ai webset-list --limit 5
167
- exa-ai webset-get WEBSET_ID
168
- exa-ai webset-update WEBSET_ID --metadata '{"updated":"true","version":"2"}'
169
- exa-ai webset-delete WEBSET_ID --force
170
- exa-ai webset-cancel WEBSET_ID
171
-
172
- # Webset Searches
173
- exa-ai webset-search-create WEBSET_ID --query "Ford Mustang" --entity custom --entity-description "vintage cars"
174
- exa-ai webset-search-create WEBSET_ID --query "tech CEOs" --entity person --count 20
175
- exa-ai webset-search-create WEBSET_ID --query "Y Combinator startups" --entity company
176
- exa-ai webset-search-get WEBSET_ID SEARCH_ID
177
- exa-ai webset-search-cancel WEBSET_ID SEARCH_ID
178
-
179
- # Webset Items
180
- exa-ai webset-item-list WEBSET_ID
181
- exa-ai webset-item-get WEBSET_ID ITEM_ID
182
- exa-ai webset-item-delete WEBSET_ID ITEM_ID --force
183
-
184
- # Enrichments
185
- exa-ai enrichment-create WEBSET_ID --description "Find company email" --format text
186
- exa-ai enrichment-create WEBSET_ID --description "Company size category" --format options --options '[{"label":"Small (1-10)"},{"label":"Medium (11-50)"},{"label":"Large (51+)"}]'
187
- exa-ai enrichment-list WEBSET_ID
188
- exa-ai enrichment-get WEBSET_ID ENRICHMENT_ID
189
- exa-ai enrichment-update WEBSET_ID ENRICHMENT_ID --description "Updated description"
190
- exa-ai enrichment-delete WEBSET_ID ENRICHMENT_ID --force
191
- exa-ai enrichment-cancel WEBSET_ID ENRICHMENT_ID
192
-
193
- # Webset Imports
194
- exa-ai webset-import-create companies.csv --count 100 --title "My Companies" --format csv --entity-type company
195
- exa-ai webset-import-create data.csv --count 50 --title "Tech Startups" --format csv --entity-type company --csv-identifier 0
196
- exa-ai webset-import-create import.csv --count 100 --title "Import" --format csv --entity-type company --metadata '{"source":"crm"}' --quiet
197
- exa-ai webset-import-list
198
- exa-ai webset-import-get IMPORT_ID
199
- exa-ai webset-import-update IMPORT_ID --title "Updated Title"
200
- exa-ai webset-import-delete IMPORT_ID
170
+ exa-ai search "climate tech seed rounds" --type lite --objective "Find primary sources"
171
+ exa-ai get-contents --ids DOC_ID_1,DOC_ID_2 --highlights --highlights-verbosity low
172
+ exa-ai answer "What is machine learning?" --model exa-pro --user-location US
201
173
  ```
202
174
 
203
175
  ## Features
@@ -206,17 +178,27 @@ The gem provides complete access to Exa's API endpoints:
206
178
 
207
179
  ### Core Search
208
180
  - **Search** — Neural and keyword search across billions of web pages
209
- - **Find Similar** — Discover content similar to a given URL
181
+ - **Find Similar** (deprecated) — Discover content similar to a given URL
210
182
  - **Answer** — Generate comprehensive answers with source citations
211
- - **Context** — Find relevant code and documentation snippets
183
+ - **Context** (deprecated) — Find relevant code and documentation snippets
212
184
  - **Get Contents** — Extract full text content from web pages
213
185
 
214
- ### Websets
215
- - **Webset Management** — Create, update, delete, and list datasets of web pages
216
- - **Webset Searches** — Run searches within websets and manage search tasks
217
- - **Webset Items** — List, retrieve, and manage individual items in websets
218
- - **Enrichments** — Create and manage AI-powered data enrichment tasks on websets
219
- - **Imports** — Upload CSV files to import external data into websets
186
+ ### Deprecated and legacy options
187
+
188
+ These still work, so existing code keeps running. The search command prints the API's `warnings` to stderr when the API flags one of them. Use the replacement in new code.
189
+
190
+ - `find_similar` / `exa-ai find-similar`: deprecated by the API. Use `search` with a query that describes the source page.
191
+ - `context` / `exa-ai context`: `/context` is not in the API spec. No replacement is named; for code lookup, use `search`.
192
+ - Search types `fast` and `instant` are legacy; use `lite`. `deep-reasoning` is legacy; use `deep`.
193
+ - `start_crawl_date` and `end_crawl_date` are deprecated. The API ignores them.
194
+ - `include_text` and `exclude_text` are deprecated.
195
+ - The `context` contents option and the `context` response field are deprecated. Use `highlights` or `text`.
196
+ - `highlights` `num_sentences` and `highlights_per_url` are deprecated. Use `max_characters`.
197
+ - `subpages` and `subpage_target` are deprecated on `search` and `find_similar`. They stay valid on `get_contents`.
198
+ - The `resolved_search_type` response field is deprecated.
199
+ - The CLI no longer accepts `--category github`; it is not in the API's category list.
200
+
201
+ See [docs/API.md](docs/API.md) and [docs/CLI.md](docs/CLI.md) for details.
220
202
 
221
203
  ### Agent
222
204
  - **Agent API** — Asynchronous research agent with citations, streaming, and full run lifecycle
@@ -267,7 +249,7 @@ run = client.agent_run_create(
267
249
  # results into one grounded, structured answer.
268
250
  run = client.agent_run_create(
269
251
  query: "Profile Anthropic: total funding and estimated monthly web traffic",
270
- data_sources: [{ provider: "fiber_ai" }, { provider: "similarweb" }],
252
+ data_sources: [{ provider: "fiber" }, { provider: "similarweb" }],
271
253
  output_schema: {
272
254
  type: "object",
273
255
  properties: {
@@ -278,11 +260,19 @@ run = client.agent_run_create(
278
260
  }
279
261
  )
280
262
 
263
+ # Limit what a run may spend. max_cost_dollars accepts $1 to $100;
264
+ # max_duration_seconds (300 to 10800) applies only to effort "ultra".
265
+ run = client.agent_run_create(
266
+ query: "Every public company that announced a lithium recycling plant in 2025",
267
+ effort: "ultra",
268
+ budget: { max_cost_dollars: 20.0, max_duration_seconds: 3600 }
269
+ )
270
+
281
271
  # Stream events as they arrive
282
- client.agent_run_stream(query: "AI infrastructure startups that raised Series A in 2025") do |event, data|
283
- puts "#{event}: #{data.inspect}"
272
+ client.agent_run_stream(query: "AI infrastructure startups that raised Series A in 2025") do |event, data, event_id|
273
+ puts "#{event} (#{event_id}): #{data.inspect}"
284
274
  # event is the SSE event-type string, e.g. "agent_run.completed"
285
- # data is the parsed JSON hash
275
+ # data is the parsed JSON hash; event_id is the SSE id, or nil
286
276
  end
287
277
 
288
278
  # List recent runs
@@ -294,12 +284,21 @@ runs.data.each { |r| puts "#{r.id}: #{r.status}" }
294
284
  # Fetch a run's events
295
285
  events = client.agent_run_events(run.id)
296
286
 
297
- # Cancel or delete a run
287
+ # Replay the events after a known event id (server-sent events).
288
+ # This reads the whole response before it returns.
289
+ events = client.agent_run_events(run.id, last_event_id: "7")
290
+
291
+ # Stop a run early: it completes with stop_reason "stopped" and keeps the
292
+ # results gathered so far (effort high, xhigh or ultra only)
293
+ client.agent_run_stop(run.id)
294
+
295
+ # Cancel a run (it ends at once with no results), or delete it
298
296
  client.agent_run_cancel(run.id)
299
- client.agent_run_delete(run.id)
297
+ deletion = client.agent_run_delete(run.id) # => Exa::Resources::AgentRunDeletion
298
+ deletion.deleted? # => true
300
299
  ```
301
300
 
302
- > **Note:** Multi-word keys inside `input`, `data_sources` items, and `metadata` are passed through verbatim — supply them in the exact shape the API expects, the same contract as `output_schema`.
301
+ > **Note:** The gem converts snake_case keys to camelCase at every depth, including keys inside `input` and `data_sources` items. Keys under `output_schema`, `schema`, `metadata`, `data` and `exclusion` are your own data and are sent unchanged, so supply them in the exact shape the API expects.
303
302
 
304
303
  ### Command Line
305
304
 
@@ -309,24 +308,82 @@ exa-ai agent-run-create --query "AI infrastructure startups that raised Series A
309
308
 
310
309
  # Attach premium data partners (Exa Connect) with a structured schema.
311
310
  # Run `exa-ai agent-run-create --help` to see every provider and when to use it:
312
- # fiber_ai, similarweb, baselayer, affiliate, particle_news, financial_datasets, jinko
311
+ # fiber, similarweb, baselayer, polymarket, macrobond, affiliate, particle,
312
+ # financial_datasets, jinko (up to 5 per run)
313
313
  exa-ai agent-run-create --wait \
314
314
  --query "Profile Anthropic: total funding and monthly web traffic" \
315
- --data-sources fiber_ai,similarweb \
315
+ --data-sources fiber,similarweb \
316
316
  --output-schema '{"type":"object","properties":{"name":{"type":"string"},"totalFunding":{"type":"string"},"monthlyVisits":{"type":"number"}}}'
317
317
 
318
+ # Cap cost and time for an ultra run
319
+ exa-ai agent-run-create --effort ultra --max-cost-dollars 20 --max-duration-seconds 3600 \
320
+ --query "Every public company that announced a lithium recycling plant in 2025"
321
+
318
322
  # Fetch an existing run
319
323
  exa-ai agent-run-get <run_id>
320
324
 
321
325
  # List recent runs
322
326
  exa-ai agent-run-list --limit 5
323
327
 
324
- # Cancel or delete a run
328
+ # Stop a run early and keep its results, or cancel or delete it
329
+ exa-ai agent-run-stop <run_id>
325
330
  exa-ai agent-run-cancel <run_id>
326
331
  exa-ai agent-run-delete <run_id>
327
332
 
328
- # Fetch a run's events
329
- exa-ai agent-run-events <run_id>
333
+ # Fetch a run's events, one page at a time
334
+ exa-ai agent-run-events <run_id> --limit 50
335
+ exa-ai agent-run-events <run_id> --limit 50 --cursor <next_cursor>
336
+ ```
337
+
338
+ ## Search Monitors
339
+
340
+ A search monitor runs an Exa search on a schedule and posts new results to your webhook. This is the Monitors API (`/monitors`).
341
+
342
+ ### Ruby API
343
+
344
+ ```ruby
345
+ client = Exa::Client.new(api_key: "your-key")
346
+
347
+ # Create a monitor that runs once a day.
348
+ # Without trigger:, the monitor runs only when you call search_monitor_trigger.
349
+ monitor = client.search_monitor_create(
350
+ name: "AI funding news",
351
+ search: { query: "AI/ML infrastructure startups with Series A funding", num_results: 10 },
352
+ webhook: { url: "https://your-app.example/webhooks/exa" },
353
+ trigger: { type: "interval", period: "1d" }
354
+ )
355
+ monitor.webhook_secret # The API returns this only once. Store it now.
356
+
357
+ client.search_monitor_get(monitor.id)
358
+ client.search_monitor_list(status: "active", limit: 20)
359
+ client.search_monitor_update(monitor.id, status: "paused")
360
+ client.search_monitor_update(monitor.id, trigger: nil) # remove the schedule
361
+ client.search_monitor_trigger(monitor.id) # run now
362
+
363
+ runs = client.search_monitor_runs_list(monitor.id)
364
+ client.search_monitor_runs_get(monitor.id, runs.data.first.id)
365
+
366
+ # Pause, unpause or delete many monitors. This is a dry run unless you pass dry_run: false.
367
+ result = client.search_monitor_batch(action: "pause", filter: { name: "AI funding" })
368
+ result.ids # what would change
369
+
370
+ client.search_monitor_delete(monitor.id)
371
+ ```
372
+
373
+ ### Command Line
374
+
375
+ ```bash
376
+ exa-ai search-monitor-create --query "AI/ML infrastructure startups with Series A funding" \
377
+ --webhook-url https://your-app.example/webhooks/exa --period 1d --name "AI funding news"
378
+ exa-ai search-monitor-list --status active
379
+ exa-ai search-monitor-get <monitor_id>
380
+ exa-ai search-monitor-update <monitor_id> --status paused
381
+ exa-ai search-monitor-trigger <monitor_id>
382
+ exa-ai search-monitor-runs-list <monitor_id>
383
+ exa-ai search-monitor-runs-get <monitor_id> <run_id>
384
+ exa-ai search-monitor-batch --action pause --name "AI funding" # dry run
385
+ exa-ai search-monitor-batch --action pause --name "AI funding" --execute # apply
386
+ exa-ai search-monitor-delete <monitor_id>
330
387
  ```
331
388
 
332
389
  ## Error Handling
@@ -371,9 +428,6 @@ bundle exec rake test
371
428
 
372
429
  # Run integration tests (VCR-based, no real API calls)
373
430
  RUN_INTEGRATION_TESTS=true bundle exec rake test
374
-
375
- # Run CLI integration tests (real API calls, requires explicit opt-in)
376
- RUN_CLI_INTEGRATION_TESTS=true bundle exec rake test
377
431
  ```
378
432
 
379
433
  ### Integration Tests
@@ -386,20 +440,12 @@ RUN_CLI_INTEGRATION_TESTS=true bundle exec rake test
386
440
  - Set `RUN_INTEGRATION_TESTS=true` to run them
387
441
  - Safe to run during development
388
442
 
389
- **CLI integration tests (`RUN_CLI_INTEGRATION_TESTS`):**
390
- - Make real API calls through shell commands
391
- - Consume Exa's concurrent search quota
392
- - Set `RUN_CLI_INTEGRATION_TESTS=true` AND `EXA_API_KEY` to run them
393
- - **Warning:** Can exhaust API quota and trigger rate limits lasting 1-2 days
394
-
395
443
  **When to run integration tests:**
396
444
  - VCR tests: Anytime (safe, no real API calls)
397
- - CLI tests: Only before releases or when testing CLI-specific functionality
398
445
 
399
446
  **Test Coverage:**
400
447
  - **Unit tests** - Fast, no API calls, always run
401
448
  - **VCR integration tests** - Replay cassettes, skipped by default
402
- - **CLI integration tests** - Real API calls via shell, skipped by default
403
449
 
404
450
  ## Support
405
451
 
data/exe/exa-ai CHANGED
@@ -12,40 +12,20 @@ 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
- "webset-create" => "Create a new webset",
16
- "webset-get" => "Get webset details",
17
- "webset-list" => "List websets",
18
- "webset-update" => "Update a webset",
19
- "webset-delete" => "Delete a webset",
20
- "webset-cancel" => "Cancel a webset",
21
- "webset-search-create" => "Create a search in a webset",
22
- "webset-search-get" => "Get webset search details",
23
- "webset-search-cancel" => "Cancel a webset search",
24
- "webset-item-list" => "List items in a webset",
25
- "webset-item-get" => "Get webset item details",
26
- "webset-item-delete" => "Delete a webset item",
27
- "enrichment-create" => "Create an enrichment",
28
- "enrichment-get" => "Get enrichment details",
29
- "enrichment-list" => "List enrichments",
30
- "enrichment-update" => "Update an enrichment",
31
- "enrichment-delete" => "Delete an enrichment",
32
- "enrichment-cancel" => "Cancel an enrichment",
33
- "import-create" => "Create a new import",
34
- "import-list" => "List imports",
35
- "import-get" => "Get import details",
36
- "import-update" => "Update an import",
37
- "import-delete" => "Delete an import",
38
- "monitor-create" => "Create a webset monitor",
39
- "monitor-get" => "Get monitor details",
40
- "monitor-list" => "List monitors",
41
- "monitor-update" => "Update a monitor",
42
- "monitor-delete" => "Delete a monitor",
43
- "monitor-runs-list" => "List monitor runs",
44
- "monitor-runs-get" => "Get monitor run details",
15
+ "search-monitor-create" => "Create a search monitor",
16
+ "search-monitor-get" => "Get search monitor details",
17
+ "search-monitor-list" => "List search monitors",
18
+ "search-monitor-update" => "Update a search monitor",
19
+ "search-monitor-delete" => "Delete a search monitor",
20
+ "search-monitor-trigger" => "Run a search monitor now",
21
+ "search-monitor-batch" => "Delete, pause or unpause search monitors in bulk",
22
+ "search-monitor-runs-list" => "List search monitor runs",
23
+ "search-monitor-runs-get" => "Get search monitor run details",
45
24
  "agent-run-create" => "Create an agent run",
46
25
  "agent-run-get" => "Get agent run details",
47
26
  "agent-run-list" => "List agent runs",
48
27
  "agent-run-cancel" => "Cancel an agent run",
28
+ "agent-run-stop" => "Stop an agent run early and keep its results",
49
29
  "agent-run-delete" => "Delete an agent run",
50
30
  "agent-run-events" => "Get events for an agent run"
51
31
  }.freeze
@@ -71,66 +51,24 @@ module ExaCLI
71
51
  exec File.expand_path("../exa-ai-context", __FILE__), *ARGV[1..]
72
52
  when "get-contents"
73
53
  exec File.expand_path("../exa-ai-get-contents", __FILE__), *ARGV[1..]
74
- when "webset-create"
75
- exec File.expand_path("../exa-ai-webset-create", __FILE__), *ARGV[1..]
76
- when "webset-get"
77
- exec File.expand_path("../exa-ai-webset-get", __FILE__), *ARGV[1..]
78
- when "webset-list"
79
- exec File.expand_path("../exa-ai-webset-list", __FILE__), *ARGV[1..]
80
- when "webset-update"
81
- exec File.expand_path("../exa-ai-webset-update", __FILE__), *ARGV[1..]
82
- when "webset-delete"
83
- exec File.expand_path("../exa-ai-webset-delete", __FILE__), *ARGV[1..]
84
- when "webset-cancel"
85
- exec File.expand_path("../exa-ai-webset-cancel", __FILE__), *ARGV[1..]
86
- when "webset-search-create"
87
- exec File.expand_path("../exa-ai-webset-search-create", __FILE__), *ARGV[1..]
88
- when "webset-search-get"
89
- exec File.expand_path("../exa-ai-webset-search-get", __FILE__), *ARGV[1..]
90
- when "webset-search-cancel"
91
- exec File.expand_path("../exa-ai-webset-search-cancel", __FILE__), *ARGV[1..]
92
- when "webset-item-list"
93
- exec File.expand_path("../exa-ai-webset-item-list", __FILE__), *ARGV[1..]
94
- when "webset-item-get"
95
- exec File.expand_path("../exa-ai-webset-item-get", __FILE__), *ARGV[1..]
96
- when "webset-item-delete"
97
- exec File.expand_path("../exa-ai-webset-item-delete", __FILE__), *ARGV[1..]
98
- when "enrichment-create"
99
- exec File.expand_path("../exa-ai-enrichment-create", __FILE__), *ARGV[1..]
100
- when "enrichment-get"
101
- exec File.expand_path("../exa-ai-enrichment-get", __FILE__), *ARGV[1..]
102
- when "enrichment-list"
103
- exec File.expand_path("../exa-ai-enrichment-list", __FILE__), *ARGV[1..]
104
- when "enrichment-update"
105
- exec File.expand_path("../exa-ai-enrichment-update", __FILE__), *ARGV[1..]
106
- when "enrichment-delete"
107
- exec File.expand_path("../exa-ai-enrichment-delete", __FILE__), *ARGV[1..]
108
- when "enrichment-cancel"
109
- exec File.expand_path("../exa-ai-enrichment-cancel", __FILE__), *ARGV[1..]
110
- when "import-create"
111
- exec File.expand_path("../exa-ai-import-create", __FILE__), *ARGV[1..]
112
- when "import-list"
113
- exec File.expand_path("../exa-ai-import-list", __FILE__), *ARGV[1..]
114
- when "import-get"
115
- exec File.expand_path("../exa-ai-import-get", __FILE__), *ARGV[1..]
116
- when "import-update"
117
- exec File.expand_path("../exa-ai-import-update", __FILE__), *ARGV[1..]
118
- when "import-delete"
119
- exec File.expand_path("../exa-ai-import-delete", __FILE__), *ARGV[1..]
120
- when "monitor-create"
121
- exec File.expand_path("../exa-ai-monitor-create", __FILE__), *ARGV[1..]
122
- when "monitor-get"
123
- exec File.expand_path("../exa-ai-monitor-get", __FILE__), *ARGV[1..]
124
- when "monitor-list"
125
- exec File.expand_path("../exa-ai-monitor-list", __FILE__), *ARGV[1..]
126
- when "monitor-update"
127
- exec File.expand_path("../exa-ai-monitor-update", __FILE__), *ARGV[1..]
128
- when "monitor-delete"
129
- exec File.expand_path("../exa-ai-monitor-delete", __FILE__), *ARGV[1..]
130
- when "monitor-runs-list"
131
- exec File.expand_path("../exa-ai-monitor-runs-list", __FILE__), *ARGV[1..]
132
- when "monitor-runs-get"
133
- exec File.expand_path("../exa-ai-monitor-runs-get", __FILE__), *ARGV[1..]
54
+ when "search-monitor-create"
55
+ exec File.expand_path("../exa-ai-search-monitor-create", __FILE__), *ARGV[1..]
56
+ when "search-monitor-get"
57
+ exec File.expand_path("../exa-ai-search-monitor-get", __FILE__), *ARGV[1..]
58
+ when "search-monitor-list"
59
+ exec File.expand_path("../exa-ai-search-monitor-list", __FILE__), *ARGV[1..]
60
+ when "search-monitor-update"
61
+ exec File.expand_path("../exa-ai-search-monitor-update", __FILE__), *ARGV[1..]
62
+ when "search-monitor-delete"
63
+ exec File.expand_path("../exa-ai-search-monitor-delete", __FILE__), *ARGV[1..]
64
+ when "search-monitor-trigger"
65
+ exec File.expand_path("../exa-ai-search-monitor-trigger", __FILE__), *ARGV[1..]
66
+ when "search-monitor-batch"
67
+ exec File.expand_path("../exa-ai-search-monitor-batch", __FILE__), *ARGV[1..]
68
+ when "search-monitor-runs-list"
69
+ exec File.expand_path("../exa-ai-search-monitor-runs-list", __FILE__), *ARGV[1..]
70
+ when "search-monitor-runs-get"
71
+ exec File.expand_path("../exa-ai-search-monitor-runs-get", __FILE__), *ARGV[1..]
134
72
  when "agent-run-create"
135
73
  exec File.expand_path("../exa-ai-agent-run-create", __FILE__), *ARGV[1..]
136
74
  when "agent-run-get"
@@ -139,6 +77,8 @@ module ExaCLI
139
77
  exec File.expand_path("../exa-ai-agent-run-list", __FILE__), *ARGV[1..]
140
78
  when "agent-run-cancel"
141
79
  exec File.expand_path("../exa-ai-agent-run-cancel", __FILE__), *ARGV[1..]
80
+ when "agent-run-stop"
81
+ exec File.expand_path("../exa-ai-agent-run-stop", __FILE__), *ARGV[1..]
142
82
  when "agent-run-delete"
143
83
  exec File.expand_path("../exa-ai-agent-run-delete", __FILE__), *ARGV[1..]
144
84
  when "agent-run-events"
@@ -166,61 +106,26 @@ module ExaCLI
166
106
  ["get-contents", "Retrieve page contents"]
167
107
  ])
168
108
 
169
- print_command_section("Websets", [
170
- ["webset-create", "Create a new webset"],
171
- ["webset-get", "Get webset details"],
172
- ["webset-list", "List websets"],
173
- ["webset-update", "Update a webset"],
174
- ["webset-delete", "Delete a webset"],
175
- ["webset-cancel", "Cancel a webset"]
176
- ])
177
-
178
- print_command_section("Webset Searches", [
179
- ["webset-search-create", "Create a search in a webset"],
180
- ["webset-search-get", "Get webset search details"],
181
- ["webset-search-cancel", "Cancel a webset search"]
182
- ])
183
-
184
- print_command_section("Webset Items", [
185
- ["webset-item-list", "List items in a webset"],
186
- ["webset-item-get", "Get webset item details"],
187
- ["webset-item-delete", "Delete a webset item"]
188
- ])
189
-
190
- print_command_section("Webset Enrichments", [
191
- ["enrichment-create", "Create an enrichment"],
192
- ["enrichment-get", "Get enrichment details"],
193
- ["enrichment-list", "List enrichments"],
194
- ["enrichment-update", "Update an enrichment"],
195
- ["enrichment-delete", "Delete an enrichment"],
196
- ["enrichment-cancel", "Cancel an enrichment"]
197
- ])
198
-
199
- print_command_section("Imports", [
200
- ["import-create", "Create a new import"],
201
- ["import-list", "List imports"],
202
- ["import-get", "Get import details"],
203
- ["import-update", "Update an import"],
204
- ["import-delete", "Delete an import"]
205
- ])
206
-
207
109
  print_command_section("Agent Runs", [
208
110
  ["agent-run-create", "Create an agent run"],
209
111
  ["agent-run-get", "Get agent run details"],
210
112
  ["agent-run-list", "List agent runs"],
211
113
  ["agent-run-cancel", "Cancel an agent run"],
114
+ ["agent-run-stop", "Stop an agent run early and keep its results"],
212
115
  ["agent-run-delete", "Delete an agent run"],
213
116
  ["agent-run-events", "Get events for an agent run"]
214
117
  ])
215
118
 
216
- print_command_section("Webset Monitors", [
217
- ["monitor-create", "Create a webset monitor"],
218
- ["monitor-get", "Get monitor details"],
219
- ["monitor-list", "List monitors"],
220
- ["monitor-update", "Update a monitor"],
221
- ["monitor-delete", "Delete a monitor"],
222
- ["monitor-runs-list", "List monitor runs"],
223
- ["monitor-runs-get", "Get monitor run details"]
119
+ print_command_section("Search Monitors", [
120
+ ["search-monitor-create", "Create a search monitor"],
121
+ ["search-monitor-get", "Get search monitor details"],
122
+ ["search-monitor-list", "List search monitors"],
123
+ ["search-monitor-update", "Update a search monitor"],
124
+ ["search-monitor-delete", "Delete a search monitor"],
125
+ ["search-monitor-trigger", "Run a search monitor now"],
126
+ ["search-monitor-batch", "Delete, pause or unpause search monitors in bulk"],
127
+ ["search-monitor-runs-list", "List search monitor runs"],
128
+ ["search-monitor-runs-get", "Get search monitor run details"]
224
129
  ])
225
130
 
226
131
  puts "Global Options:"