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
data/lib/exa/client.rb CHANGED
@@ -4,7 +4,7 @@ module Exa
4
4
  # Main client for interacting with the Exa.ai API
5
5
  #
6
6
  # Provides methods for all supported Exa.ai operations including search,
7
- # content retrieval, answer generation, and async research tasks.
7
+ # content retrieval, answer generation, and agent runs.
8
8
  #
9
9
  # @example Basic usage
10
10
  # client = Exa::Client.new(api_key: "your-key")
@@ -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,42 +126,39 @@ module Exa
86
126
  Services::AnswerStream.new(connection, query: query, **options).call(&block)
87
127
  end
88
128
 
89
- # Start an asynchronous research task
90
- #
91
- # @param params [Hash] Research parameters
92
- # @return [Resources::Research] Research task with ID
93
- def research_start(**params)
94
- Services::ResearchStart.new(connection, **params).call
95
- end
96
-
97
- # List all research tasks
129
+ # Stream a search with a synthesized answer
98
130
  #
99
- # @param params [Hash] Listing parameters
100
- # @option params [Integer] :limit Maximum number of tasks to return
101
- # @return [Resources::ResearchList] List of research tasks
102
- def research_list(**params)
103
- Services::ResearchList.new(connection, **params).call
104
- end
105
-
106
- # Get status and results of a research task
131
+ # The API streams /search only when an output schema is set, so
132
+ # :output_schema is required.
107
133
  #
108
- # @param research_id [String] Research task ID
109
- # @param params [Hash] Fetch options
110
- # @return [Resources::Research] Research task with current status and results
111
- def research_get(research_id, **params)
112
- Services::ResearchGet.new(connection, research_id: research_id, **params).call
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)
113
146
  end
114
147
 
115
148
  # Create a new agent run
116
149
  #
117
150
  # @param query [String] The query or task for the agent to execute (required)
118
151
  # @param params [Hash] Additional run parameters
119
- # @option params [Hash] :input Input data for the agent run. Multi-word keys inside
120
- # +input+, +data_sources+ items, and +metadata+ must be supplied in the exact shape
121
- # the API expects — the parameter converter does not recurse into nested values
122
- # (same contract as +output_schema+).
123
- # @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
124
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.
125
162
  # @return [Resources::AgentRun] The newly created agent run
126
163
  def agent_run_create(query:, **params)
127
164
  Services::AgentRunCreate.new(connection, query: query, **params).call
@@ -131,15 +168,25 @@ module Exa
131
168
  #
132
169
  # @param query [String] The query or task for the agent to execute (required)
133
170
  # @param params [Hash] Additional run parameters
134
- # @option params [Hash] :input Input data for the agent run. Multi-word keys inside
135
- # +input+, +data_sources+ items, and +metadata+ must be supplied in the exact shape
136
- # the API expects — the parameter converter does not recurse into nested values
137
- # (same contract as +output_schema+).
138
- # @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
139
176
  # @option params [Hash] :metadata Custom metadata
140
- # @yield [chunk] Yields each streamed event chunk as it arrives
141
- # @yieldparam chunk [Hash] Partial agent run event data
142
- # @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
143
190
  def agent_run_stream(query:, **params, &block)
144
191
  Services::AgentRunStream.new(connection, query: query, **params).call(&block)
145
192
  end
@@ -162,7 +209,7 @@ module Exa
162
209
  Services::AgentRunList.new(connection, **params).call
163
210
  end
164
211
 
165
- # Cancel an in-progress agent run
212
+ # Cancel an in-progress agent run. The run ends at once with no results.
166
213
  #
167
214
  # @param run_id [String] Agent run ID
168
215
  # @return [Resources::AgentRun] The cancelled agent run
@@ -170,10 +217,20 @@ module Exa
170
217
  Services::AgentRunCancel.new(connection, run_id: run_id).call
171
218
  end
172
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
+
173
230
  # Delete an agent run
174
231
  #
175
232
  # @param run_id [String] Agent run ID
176
- # @return [Resources::AgentRun] The deleted agent run
233
+ # @return [Resources::AgentRunDeletion] The id of the deleted run and deleted: true
177
234
  def agent_run_delete(run_id)
178
235
  Services::AgentRunDelete.new(connection, run_id: run_id).call
179
236
  end
@@ -184,331 +241,124 @@ module Exa
184
241
  # @param params [Hash] Listing parameters
185
242
  # @option params [Integer] :limit Maximum number of events to return
186
243
  # @option params [String] :cursor Cursor for pagination
187
- # @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
188
253
  def agent_run_events(run_id, **params)
189
254
  Services::AgentRunEvents.new(connection, run_id: run_id, **params).call
190
255
  end
191
256
 
192
- # 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.
193
259
  #
194
- # @param query [String] Code search query
195
- # @param params [Hash] Search parameters
196
- # @option params [Array<String>] :languages Programming languages to search
197
- # @return [Resources::SearchResult] Code search results
198
- def context(query, **params)
199
- 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
200
272
  end
201
273
 
202
- # List all websets
274
+ # List search monitors
203
275
  #
204
- # @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
205
281
  # @option params [String] :cursor Cursor for pagination
206
- # @option params [Integer] :limit Maximum number of websets to return
207
- # @return [Resources::WebsetCollection] Paginated list of websets
208
- def list_websets(**params)
209
- Services::Websets::List.new(connection, **params).call
210
- end
211
-
212
- # Get a specific webset by ID
213
- #
214
- # @param id [String] Webset ID
215
- # @param params [Hash] Optional parameters
216
- # @option params [Array<String>] :expand Resources to expand in response (e.g., ['items'])
217
- # @return [Resources::Webset] The requested webset
218
- def get_webset(id, **params)
219
- Services::Websets::Retrieve.new(connection, id: id, **params).call
220
- end
221
-
222
- # Delete a webset
223
- #
224
- # @param id [String] Webset ID
225
- # @return [Resources::Webset] The deleted webset
226
- def delete_webset(id)
227
- Services::Websets::Delete.new(connection, id: id).call
228
- end
229
-
230
- # Cancel in-progress operations on a webset
231
- #
232
- # @param id [String] Webset ID
233
- # @return [Resources::Webset] The webset with cancelled operations
234
- def cancel_webset(id)
235
- Services::Websets::Cancel.new(connection, id: id).call
236
- end
237
-
238
- # Update a webset's title and/or metadata
239
- #
240
- # @param id [String] Webset ID
241
- # @param params [Hash] Update parameters
242
- # @option params [String] :title Title for the webset
243
- # @option params [Hash] :metadata Metadata to update
244
- # @return [Resources::Webset] The updated webset
245
- def update_webset(id, **params)
246
- Services::Websets::Update.new(connection, id: id, **params).call
247
- end
248
-
249
- # Create a new webset
250
- #
251
- # @param params [Hash] Creation parameters
252
- # @option params [Hash] :search Search configuration
253
- # @return [Resources::Webset] The newly created webset
254
- def create_webset(**params)
255
- Services::Websets::Create.new(connection, **params).call
256
- end
257
-
258
- # Create a new enrichment for a webset
259
- #
260
- # @param webset_id [String] Webset ID
261
- # @param params [Hash] Enrichment parameters
262
- # @option params [String] :description Description of data to extract
263
- # @option params [String] :format Format type (text, url, options, etc.)
264
- # @option params [Array<Hash>] :options Options for enrichment
265
- # @option params [Hash] :metadata Custom metadata
266
- # @return [Resources::WebsetEnrichment] The newly created enrichment
267
- def create_enrichment(webset_id:, **params)
268
- Services::Websets::CreateEnrichment.new(connection, webset_id: webset_id, **params).call
282
+ # @return [Resources::SearchMonitorList] One page of monitors
283
+ def search_monitor_list(**params)
284
+ Services::SearchMonitors::List.new(connection, **params).call
269
285
  end
270
286
 
271
- # Get a specific enrichment by ID
287
+ # Get a search monitor
272
288
  #
273
- # @param webset_id [String] Webset ID
274
- # @param id [String] Enrichment ID
275
- # @return [Resources::WebsetEnrichment] The requested enrichment
276
- def get_enrichment(webset_id:, id:)
277
- Services::Websets::RetrieveEnrichment.new(connection, webset_id: webset_id, id: id).call
278
- end
279
-
280
- # Update an enrichment
281
- #
282
- # @param webset_id [String] Webset ID
283
- # @param id [String] Enrichment ID
284
- # @param params [Hash] Update parameters
285
- # @option params [String] :description Updated description
286
- # @option params [String] :format Updated format
287
- # @option params [Array<Hash>] :options Updated options
288
- # @option params [Hash] :metadata Updated metadata
289
- # @return [Resources::WebsetEnrichment] The updated enrichment
290
- def update_enrichment(webset_id:, id:, **params)
291
- Services::Websets::UpdateEnrichment.new(connection, webset_id: webset_id, id: id, **params).call
292
- end
293
-
294
- # Delete an enrichment
295
- #
296
- # @param webset_id [String] Webset ID
297
- # @param id [String] Enrichment ID
298
- # @return [Resources::WebsetEnrichment] The deleted enrichment
299
- def delete_enrichment(webset_id:, id:)
300
- Services::Websets::DeleteEnrichment.new(connection, webset_id: webset_id, id: id).call
301
- end
302
-
303
- # Cancel a running enrichment
304
- #
305
- # @param webset_id [String] Webset ID
306
- # @param id [String] Enrichment ID
307
- # @return [Resources::WebsetEnrichment] The cancelled enrichment
308
- def cancel_enrichment(webset_id:, id:)
309
- Services::Websets::CancelEnrichment.new(connection, webset_id: webset_id, id: id).call
310
- end
311
-
312
- # Create a new search within a webset
313
- #
314
- # @param webset_id [String] Webset ID
315
- # @param params [Hash] Search parameters
316
- # @option params [String] :query The search query (required)
317
- # @option params [Integer] :count Number of results to find
318
- # @option params [Hash] :entity Entity type specification
319
- # @option params [Array<Hash>] :criteria Search criteria
320
- # @option params [Array<Hash>] :exclude Items to exclude from results
321
- # @option params [Array<Hash>] :scope Limit search to specific sources
322
- # @option params [Boolean] :recall Whether to estimate total available results
323
- # @option params [String] :behavior "override" or "append" (default: "override")
324
- # @option params [Hash] :metadata Custom metadata
325
- # @return [Resources::WebsetSearch] The newly created search
326
- def create_webset_search(webset_id:, **params)
327
- Services::Websets::CreateSearch.new(connection, webset_id: webset_id, **params).call
328
- end
329
-
330
- # Get a webset search by ID
331
- #
332
- # @param webset_id [String] Webset ID
333
- # @param id [String] Search ID
334
- # @return [Resources::WebsetSearch] The requested search
335
- def get_webset_search(webset_id:, id:)
336
- Services::Websets::GetSearch.new(connection, webset_id: webset_id, id: id).call
337
- end
338
-
339
- # Cancel a webset search
340
- #
341
- # @param webset_id [String] Webset ID
342
- # @param id [String] Search ID
343
- # @return [Resources::WebsetSearch] The cancelled search
344
- def cancel_webset_search(webset_id:, id:)
345
- Services::Websets::CancelSearch.new(connection, webset_id: webset_id, id: id).call
346
- end
347
-
348
- # Get a webset item by ID
349
- #
350
- # @param webset_id [String] Webset ID
351
- # @param id [String] Item ID
352
- # @return [Hash] The requested item
353
- def get_item(webset_id:, id:)
354
- Services::Websets::GetItem.new(connection, webset_id: webset_id, id: id).call
355
- end
356
-
357
- # Delete a webset item by ID
358
- #
359
- # @param webset_id [String] Webset ID
360
- # @param id [String] Item ID
361
- # @return [Boolean] True if deletion was successful
362
- def delete_item(webset_id:, id:)
363
- Services::Websets::DeleteItem.new(connection, webset_id: webset_id, id: id).call
364
- end
365
-
366
- # List all items in a webset
367
- #
368
- # @param webset_id [String] Webset ID
369
- # @param params [Hash] Pagination parameters
370
- # @option params [String] :cursor Cursor for pagination
371
- # @option params [Integer] :limit Maximum number of items to return (default: 20)
372
- # @return [Resources::WebsetItemCollection] Paginated list of items
373
- def list_items(webset_id:, **params)
374
- Services::Websets::ListItems.new(connection, webset_id: webset_id, **params).call
375
- end
376
-
377
- # List all imports
378
- #
379
- # @param params [Hash] Pagination parameters
380
- # @option params [String] :cursor Cursor for pagination
381
- # @option params [Integer] :limit Maximum number of imports to return
382
- # @return [Resources::ImportCollection] Paginated list of imports
383
- def list_imports(**params)
384
- Services::Websets::ListImports.new(connection, **params).call
385
- end
386
-
387
- # Create a new import
388
- #
389
- # @param params [Hash] Import parameters
390
- # @option params [Integer] :size Size of the import file
391
- # @option params [Integer] :count Number of items to import
392
- # @option params [String] :title Import title
393
- # @option params [String] :format Import format (e.g., "csv")
394
- # @option params [Hash] :entity Entity type specification
395
- # @option params [Hash] :metadata Custom metadata
396
- # @option params [Hash] :csv CSV-specific configuration
397
- # @return [Resources::Import] The newly created import
398
- def create_import(**params)
399
- Services::Websets::CreateImport.new(connection, **params).call
400
- end
401
-
402
- # Upload a file for import (creates import and uploads file)
403
- #
404
- # @param file_path [String] Path to the file to upload
405
- # @param params [Hash] Import parameters
406
- # @option params [Integer] :count Number of items to import
407
- # @option params [String] :title Import title
408
- # @option params [String] :format Import format (e.g., "csv")
409
- # @option params [Hash] :entity Entity type specification
410
- # @option params [Hash] :metadata Custom metadata
411
- # @option params [Hash] :csv CSV-specific configuration
412
- # @return [Resources::Import] The created import (file size is inferred automatically)
413
- def upload_import(file_path:, **params)
414
- Services::Websets::UploadImport.new(connection, file_path: file_path, **params).call
415
- end
416
-
417
- # Get a specific import by ID
418
- #
419
- # @param id [String] Import ID
420
- # @return [Resources::Import] The requested import
421
- def get_import(id)
422
- Services::Websets::GetImport.new(connection, id: id).call
423
- end
424
-
425
- # Update an import
426
- #
427
- # @param id [String] Import ID
428
- # @param params [Hash] Update parameters
429
- # @option params [String] :title Updated title
430
- # @option params [Hash] :metadata Updated metadata
431
- # @return [Resources::Import] The updated import
432
- def update_import(id, **params)
433
- Services::Websets::UpdateImport.new(connection, id: id, **params).call
434
- end
435
-
436
- # Delete an import
437
- #
438
- # @param id [String] Import ID
439
- # @return [Resources::Import] The deleted import
440
- def delete_import(id)
441
- 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
442
293
  end
443
294
 
444
- # Create a new monitor for a webset
295
+ # Update a search monitor. Only the keys given are changed.
445
296
  #
446
- # @param webset_id [String] Webset ID
447
- # @param cadence [Hash] Schedule configuration with :cron and :timezone
448
- # @param behavior [Hash] Behavior configuration (type, query, etc.)
449
- # @param params [Hash] Additional monitor parameters
450
- # @option params [Hash] :metadata Custom metadata
451
- # @return [Resources::Monitor] The newly created monitor
452
- def create_monitor(webset_id:, cadence:, behavior:, **params)
453
- 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
454
303
  end
455
304
 
456
- # List all monitors
305
+ # Delete a search monitor
457
306
  #
458
- # @param params [Hash] Pagination parameters
459
- # @option params [String] :cursor Cursor for pagination
460
- # @option params [Integer] :limit Maximum number of monitors to return
461
- # @return [Resources::MonitorCollection] Paginated list of monitors
462
- def list_monitors(**params)
463
- 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
464
311
  end
465
312
 
466
- # Get a specific monitor by ID
313
+ # Run a search monitor now. Works when its status is active or paused.
467
314
  #
468
315
  # @param id [String] Monitor ID
469
- # @return [Resources::Monitor] The requested monitor
470
- def get_monitor(id:)
471
- 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
472
319
  end
473
320
 
474
- # Update a monitor
321
+ # Delete, pause or unpause every search monitor that matches a filter.
322
+ # Call again until has_more is false.
475
323
  #
476
- # @param id [String] Monitor ID
477
- # @param params [Hash] Update parameters
478
- # @option params [Hash] :cadence Updated schedule configuration
479
- # @option params [Hash] :behavior Updated behavior configuration
480
- # @option params [Hash] :metadata Updated metadata
481
- # @return [Resources::Monitor] The updated monitor
482
- def update_monitor(id:, **params)
483
- 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
484
331
  end
485
332
 
486
- # Delete a monitor
333
+ # List the runs of a search monitor
487
334
  #
488
- # @param id [String] Monitor ID
489
- # @return [Resources::Monitor] The deleted monitor
490
- def delete_monitor(id:)
491
- 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
492
340
  end
493
341
 
494
- # List all runs for a specific monitor
342
+ # Get one run of a search monitor
495
343
  #
496
344
  # @param monitor_id [String] Monitor ID
497
- # @param params [Hash] Pagination parameters
498
- # @option params [String] :cursor Cursor for pagination
499
- # @option params [Integer] :limit Maximum number of runs to return
500
- # @return [Resources::MonitorRunCollection] Paginated list of monitor runs
501
- def list_monitor_runs(monitor_id:, **params)
502
- 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
503
349
  end
504
350
 
505
- # Get a specific monitor run by ID
351
+ # Search code repositories
506
352
  #
507
- # @param monitor_id [String] Monitor ID
508
- # @param id [String] Run ID
509
- # @return [Resources::MonitorRun] The requested monitor run
510
- def get_monitor_run(monitor_id:, id:)
511
- 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
512
362
  end
513
363
 
514
364
  private