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
data/lib/exa/client.rb CHANGED
@@ -37,6 +37,23 @@ module Exa
37
37
  # @option params [Array<String>] :include_domains Domains to include in results
38
38
  # @option params [Array<String>] :exclude_domains Domains to exclude from results
39
39
  # @option params [Integer] :num_results Number of results to return
40
+ #
41
+ # Deprecated and legacy parameters still work. The API reports some of
42
+ # them in the response's warnings:
43
+ # - :type "fast" and "instant" are legacy; use "lite". "deep-reasoning"
44
+ # is legacy; use "deep".
45
+ # - :start_crawl_date and :end_crawl_date are deprecated. The API ignores
46
+ # them and adds an IGNORED_FIELD warning.
47
+ # - :include_text and :exclude_text are deprecated.
48
+ # - :context (and :context_max_characters) is deprecated; use :highlights
49
+ # or :text.
50
+ # - :highlights_num_sentences (highlights numSentences) is deprecated; use
51
+ # :highlights_max_characters. :highlights_per_url is deprecated and
52
+ # ignored by the API.
53
+ # - :subpages and :subpage_target are deprecated on search; pass them to
54
+ # #get_contents instead.
55
+ # - :livecrawl is deprecated; use :max_age_hours. :crawled_before_date is
56
+ # deprecated; use :snapshot_as_of, an alias with identical behavior.
40
57
  # @return [Resources::SearchResult] Search results with metadata
41
58
  def search(query, **params)
42
59
  Services::Search.new(connection, query: query, **params).call
@@ -44,21 +61,44 @@ module Exa
44
61
 
45
62
  # Find similar content to a given URL
46
63
  #
64
+ # @deprecated The API marks /findSimilar as deprecated. Use #search with
65
+ # a query that describes the source page instead. This method still
66
+ # works. Its :start_crawl_date, :end_crawl_date, :include_text,
67
+ # :exclude_text, :context, :livecrawl and :crawled_before_date options
68
+ # are deprecated as on #search.
47
69
  # @param url [String] URL to find similar content for
48
70
  # @param options [Hash] Search options
49
71
  # @option options [Integer] :num_results Number of results to return
50
- # @return [Resources::SearchResult] Similar results
72
+ # @return [Resources::FindSimilarResult] Similar results
51
73
  def find_similar(url, **options)
52
74
  Services::FindSimilar.new(connection, url: url, **options).call
53
75
  end
54
76
 
55
77
  # Get full page contents for URLs
56
78
  #
57
- # @param urls [Array<String>, String] URL or URLs to fetch contents for
79
+ # @param urls [Array<String>, String, nil] URL or URLs to fetch contents for,
80
+ # positional or as the urls: keyword. Leave out when passing :ids
81
+ # instead; urls is sent only when given. Nil and empty count as missing.
58
82
  # @param options [Hash] Fetch options
59
- # @return [Resources::ContentCollection] Collection of page contents
60
- def get_contents(urls, **options)
61
- Services::GetContents.new(connection, urls: urls, **options).call
83
+ # @option options [Array<String>] :ids Document IDs from earlier searches
84
+ # @option options [Boolean, Hash] :context Deprecated; use :highlights or
85
+ # :text. The highlights numSentences and highlightsPerUrl keys are also
86
+ # deprecated; use maxCharacters. :subpages and :subpage_target stay
87
+ # valid here.
88
+ # @option options [String] :livecrawl Deprecated; use :max_age_hours.
89
+ # @option options [String] :crawled_before_date Deprecated; use
90
+ # :snapshot_as_of, an alias with identical behavior.
91
+ # @raise [ArgumentError] when neither urls nor :ids is given
92
+ # @return [Resources::ContentsResult] Page contents with metadata
93
+ def get_contents(urls = nil, **options)
94
+ urls ||= options.delete(:urls)
95
+ urls = nil if urls.respond_to?(:empty?) && urls.empty?
96
+ ids = options[:ids]
97
+ ids = nil if ids.respond_to?(:empty?) && ids.empty?
98
+ raise ArgumentError, "get_contents requires urls or the ids: option" unless urls || ids
99
+
100
+ options = { urls: urls }.merge(options) if urls
101
+ Services::GetContents.new(connection, **options).call
62
102
  end
63
103
 
64
104
  # Get AI-generated answers to a query
@@ -86,16 +126,39 @@ module Exa
86
126
  Services::AnswerStream.new(connection, query: query, **options).call(&block)
87
127
  end
88
128
 
129
+ # Stream a search with a synthesized answer
130
+ #
131
+ # The API streams /search only when an output schema is set, so
132
+ # :output_schema is required.
133
+ #
134
+ # @param query [String] Search query
135
+ # @param params [Hash] Search parameters, as for #search
136
+ # @option params [Hash] :output_schema JSON schema for the synthesized output (required)
137
+ # @yield [chunk] Yields each server-sent event as it arrives
138
+ # @yieldparam chunk [Hash] Event with a "type" of text-delta, grounding,
139
+ # results, stream-reset or done. Chunks are yielded as received, so a
140
+ # summary requested with a schema arrives as a JSON string, not a Hash.
141
+ # @raise [ArgumentError] when :output_schema is missing
142
+ # @raise [Exa::Error] when the stream sends an error event
143
+ # @return [void]
144
+ def search_stream(query, **params, &block)
145
+ Services::SearchStream.new(connection, query: query, **params).call(&block)
146
+ end
147
+
89
148
  # Create a new agent run
90
149
  #
91
150
  # @param query [String] The query or task for the agent to execute (required)
92
151
  # @param params [Hash] Additional run parameters
93
- # @option params [Hash] :input Input data for the agent run. Multi-word keys inside
94
- # +input+, +data_sources+ items, and +metadata+ must be supplied in the exact shape
95
- # the API expects — the parameter converter does not recurse into nested values
96
- # (same contract as +output_schema+).
97
- # @option params [Array<Hash>] :data_sources Data sources for the agent run
152
+ # @option params [Hash] :input Input data for the agent run
153
+ # @option params [Array<Hash>] :data_sources Data sources for the agent run (up to 5)
154
+ # @option params [Hash] :budget Spend limits, for example
155
+ # +{max_cost_dollars: 5.0, max_duration_seconds: 1800}+
156
+ # @option params [String] :user_identifier Your identifier for the end user of this run
98
157
  # @option params [Hash] :metadata Custom metadata
158
+ #
159
+ # The parameter converter turns snake_case keys into camelCase at every depth,
160
+ # so +budget+, +input+ and +data_sources+ items can use snake_case keys. Keys
161
+ # inside +metadata+ and +output_schema+ are user data and go out exactly as given.
99
162
  # @return [Resources::AgentRun] The newly created agent run
100
163
  def agent_run_create(query:, **params)
101
164
  Services::AgentRunCreate.new(connection, query: query, **params).call
@@ -105,15 +168,25 @@ module Exa
105
168
  #
106
169
  # @param query [String] The query or task for the agent to execute (required)
107
170
  # @param params [Hash] Additional run parameters
108
- # @option params [Hash] :input Input data for the agent run. Multi-word keys inside
109
- # +input+, +data_sources+ items, and +metadata+ must be supplied in the exact shape
110
- # the API expects — the parameter converter does not recurse into nested values
111
- # (same contract as +output_schema+).
112
- # @option params [Array<Hash>] :data_sources Data sources for the agent run
171
+ # @option params [Hash] :input Input data for the agent run
172
+ # @option params [Array<Hash>] :data_sources Data sources for the agent run (up to 5)
173
+ # @option params [Hash] :budget Spend limits, for example
174
+ # +{max_cost_dollars: 5.0, max_duration_seconds: 1800}+
175
+ # @option params [String] :user_identifier Your identifier for the end user of this run
113
176
  # @option params [Hash] :metadata Custom metadata
114
- # @yield [chunk] Yields each streamed event chunk as it arrives
115
- # @yieldparam chunk [Hash] Partial agent run event data
116
- # @return [void]
177
+ #
178
+ # The parameter converter turns snake_case keys into camelCase at every depth,
179
+ # so +budget+, +input+ and +data_sources+ items can use snake_case keys. Keys
180
+ # inside +metadata+ and +output_schema+ are user data and go out exactly as given.
181
+ #
182
+ # @yield [event_type, data, event_id] Yields each streamed event as it arrives.
183
+ # Blocks and procs that take only (event_type, data) keep working; a lambda
184
+ # passed with & must accept three arguments.
185
+ # @yieldparam event_type [String] Event name, for example "agent_run.completed"
186
+ # @yieldparam data [Hash] The event's JSON payload
187
+ # @yieldparam event_id [String, nil] The SSE id of the event, if the server sent one
188
+ # @return [Resources::AgentRun, nil] The final run from the terminal event, or nil
189
+ # if the stream ended before one arrived
117
190
  def agent_run_stream(query:, **params, &block)
118
191
  Services::AgentRunStream.new(connection, query: query, **params).call(&block)
119
192
  end
@@ -136,7 +209,7 @@ module Exa
136
209
  Services::AgentRunList.new(connection, **params).call
137
210
  end
138
211
 
139
- # Cancel an in-progress agent run
212
+ # Cancel an in-progress agent run. The run ends at once with no results.
140
213
  #
141
214
  # @param run_id [String] Agent run ID
142
215
  # @return [Resources::AgentRun] The cancelled agent run
@@ -144,10 +217,20 @@ module Exa
144
217
  Services::AgentRunCancel.new(connection, run_id: run_id).call
145
218
  end
146
219
 
220
+ # Stop an in-progress agent run early. Unlike cancel, the run completes
221
+ # with stop reason "stopped" and keeps the results gathered so far. The API
222
+ # supports this only for runs with effort high, xhigh or ultra.
223
+ #
224
+ # @param run_id [String] Agent run ID
225
+ # @return [Resources::AgentRun] The stopped agent run
226
+ def agent_run_stop(run_id)
227
+ Services::AgentRunStop.new(connection, run_id: run_id).call
228
+ end
229
+
147
230
  # Delete an agent run
148
231
  #
149
232
  # @param run_id [String] Agent run ID
150
- # @return [Resources::AgentRun] The deleted agent run
233
+ # @return [Resources::AgentRunDeletion] The id of the deleted run and deleted: true
151
234
  def agent_run_delete(run_id)
152
235
  Services::AgentRunDelete.new(connection, run_id: run_id).call
153
236
  end
@@ -158,331 +241,124 @@ module Exa
158
241
  # @param params [Hash] Listing parameters
159
242
  # @option params [Integer] :limit Maximum number of events to return
160
243
  # @option params [String] :cursor Cursor for pagination
161
- # @return [Array<Hash>] List of agent run events
244
+ # @option params [String] :last_event_id Replay the events after this event id.
245
+ # The call then asks for server-sent events (Accept: text/event-stream with a
246
+ # Last-Event-ID header) and reads the whole response before it returns. The
247
+ # docs do not say whether the server closes the stream for a run that is still
248
+ # in progress, so for such a run this call may block until the run ends.
249
+ # If no data arrives within the connection's read timeout, the call raises
250
+ # Faraday::TimeoutError.
251
+ # The result has items {"id", "event", "data"}, has_more false and no cursor.
252
+ # @return [Resources::AgentRunEventList] Agent run events with has_more and next_cursor
162
253
  def agent_run_events(run_id, **params)
163
254
  Services::AgentRunEvents.new(connection, run_id: run_id, **params).call
164
255
  end
165
256
 
166
- # Search code repositories
257
+ # Create a search monitor: a scheduled Exa search that posts new results to a webhook.
258
+ # This is the /monitors API.
167
259
  #
168
- # @param query [String] Code search query
169
- # @param params [Hash] Search parameters
170
- # @option params [Array<String>] :languages Programming languages to search
171
- # @return [Resources::SearchResult] Code search results
172
- def context(query, **params)
173
- Services::Context.new(connection, query: query, **params).call
260
+ # @param search [Hash] Search to run (required: :query; optional :num_results,
261
+ # :include_domains, :exclude_domains, :contents)
262
+ # @param webhook [Hash] Webhook to call (required: :url; optional :events)
263
+ # @param params [Hash] Additional parameters
264
+ # @option params [Hash] :trigger Schedule, e.g. { type: "interval", period: "1d" }.
265
+ # Without it the monitor runs only when triggered by hand.
266
+ # @option params [String] :name Monitor name
267
+ # @option params [Hash] :output_schema JSON schema for structured output (sent as given)
268
+ # @option params [Hash] :metadata Custom metadata (sent as given)
269
+ # @return [Resources::SearchMonitor] The new monitor. Its webhook_secret is returned only once.
270
+ def search_monitor_create(search:, webhook:, **params)
271
+ Services::SearchMonitors::Create.new(connection, search: search, webhook: webhook, **params).call
174
272
  end
175
273
 
176
- # List all websets
274
+ # List search monitors
177
275
  #
178
- # @param params [Hash] Pagination parameters
276
+ # @param params [Hash] Filters and pagination
277
+ # @option params [String] :status Filter by status (active, paused, disabled)
278
+ # @option params [String] :name Filter by name (case-insensitive substring)
279
+ # @option params [Hash] :metadata Filter by metadata key-value pairs
280
+ # @option params [Integer] :limit Results per page
179
281
  # @option params [String] :cursor Cursor for pagination
180
- # @option params [Integer] :limit Maximum number of websets to return
181
- # @return [Resources::WebsetCollection] Paginated list of websets
182
- def list_websets(**params)
183
- Services::Websets::List.new(connection, **params).call
282
+ # @return [Resources::SearchMonitorList] One page of monitors
283
+ def search_monitor_list(**params)
284
+ Services::SearchMonitors::List.new(connection, **params).call
184
285
  end
185
286
 
186
- # Get a specific webset by ID
287
+ # Get a search monitor
187
288
  #
188
- # @param id [String] Webset ID
189
- # @param params [Hash] Optional parameters
190
- # @option params [Array<String>] :expand Resources to expand in response (e.g., ['items'])
191
- # @return [Resources::Webset] The requested webset
192
- def get_webset(id, **params)
193
- Services::Websets::Retrieve.new(connection, id: id, **params).call
194
- end
195
-
196
- # Delete a webset
197
- #
198
- # @param id [String] Webset ID
199
- # @return [Resources::Webset] The deleted webset
200
- def delete_webset(id)
201
- Services::Websets::Delete.new(connection, id: id).call
202
- end
203
-
204
- # Cancel in-progress operations on a webset
205
- #
206
- # @param id [String] Webset ID
207
- # @return [Resources::Webset] The webset with cancelled operations
208
- def cancel_webset(id)
209
- Services::Websets::Cancel.new(connection, id: id).call
210
- end
211
-
212
- # Update a webset's title and/or metadata
213
- #
214
- # @param id [String] Webset ID
215
- # @param params [Hash] Update parameters
216
- # @option params [String] :title Title for the webset
217
- # @option params [Hash] :metadata Metadata to update
218
- # @return [Resources::Webset] The updated webset
219
- def update_webset(id, **params)
220
- Services::Websets::Update.new(connection, id: id, **params).call
221
- end
222
-
223
- # Create a new webset
224
- #
225
- # @param params [Hash] Creation parameters
226
- # @option params [Hash] :search Search configuration
227
- # @return [Resources::Webset] The newly created webset
228
- def create_webset(**params)
229
- Services::Websets::Create.new(connection, **params).call
230
- end
231
-
232
- # Create a new enrichment for a webset
233
- #
234
- # @param webset_id [String] Webset ID
235
- # @param params [Hash] Enrichment parameters
236
- # @option params [String] :description Description of data to extract
237
- # @option params [String] :format Format type (text, url, options, etc.)
238
- # @option params [Array<Hash>] :options Options for enrichment
239
- # @option params [Hash] :metadata Custom metadata
240
- # @return [Resources::WebsetEnrichment] The newly created enrichment
241
- def create_enrichment(webset_id:, **params)
242
- Services::Websets::CreateEnrichment.new(connection, webset_id: webset_id, **params).call
243
- end
244
-
245
- # Get a specific enrichment by ID
246
- #
247
- # @param webset_id [String] Webset ID
248
- # @param id [String] Enrichment ID
249
- # @return [Resources::WebsetEnrichment] The requested enrichment
250
- def get_enrichment(webset_id:, id:)
251
- Services::Websets::RetrieveEnrichment.new(connection, webset_id: webset_id, id: id).call
252
- end
253
-
254
- # Update an enrichment
255
- #
256
- # @param webset_id [String] Webset ID
257
- # @param id [String] Enrichment ID
258
- # @param params [Hash] Update parameters
259
- # @option params [String] :description Updated description
260
- # @option params [String] :format Updated format
261
- # @option params [Array<Hash>] :options Updated options
262
- # @option params [Hash] :metadata Updated metadata
263
- # @return [Resources::WebsetEnrichment] The updated enrichment
264
- def update_enrichment(webset_id:, id:, **params)
265
- Services::Websets::UpdateEnrichment.new(connection, webset_id: webset_id, id: id, **params).call
266
- end
267
-
268
- # Delete an enrichment
269
- #
270
- # @param webset_id [String] Webset ID
271
- # @param id [String] Enrichment ID
272
- # @return [Resources::WebsetEnrichment] The deleted enrichment
273
- def delete_enrichment(webset_id:, id:)
274
- Services::Websets::DeleteEnrichment.new(connection, webset_id: webset_id, id: id).call
275
- end
276
-
277
- # Cancel a running enrichment
278
- #
279
- # @param webset_id [String] Webset ID
280
- # @param id [String] Enrichment ID
281
- # @return [Resources::WebsetEnrichment] The cancelled enrichment
282
- def cancel_enrichment(webset_id:, id:)
283
- Services::Websets::CancelEnrichment.new(connection, webset_id: webset_id, id: id).call
284
- end
285
-
286
- # Create a new search within a webset
287
- #
288
- # @param webset_id [String] Webset ID
289
- # @param params [Hash] Search parameters
290
- # @option params [String] :query The search query (required)
291
- # @option params [Integer] :count Number of results to find
292
- # @option params [Hash] :entity Entity type specification
293
- # @option params [Array<Hash>] :criteria Search criteria
294
- # @option params [Array<Hash>] :exclude Items to exclude from results
295
- # @option params [Array<Hash>] :scope Limit search to specific sources
296
- # @option params [Boolean] :recall Whether to estimate total available results
297
- # @option params [String] :behavior "override" or "append" (default: "override")
298
- # @option params [Hash] :metadata Custom metadata
299
- # @return [Resources::WebsetSearch] The newly created search
300
- def create_webset_search(webset_id:, **params)
301
- Services::Websets::CreateSearch.new(connection, webset_id: webset_id, **params).call
302
- end
303
-
304
- # Get a webset search by ID
305
- #
306
- # @param webset_id [String] Webset ID
307
- # @param id [String] Search ID
308
- # @return [Resources::WebsetSearch] The requested search
309
- def get_webset_search(webset_id:, id:)
310
- Services::Websets::GetSearch.new(connection, webset_id: webset_id, id: id).call
311
- end
312
-
313
- # Cancel a webset search
314
- #
315
- # @param webset_id [String] Webset ID
316
- # @param id [String] Search ID
317
- # @return [Resources::WebsetSearch] The cancelled search
318
- def cancel_webset_search(webset_id:, id:)
319
- Services::Websets::CancelSearch.new(connection, webset_id: webset_id, id: id).call
320
- end
321
-
322
- # Get a webset item by ID
323
- #
324
- # @param webset_id [String] Webset ID
325
- # @param id [String] Item ID
326
- # @return [Hash] The requested item
327
- def get_item(webset_id:, id:)
328
- Services::Websets::GetItem.new(connection, webset_id: webset_id, id: id).call
329
- end
330
-
331
- # Delete a webset item by ID
332
- #
333
- # @param webset_id [String] Webset ID
334
- # @param id [String] Item ID
335
- # @return [Boolean] True if deletion was successful
336
- def delete_item(webset_id:, id:)
337
- Services::Websets::DeleteItem.new(connection, webset_id: webset_id, id: id).call
338
- end
339
-
340
- # List all items in a webset
341
- #
342
- # @param webset_id [String] Webset ID
343
- # @param params [Hash] Pagination parameters
344
- # @option params [String] :cursor Cursor for pagination
345
- # @option params [Integer] :limit Maximum number of items to return (default: 20)
346
- # @return [Resources::WebsetItemCollection] Paginated list of items
347
- def list_items(webset_id:, **params)
348
- Services::Websets::ListItems.new(connection, webset_id: webset_id, **params).call
349
- end
350
-
351
- # List all imports
352
- #
353
- # @param params [Hash] Pagination parameters
354
- # @option params [String] :cursor Cursor for pagination
355
- # @option params [Integer] :limit Maximum number of imports to return
356
- # @return [Resources::ImportCollection] Paginated list of imports
357
- def list_imports(**params)
358
- Services::Websets::ListImports.new(connection, **params).call
359
- end
360
-
361
- # Create a new import
362
- #
363
- # @param params [Hash] Import parameters
364
- # @option params [Integer] :size Size of the import file
365
- # @option params [Integer] :count Number of items to import
366
- # @option params [String] :title Import title
367
- # @option params [String] :format Import format (e.g., "csv")
368
- # @option params [Hash] :entity Entity type specification
369
- # @option params [Hash] :metadata Custom metadata
370
- # @option params [Hash] :csv CSV-specific configuration
371
- # @return [Resources::Import] The newly created import
372
- def create_import(**params)
373
- Services::Websets::CreateImport.new(connection, **params).call
374
- end
375
-
376
- # Upload a file for import (creates import and uploads file)
377
- #
378
- # @param file_path [String] Path to the file to upload
379
- # @param params [Hash] Import parameters
380
- # @option params [Integer] :count Number of items to import
381
- # @option params [String] :title Import title
382
- # @option params [String] :format Import format (e.g., "csv")
383
- # @option params [Hash] :entity Entity type specification
384
- # @option params [Hash] :metadata Custom metadata
385
- # @option params [Hash] :csv CSV-specific configuration
386
- # @return [Resources::Import] The created import (file size is inferred automatically)
387
- def upload_import(file_path:, **params)
388
- Services::Websets::UploadImport.new(connection, file_path: file_path, **params).call
389
- end
390
-
391
- # Get a specific import by ID
392
- #
393
- # @param id [String] Import ID
394
- # @return [Resources::Import] The requested import
395
- def get_import(id)
396
- Services::Websets::GetImport.new(connection, id: id).call
397
- end
398
-
399
- # Update an import
400
- #
401
- # @param id [String] Import ID
402
- # @param params [Hash] Update parameters
403
- # @option params [String] :title Updated title
404
- # @option params [Hash] :metadata Updated metadata
405
- # @return [Resources::Import] The updated import
406
- def update_import(id, **params)
407
- Services::Websets::UpdateImport.new(connection, id: id, **params).call
408
- end
409
-
410
- # Delete an import
411
- #
412
- # @param id [String] Import ID
413
- # @return [Resources::Import] The deleted import
414
- def delete_import(id)
415
- Services::Websets::DeleteImport.new(connection, id: id).call
289
+ # @param id [String] Monitor ID
290
+ # @return [Resources::SearchMonitor] The monitor
291
+ def search_monitor_get(id)
292
+ Services::SearchMonitors::Get.new(connection, id: id).call
416
293
  end
417
294
 
418
- # Create a new monitor for a webset
295
+ # Update a search monitor. Only the keys given are changed.
419
296
  #
420
- # @param webset_id [String] Webset ID
421
- # @param cadence [Hash] Schedule configuration with :cron and :timezone
422
- # @param behavior [Hash] Behavior configuration (type, query, etc.)
423
- # @param params [Hash] Additional monitor parameters
424
- # @option params [Hash] :metadata Custom metadata
425
- # @return [Resources::Monitor] The newly created monitor
426
- def create_monitor(webset_id:, cadence:, behavior:, **params)
427
- Services::Websets::Monitors::Create.new(connection, webset_id: webset_id, cadence: cadence, behavior: behavior, **params).call
297
+ # @param id [String] Monitor ID
298
+ # @param params [Hash] Fields to change: :name, :status, :search, :trigger,
299
+ # :webhook, :output_schema, :metadata. Pass trigger: nil to remove the schedule.
300
+ # @return [Resources::SearchMonitor] The updated monitor
301
+ def search_monitor_update(id, **params)
302
+ Services::SearchMonitors::Update.new(connection, id: id, **params).call
428
303
  end
429
304
 
430
- # List all monitors
305
+ # Delete a search monitor
431
306
  #
432
- # @param params [Hash] Pagination parameters
433
- # @option params [String] :cursor Cursor for pagination
434
- # @option params [Integer] :limit Maximum number of monitors to return
435
- # @return [Resources::MonitorCollection] Paginated list of monitors
436
- def list_monitors(**params)
437
- Services::Websets::Monitors::List.new(connection, **params).call
307
+ # @param id [String] Monitor ID
308
+ # @return [Resources::SearchMonitor] The deleted monitor
309
+ def search_monitor_delete(id)
310
+ Services::SearchMonitors::Delete.new(connection, id: id).call
438
311
  end
439
312
 
440
- # Get a specific monitor by ID
313
+ # Run a search monitor now. Works when its status is active or paused.
441
314
  #
442
315
  # @param id [String] Monitor ID
443
- # @return [Resources::Monitor] The requested monitor
444
- def get_monitor(id:)
445
- Services::Websets::Monitors::Get.new(connection, id: id).call
316
+ # @return [Resources::SearchMonitorTriggerResult] Whether a run started
317
+ def search_monitor_trigger(id)
318
+ Services::SearchMonitors::Trigger.new(connection, id: id).call
446
319
  end
447
320
 
448
- # Update a monitor
321
+ # Delete, pause or unpause every search monitor that matches a filter.
322
+ # Call again until has_more is false.
449
323
  #
450
- # @param id [String] Monitor ID
451
- # @param params [Hash] Update parameters
452
- # @option params [Hash] :cadence Updated schedule configuration
453
- # @option params [Hash] :behavior Updated behavior configuration
454
- # @option params [Hash] :metadata Updated metadata
455
- # @return [Resources::Monitor] The updated monitor
456
- def update_monitor(id:, **params)
457
- Services::Websets::Monitors::Update.new(connection, id: id, **params).call
324
+ # @param action [String] "delete", "pause" or "unpause"
325
+ # @param filter [Hash] :name, :status and/or :metadata to match
326
+ # @param dry_run [Boolean] Only report what would change. True unless you pass false.
327
+ # @param limit [Integer, nil] Maximum monitors to change in this call
328
+ # @return [Resources::SearchMonitorBatchResult] What changed, or would change
329
+ def search_monitor_batch(action:, filter:, dry_run: true, limit: nil)
330
+ Services::SearchMonitors::Batch.new(connection, action: action, filter: filter, dry_run: dry_run, limit: limit).call
458
331
  end
459
332
 
460
- # Delete a monitor
333
+ # List the runs of a search monitor
461
334
  #
462
- # @param id [String] Monitor ID
463
- # @return [Resources::Monitor] The deleted monitor
464
- def delete_monitor(id:)
465
- Services::Websets::Monitors::Delete.new(connection, id: id).call
335
+ # @param monitor_id [String] Monitor ID
336
+ # @param params [Hash] Pagination: :limit, :cursor
337
+ # @return [Resources::SearchMonitorList] One page of runs
338
+ def search_monitor_runs_list(monitor_id, **params)
339
+ Services::SearchMonitors::RunsList.new(connection, monitor_id: monitor_id, **params).call
466
340
  end
467
341
 
468
- # List all runs for a specific monitor
342
+ # Get one run of a search monitor
469
343
  #
470
344
  # @param monitor_id [String] Monitor ID
471
- # @param params [Hash] Pagination parameters
472
- # @option params [String] :cursor Cursor for pagination
473
- # @option params [Integer] :limit Maximum number of runs to return
474
- # @return [Resources::MonitorRunCollection] Paginated list of monitor runs
475
- def list_monitor_runs(monitor_id:, **params)
476
- Services::Websets::Monitors::Runs::List.new(connection, monitor_id: monitor_id, **params).call
345
+ # @param run_id [String] Run ID
346
+ # @return [Resources::SearchMonitorRun] The run
347
+ def search_monitor_runs_get(monitor_id, run_id)
348
+ Services::SearchMonitors::RunsGet.new(connection, monitor_id: monitor_id, run_id: run_id).call
477
349
  end
478
350
 
479
- # Get a specific monitor run by ID
351
+ # Search code repositories
480
352
  #
481
- # @param monitor_id [String] Monitor ID
482
- # @param id [String] Run ID
483
- # @return [Resources::MonitorRun] The requested monitor run
484
- def get_monitor_run(monitor_id:, id:)
485
- Services::Websets::Monitors::Runs::Get.new(connection, monitor_id: monitor_id, id: id).call
353
+ # @deprecated The Exa API spec no longer lists POST /context. The
354
+ # endpoint still answers and this method still works, but no
355
+ # replacement is named. For code lookup, use #search.
356
+ # @param query [String] Code search query
357
+ # @param params [Hash] Search parameters
358
+ # @option params [Array<String>] :languages Programming languages to search
359
+ # @return [Resources::SearchResult] Code search results
360
+ def context(query, **params)
361
+ Services::Context.new(connection, query: query, **params).call
486
362
  end
487
363
 
488
364
  private
@@ -2,9 +2,9 @@ module Exa
2
2
  module Resources
3
3
  class AgentRun < Struct.new(
4
4
  :id, :object, :status, :stop_reason, :created_at, :completed_at,
5
- :request, :output, :usage, :cost_dollars, keyword_init: true
5
+ :request, :output, :usage, :cost_dollars, :error, keyword_init: true
6
6
  )
7
- def initialize(id:, object:, status:, stop_reason: nil, created_at: nil, completed_at: nil, request: nil, output: nil, usage: nil, cost_dollars: nil)
7
+ def initialize(id:, object:, status:, stop_reason: nil, created_at: nil, completed_at: nil, request: nil, output: nil, usage: nil, cost_dollars: nil, error: nil)
8
8
  super
9
9
  freeze
10
10
  end
@@ -22,7 +22,8 @@ module Exa
22
22
  request: body["request"],
23
23
  output: body["output"],
24
24
  usage: body["usage"],
25
- cost_dollars: body["costDollars"]
25
+ cost_dollars: body["costDollars"],
26
+ error: body["error"]
26
27
  )
27
28
  end
28
29
 
@@ -47,6 +48,7 @@ module Exa
47
48
  result[:output] = output if output
48
49
  result[:usage] = usage if usage
49
50
  result[:cost_dollars] = cost_dollars if cost_dollars
51
+ result[:error] = error if error
50
52
  result
51
53
  end
52
54
  end
@@ -0,0 +1,17 @@
1
+ module Exa
2
+ module Resources
3
+ # Result of DELETE /agent/runs/{id}: {id, object: "agent_run.deleted", deleted: true}.
4
+ class AgentRunDeletion < Struct.new(:id, :object, :deleted, keyword_init: true)
5
+ def initialize(id:, object:, deleted:)
6
+ super
7
+ freeze
8
+ end
9
+
10
+ def deleted? = deleted == true
11
+
12
+ def to_h
13
+ { id: id, object: object, deleted: deleted }
14
+ end
15
+ end
16
+ end
17
+ end