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
@@ -0,0 +1,199 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Exa
4
+ module CLI
5
+ # The contents flags that exa-ai-search and exa-ai-find-similar share:
6
+ # how each flag is read from the command line, how the flags become the
7
+ # request's contents hash, and their lines in the help text.
8
+ module ContentsFlags
9
+ VALID_TEXT_VERBOSITY = ["compact", "standard", "full"].freeze
10
+
11
+ # The "Content Extraction" lines of the help text, each with its indent.
12
+ HELP = <<~HELP.gsub(/^/, " ").chomp
13
+ --text Include full webpage text
14
+ --text-max-characters N Max characters for webpage text
15
+ --text-verbosity LEVEL Text verbosity: compact, standard, or full
16
+ --include-html-tags Include HTML tags in text extraction
17
+ --summary Include AI-generated summary
18
+ --summary-query PROMPT Custom prompt for summary generation
19
+ --summary-schema FILE JSON schema for summary structure (@file syntax)
20
+ --context Deprecated: use --highlights or --text instead
21
+ (format results as one context string)
22
+ --context-max-characters N Deprecated: max characters for context string
23
+ --subpages N Deprecated on search: crawl subpages with
24
+ exa-ai get-contents --subpages instead
25
+ --subpage-target PHRASE Deprecated on search: use
26
+ exa-ai get-contents --subpage-target instead
27
+ --links N Number of links to extract per result
28
+ --image-links N Number of image links to extract
29
+ --highlights Include text highlights in results
30
+ --highlights-max-characters N Max characters per highlight
31
+ --highlights-num-sentences N Deprecated: use --highlights-max-characters instead
32
+ --highlights-per-url N Deprecated: the API ignores it
33
+ --highlights-query QUERY Custom query for highlight extraction
34
+ --livecrawl Enable livecrawl (sets maxAgeHours=0, livecrawlTimeout=5000)
35
+ --livecrawl-timeout N Livecrawl timeout in milliseconds (overrides --livecrawl default)
36
+ --max-age-hours N Maximum age of results in hours
37
+ --snapshot-as-of DATE Return page contents as of this time (ISO 8601)
38
+ HELP
39
+
40
+ # Reads the contents flag at argv[index] into args and returns the index
41
+ # of the next argument. Returns nil when argv[index] is not a contents flag.
42
+ def self.parse(argv, index, args)
43
+ case argv[index]
44
+ when "--text"
45
+ args[:text] = true
46
+ index + 1
47
+ when "--text-max-characters"
48
+ args[:text_max_characters] = Base.parse_integer("--text-max-characters", argv[index + 1])
49
+ index + 2
50
+ when "--text-verbosity"
51
+ verbosity = argv[index + 1]
52
+ validate_text_verbosity(verbosity)
53
+ args[:text_verbosity] = verbosity
54
+ index + 2
55
+ when "--include-html-tags"
56
+ args[:include_html_tags] = true
57
+ index + 1
58
+ when "--summary"
59
+ args[:summary] = true
60
+ index + 1
61
+ when "--summary-query"
62
+ args[:summary_query] = Base.text_value("--summary-query", argv[index + 1])
63
+ index + 2
64
+ when "--summary-schema"
65
+ args[:summary_schema] = Base.parse_json_or_file("--summary-schema", argv[index + 1])
66
+ index + 2
67
+ when "--context"
68
+ args[:context] = true
69
+ index + 1
70
+ when "--context-max-characters"
71
+ args[:context_max_characters] = Base.parse_integer("--context-max-characters", argv[index + 1])
72
+ index + 2
73
+ when "--subpages"
74
+ args[:subpages] = Base.parse_integer("--subpages", argv[index + 1])
75
+ index + 2
76
+ when "--subpage-target"
77
+ args[:subpage_target] ||= []
78
+ args[:subpage_target] << Base.text_value("--subpage-target", argv[index + 1])
79
+ index + 2
80
+ when "--links"
81
+ args[:links] = Base.parse_integer("--links", argv[index + 1])
82
+ index + 2
83
+ when "--image-links"
84
+ args[:image_links] = Base.parse_integer("--image-links", argv[index + 1])
85
+ index + 2
86
+ when "--highlights"
87
+ args[:highlights] = true
88
+ index + 1
89
+ when "--highlights-max-characters"
90
+ args[:highlights_max_characters] = Base.parse_integer("--highlights-max-characters", argv[index + 1])
91
+ index + 2
92
+ when "--highlights-num-sentences"
93
+ args[:highlights_num_sentences] = Base.parse_integer("--highlights-num-sentences", argv[index + 1])
94
+ index + 2
95
+ when "--highlights-per-url"
96
+ args[:highlights_per_url] = Base.parse_integer("--highlights-per-url", argv[index + 1])
97
+ index + 2
98
+ when "--highlights-query"
99
+ args[:highlights_query] = Base.text_value("--highlights-query", argv[index + 1])
100
+ index + 2
101
+ when "--livecrawl"
102
+ args[:livecrawl] = true
103
+ index + 1
104
+ when "--livecrawl-timeout"
105
+ args[:livecrawl_timeout] = Base.parse_integer("--livecrawl-timeout", argv[index + 1])
106
+ index + 2
107
+ when "--max-age-hours"
108
+ args[:max_age_hours] = Base.parse_integer("--max-age-hours", argv[index + 1])
109
+ index + 2
110
+ when "--snapshot-as-of"
111
+ args[:snapshot_as_of] = Base.text_value("--snapshot-as-of", argv[index + 1])
112
+ index + 2
113
+ end
114
+ end
115
+
116
+ # Raises ArgumentError unless verbosity is a value the API accepts.
117
+ def self.validate_text_verbosity(verbosity)
118
+ return if VALID_TEXT_VERBOSITY.include?(verbosity)
119
+
120
+ raise ArgumentError, "Text verbosity must be one of: #{VALID_TEXT_VERBOSITY.join(', ')}"
121
+ end
122
+
123
+ # Builds the contents hash from the parsed flags, or nil when no
124
+ # contents flag is set. --snapshot-as-of is not in it: each command
125
+ # sends snapshot_as_of itself.
126
+ def self.build(args)
127
+ contents = {}
128
+
129
+ # Text options
130
+ if args[:text]
131
+ if args[:text_max_characters] || args[:include_html_tags] || args[:text_verbosity]
132
+ contents[:text] = {}
133
+ contents[:text][:max_characters] = args[:text_max_characters] if args[:text_max_characters]
134
+ contents[:text][:include_html_tags] = args[:include_html_tags] if args[:include_html_tags]
135
+ contents[:text][:verbosity] = args[:text_verbosity] if args[:text_verbosity]
136
+ else
137
+ contents[:text] = true
138
+ end
139
+ end
140
+
141
+ # Summary options
142
+ if args[:summary]
143
+ if args[:summary_query] || args[:summary_schema]
144
+ contents[:summary] = {}
145
+ contents[:summary][:query] = args[:summary_query] if args[:summary_query]
146
+ contents[:summary][:schema] = args[:summary_schema] if args[:summary_schema]
147
+ else
148
+ contents[:summary] = true
149
+ end
150
+ end
151
+
152
+ # Context options
153
+ if args[:context]
154
+ if args[:context_max_characters]
155
+ contents[:context] = { max_characters: args[:context_max_characters] }
156
+ else
157
+ contents[:context] = true
158
+ end
159
+ end
160
+
161
+ # Subpages options
162
+ contents[:subpages] = args[:subpages] if args[:subpages]
163
+ contents[:subpage_target] = args[:subpage_target] if args[:subpage_target]
164
+
165
+ # Extras options
166
+ if args[:links] || args[:image_links]
167
+ contents[:extras] = {}
168
+ contents[:extras][:links] = args[:links] if args[:links]
169
+ contents[:extras][:image_links] = args[:image_links] if args[:image_links]
170
+ end
171
+
172
+ # Highlights options
173
+ if args[:highlights]
174
+ highlight_opts = %i[highlights_max_characters highlights_num_sentences highlights_per_url highlights_query]
175
+ if highlight_opts.any? { |k| args[k] }
176
+ contents[:highlights] = {}
177
+ contents[:highlights][:max_characters] = args[:highlights_max_characters] if args[:highlights_max_characters]
178
+ contents[:highlights][:num_sentences] = args[:highlights_num_sentences] if args[:highlights_num_sentences]
179
+ contents[:highlights][:highlights_per_url] = args[:highlights_per_url] if args[:highlights_per_url]
180
+ contents[:highlights][:query] = args[:highlights_query] if args[:highlights_query]
181
+ else
182
+ contents[:highlights] = true
183
+ end
184
+ end
185
+
186
+ # Livecrawl options
187
+ if args[:livecrawl]
188
+ contents[:max_age_hours] = args[:max_age_hours].nil? ? 0 : args[:max_age_hours]
189
+ contents[:livecrawl_timeout] = args[:livecrawl_timeout].nil? ? 5000 : args[:livecrawl_timeout]
190
+ else
191
+ contents[:livecrawl_timeout] = args[:livecrawl_timeout] if args[:livecrawl_timeout]
192
+ contents[:max_age_hours] = args[:max_age_hours] if args[:max_age_hours]
193
+ end
194
+
195
+ contents.empty? ? nil : contents
196
+ end
197
+ end
198
+ end
199
+ end
@@ -17,6 +17,20 @@ module Exa
17
17
  end
18
18
  end
19
19
 
20
+ # Formats the result of deleting a run (id, object, deleted).
21
+ def self.format_deletion(deletion, format)
22
+ case format
23
+ when "pretty"
24
+ deletion.deleted? ? "Deleted agent run: #{deletion.id}" : "Agent run not deleted: #{deletion.id}"
25
+ when "text"
26
+ "#{deletion.id} #{deletion.deleted? ? 'DELETED' : 'NOT_DELETED'}"
27
+ when "toon"
28
+ Exa::CLI::Base.encode_as_toon(deletion.to_h)
29
+ else
30
+ JSON.pretty_generate(deletion.to_h)
31
+ end
32
+ end
33
+
20
34
  def self.format_list(list, format)
21
35
  case format
22
36
  when "json"
@@ -70,9 +84,12 @@ module Exa
70
84
  total = run.cost_dollars.is_a?(Hash) ? (run.cost_dollars["total"] || run.cost_dollars[:total]) : run.cost_dollars
71
85
  output << "Cost: $#{total}"
72
86
  end
87
+ output.concat([data_source_costs_line(run), usage_line(run)].compact)
73
88
  output << "Completed: #{run.completed_at}" if run.completed_at
89
+ output << "Stop reason: #{run.stop_reason}" if run.stop_reason
74
90
  when "failed"
75
91
  output << "Run failed"
92
+ output << error_line(run) if run.error
76
93
  output << "Stop reason: #{run.stop_reason}" if run.stop_reason
77
94
  when "cancelled"
78
95
  output << "Run was cancelled"
@@ -121,22 +138,81 @@ module Exa
121
138
  output << JSON.generate(structured)
122
139
  end
123
140
  elsif run.status == "failed"
124
- output << "Stop reason: #{run.stop_reason}"
141
+ output << error_line(run) if run.error
125
142
  end
143
+ output << "Stop reason: #{run.stop_reason}" if run.stop_reason && %w[completed failed].include?(run.status)
126
144
  output.join("\n")
127
145
  end
128
146
 
147
+ # One line with a failed run's error type, code and message.
148
+ def self.error_line(run)
149
+ error = run.error
150
+ return "Error: #{error}" unless error.is_a?(Hash)
151
+
152
+ "Error: #{error['type']} (#{error['code']}): #{error['message']}"
153
+ end
154
+
129
155
  # Flattens an output.grounding array into displayable source strings,
130
156
  # tolerating both shapes seen from the API: flat {url,title} items and
131
- # nested {citations:[{url,title}]} items.
157
+ # nested {citations:[{url,title}]} items. When an item names the output
158
+ # field it supports, or a confidence, each of its sources ends with
159
+ # "(field: ..., confidence: ...)".
132
160
  def self.grounding_sources(run)
133
161
  grounding = run.output.is_a?(Hash) ? (run.output["grounding"] || run.output[:grounding]) : nil
134
162
  Array(grounding).flat_map do |item|
135
163
  citations = item.is_a?(Hash) && item["citations"] ? item["citations"] : [item]
136
- citations.map { |c| c.is_a?(Hash) ? (c["title"] || c["url"]) : c }
164
+ note = grounding_note(item)
165
+ citations.map do |c|
166
+ source = c.is_a?(Hash) ? (c["title"] || c["url"]) : c
167
+ source && note ? "#{source} (#{note})" : source
168
+ end
137
169
  end.compact
138
170
  end
139
171
 
172
+ # "field: capital, confidence: high" for a grounding item, or nil when
173
+ # the item has neither.
174
+ def self.grounding_note(item)
175
+ return nil unless item.is_a?(Hash)
176
+
177
+ parts = []
178
+ parts << "field: #{item['field']}" if item["field"]
179
+ parts << "confidence: #{item['confidence']}" if item["confidence"]
180
+ parts.empty? ? nil : parts.join(", ")
181
+ end
182
+
183
+ # "Data source costs: fiber $0.04, similarweb $0.3" from
184
+ # costDollars.dataSources, or nil when there is none.
185
+ def self.data_source_costs_line(run)
186
+ return nil unless run.cost_dollars.is_a?(Hash)
187
+
188
+ costs = run.cost_dollars["dataSources"] || run.cost_dollars[:dataSources]
189
+ return nil unless costs.is_a?(Hash) && costs.any?
190
+
191
+ "Data source costs: " + costs.map { |provider, dollars| "#{provider} $#{dollars}" }.join(", ")
192
+ end
193
+
194
+ USAGE_LABELS = {
195
+ "agentComputeUnits" => "agent compute units",
196
+ "searches" => "searches",
197
+ "emails" => "emails",
198
+ "phoneNumbers" => "phone numbers"
199
+ }.freeze
200
+
201
+ # One line with the usage quantities the run reports, for example
202
+ # "Usage: 12.5 agent compute units, 8 searches, data source calls: fiber 2".
203
+ # Only keys present in run.usage appear. Returns nil when there are none.
204
+ def self.usage_line(run)
205
+ return nil unless run.usage.is_a?(Hash)
206
+
207
+ usage = run.usage.transform_keys(&:to_s)
208
+ parts = USAGE_LABELS.filter_map { |key, label| "#{usage[key]} #{label}" if usage.key?(key) }
209
+ calls = usage["dataSources"]
210
+ if calls.is_a?(Hash) && calls.any?
211
+ parts << "data source calls: " + calls.map { |provider, count| "#{provider} #{count}" }.join(", ")
212
+ end
213
+ parts.empty? ? nil : "Usage: #{parts.join(', ')}"
214
+ end
215
+
140
216
  def self.format_list_text(list)
141
217
  output = list.data.map do |run|
142
218
  "#{run.id} #{run.status.upcase} #{run.created_at}"
@@ -19,10 +19,26 @@ module Exa
19
19
  end
20
20
  end
21
21
 
22
+ # Writes one line per API warning to io (stderr by default). The API
23
+ # says warnings are for logs, not for a model, so pretty and text
24
+ # output leave them out; json and toon still carry them through to_h.
25
+ def self.print_warnings(result, io = $stderr)
26
+ (result.warnings || []).each do |warning|
27
+ io.puts "Warning: #{warning['message']} (#{warning['path']})"
28
+ end
29
+ end
30
+
22
31
  private
23
32
 
33
+ # Notices are written for a model to read, so pretty and text output
34
+ # show them above the results.
35
+ def self.notice_lines(result)
36
+ (result.notices || []).map { |notice| "Notice: #{notice['message']}" }
37
+ end
38
+
24
39
  def self.format_pretty(result)
25
- output = []
40
+ output = notice_lines(result)
41
+ output << "" if output.any?
26
42
  result.results.each_with_index do |item, idx|
27
43
  output << "--- Result #{idx + 1} ---"
28
44
  output << "Title: #{item['title']}"
@@ -34,7 +50,7 @@ module Exa
34
50
  end
35
51
 
36
52
  def self.format_text(result)
37
- output = []
53
+ output = notice_lines(result)
38
54
  result.results.each do |item|
39
55
  output << "#{item['title']}\n#{item['url']}"
40
56
  end
@@ -0,0 +1,98 @@
1
+ module Exa
2
+ module CLI
3
+ module Formatters
4
+ # Output for the exa-ai search-monitor-* commands (the /monitors API).
5
+ class SearchMonitorFormatter
6
+ # Format any search monitor result: a monitor, a run, a list of either,
7
+ # a batch result or a trigger result.
8
+ def self.format(result, format)
9
+ case format
10
+ when "pretty" then format_pretty(result)
11
+ when "text" then format_text(result)
12
+ when "toon" then Exa::CLI::Base.encode_as_toon(result.to_h)
13
+ else JSON.pretty_generate(result.to_h)
14
+ end
15
+ end
16
+
17
+ def self.format_pretty(result)
18
+ case result
19
+ when Resources::SearchMonitor then format_monitor_pretty(result)
20
+ when Resources::SearchMonitorRun then format_run_pretty(result)
21
+ when Resources::SearchMonitorList then format_list_pretty(result)
22
+ when Resources::SearchMonitorBatchResult then format_batch_pretty(result)
23
+ else JSON.pretty_generate(result.to_h)
24
+ end
25
+ end
26
+
27
+ def self.format_text(result)
28
+ case result
29
+ when Resources::SearchMonitorList
30
+ result.data.map { |item| summary_line(item) }.join("\n")
31
+ when Resources::SearchMonitor, Resources::SearchMonitorRun
32
+ summary_line(result)
33
+ else
34
+ result.to_h.map { |key, value| "#{key}: #{value}" }.join("\n")
35
+ end
36
+ end
37
+
38
+ def self.format_monitor_pretty(monitor)
39
+ output = []
40
+ output << "Search Monitor: #{monitor.id}"
41
+ output << "Name: #{monitor.name}" if monitor.name
42
+ output << "Status: #{monitor.status}"
43
+ output << "Query: #{monitor.search['query']}" if monitor.search
44
+ output << "Schedule: #{monitor.trigger ? "every #{monitor.trigger['period']}" : 'manual only'}"
45
+ output << "Webhook: #{monitor.webhook['url']}" if monitor.webhook
46
+ output << "Next run: #{monitor.next_run_at}" if monitor.next_run_at
47
+ output << "Created: #{monitor.created_at}" if monitor.created_at
48
+ if monitor.webhook_secret
49
+ output << ""
50
+ output << "Webhook secret: #{monitor.webhook_secret}"
51
+ output << "Save it now. The API returns the webhook secret only once."
52
+ end
53
+ output.join("\n")
54
+ end
55
+
56
+ def self.format_run_pretty(run)
57
+ output = []
58
+ output << "Search Monitor Run: #{run.id}"
59
+ output << "Monitor: #{run.monitor_id}"
60
+ output << "Status: #{run.status}"
61
+ output << "Fail reason: #{run.fail_reason}" if run.fail_reason
62
+ output << "Duration: #{run.duration_ms} ms" if run.duration_ms
63
+ output << "Created: #{run.created_at}" if run.created_at
64
+ if run.output
65
+ output << ""
66
+ output << "Output:"
67
+ output << JSON.pretty_generate(run.output)
68
+ end
69
+ output.join("\n")
70
+ end
71
+
72
+ def self.format_list_pretty(list)
73
+ return "No results found." if list.data.empty?
74
+
75
+ lines = list.data.map { |item| summary_line(item) }
76
+ lines << "" << "More results available. Use --cursor #{list.next_cursor} for next page." if list.has_more
77
+ lines.join("\n")
78
+ end
79
+
80
+ def self.format_batch_pretty(result)
81
+ output = []
82
+ output << (result.dry_run ? "Dry run: nothing changed. Pass --execute to apply." : "Batch #{result.action} applied.")
83
+ output << "Action: #{result.action}"
84
+ output << "Affected: #{result.affected}"
85
+ output << "IDs: #{Array(result.ids).join(', ')}" unless Array(result.ids).empty?
86
+ output << "More monitors match. Run the command again." if result.has_more
87
+ output.join("\n")
88
+ end
89
+
90
+ # One line per monitor or run: id, status, then the name or creation time.
91
+ def self.summary_line(item)
92
+ label = item.is_a?(Resources::SearchMonitor) ? item.name : item.created_at
93
+ [item.id, item.status, label].compact.join(" ")
94
+ end
95
+ end
96
+ end
97
+ end
98
+ end
@@ -1,12 +1,15 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require_relative "contents_flags"
4
+
3
5
  module Exa
4
6
  module CLI
5
7
  class SearchParser
6
- VALID_SEARCH_TYPES = ["auto", "neural", "fast", "deep", "deep-reasoning", "instant"].freeze
7
- VALID_TEXT_VERBOSITY = ["compact", "standard", "full"].freeze
8
+ VALID_SEARCH_TYPES = ["auto", "lite", "deep-lite", "neural", "fast", "deep", "deep-reasoning", "instant"].freeze
9
+ VALID_TEXT_VERBOSITY = ContentsFlags::VALID_TEXT_VERBOSITY
10
+ VALID_COMPLIANCE = ["hipaa"].freeze
8
11
  VALID_CATEGORIES = [
9
- "company", "publication", "news", "github",
12
+ "company", "publication", "news",
10
13
  "personal site", "people", "financial report"
11
14
  ].freeze
12
15
 
@@ -14,6 +17,18 @@ module Exa
14
17
  new(argv).parse
15
18
  end
16
19
 
20
+ # A country code stays a string. An argument that starts with "{" is
21
+ # parsed as a JSON object, and one that starts with "@" is read as a
22
+ # JSON file, the way --output-schema works. A missing value gives nil,
23
+ # so the flag is skipped. Bad JSON or an unreadable file exits 1 with
24
+ # one error line that names --user-location.
25
+ def self.parse_user_location(value)
26
+ return nil if value.nil?
27
+ return Base.parse_json_or_file("--user-location", value) if value.start_with?("@", "{")
28
+
29
+ value
30
+ end
31
+
17
32
  def initialize(argv)
18
33
  @argv = argv
19
34
  @args = {
@@ -36,9 +51,15 @@ module Exa
36
51
 
37
52
  while i < @argv.length
38
53
  arg = @argv[i]
54
+ next_index = ContentsFlags.parse(@argv, i, @args)
55
+ if next_index
56
+ i = next_index
57
+ next
58
+ end
59
+
39
60
  case arg
40
61
  when "--num-results"
41
- @args[:num_results] = @argv[i + 1].to_i
62
+ @args[:num_results] = Exa::CLI::Base.parse_integer("--num-results", @argv[i + 1])
42
63
  i += 2
43
64
  when "--type"
44
65
  search_type = @argv[i + 1]
@@ -51,10 +72,10 @@ module Exa
51
72
  @args[:category] = category
52
73
  i += 2
53
74
  when "--include-domains"
54
- @args[:include_domains] = @argv[i + 1].split(",").map(&:strip)
75
+ @args[:include_domains] = Exa::CLI::Base.option_value("--include-domains", @argv[i + 1]).split(",").map(&:strip)
55
76
  i += 2
56
77
  when "--exclude-domains"
57
- @args[:exclude_domains] = @argv[i + 1].split(",").map(&:strip)
78
+ @args[:exclude_domains] = Exa::CLI::Base.option_value("--exclude-domains", @argv[i + 1]).split(",").map(&:strip)
58
79
  i += 2
59
80
  when "--api-key"
60
81
  @args[:api_key] = @argv[i + 1]
@@ -82,86 +103,26 @@ module Exa
82
103
  @args[:exclude_text] ||= []
83
104
  @args[:exclude_text] << @argv[i + 1]
84
105
  i += 2
85
- when "--text"
86
- @args[:text] = true
87
- i += 1
88
- when "--text-max-characters"
89
- @args[:text_max_characters] = @argv[i + 1].to_i
90
- i += 2
91
- when "--include-html-tags"
92
- @args[:include_html_tags] = true
93
- i += 1
94
- when "--summary"
95
- @args[:summary] = true
96
- i += 1
97
- when "--summary-query"
98
- @args[:summary_query] = @argv[i + 1]
99
- i += 2
100
- when "--summary-schema"
101
- schema_arg = @argv[i + 1]
102
- @args[:summary_schema] = if schema_arg.start_with?("@")
103
- JSON.parse(File.read(schema_arg[1..]))
104
- else
105
- JSON.parse(schema_arg)
106
- end
107
- i += 2
108
- when "--context"
109
- @args[:context] = true
110
- i += 1
111
- when "--context-max-characters"
112
- @args[:context_max_characters] = @argv[i + 1].to_i
113
- i += 2
114
- when "--subpages"
115
- @args[:subpages] = @argv[i + 1].to_i
116
- i += 2
117
- when "--subpage-target"
118
- @args[:subpage_target] ||= []
119
- @args[:subpage_target] << @argv[i + 1]
120
- i += 2
121
- when "--links"
122
- @args[:links] = @argv[i + 1].to_i
123
- i += 2
124
- when "--image-links"
125
- @args[:image_links] = @argv[i + 1].to_i
126
- i += 2
127
- when "--highlights"
128
- @args[:highlights] = true
129
- i += 1
130
- when "--highlights-max-characters"
131
- @args[:highlights_max_characters] = @argv[i + 1].to_i
132
- i += 2
133
- when "--highlights-num-sentences"
134
- @args[:highlights_num_sentences] = @argv[i + 1].to_i
135
- i += 2
136
- when "--highlights-per-url"
137
- @args[:highlights_per_url] = @argv[i + 1].to_i
138
- i += 2
139
- when "--highlights-query"
140
- @args[:highlights_query] = @argv[i + 1]
141
- i += 2
142
- when "--livecrawl"
143
- @args[:livecrawl] = true
144
- i += 1
145
- when "--livecrawl-timeout"
146
- @args[:livecrawl_timeout] = @argv[i + 1].to_i
147
- i += 2
148
- when "--max-age-hours"
149
- @args[:max_age_hours] = @argv[i + 1].to_i
150
- i += 2
151
106
  when "--additional-queries"
152
107
  @args[:additional_queries] ||= []
153
108
  @args[:additional_queries] << @argv[i + 1]
154
109
  i += 2
155
110
  when "--output-schema"
156
- schema_arg = @argv[i + 1]
157
- @args[:output_schema] = if schema_arg.start_with?("@")
158
- JSON.parse(File.read(schema_arg[1..]))
159
- else
160
- JSON.parse(schema_arg)
161
- end
111
+ @args[:output_schema] = Exa::CLI::Base.parse_json_or_file("--output-schema", @argv[i + 1])
162
112
  i += 2
163
113
  when "--user-location"
164
- @args[:user_location] = @argv[i + 1]
114
+ @args[:user_location] = self.class.parse_user_location(@argv[i + 1])
115
+ i += 2
116
+ when "--objective"
117
+ @args[:objective] = @argv[i + 1]
118
+ i += 2
119
+ when "--user-identifier"
120
+ @args[:user_identifier] = @argv[i + 1]
121
+ i += 2
122
+ when "--compliance"
123
+ compliance = @argv[i + 1]
124
+ validate_compliance(compliance)
125
+ @args[:compliance] = compliance
165
126
  i += 2
166
127
  when "--system-prompt"
167
128
  @args[:system_prompt] = @argv[i + 1]
@@ -169,12 +130,9 @@ module Exa
169
130
  when "--moderation"
170
131
  @args[:moderation] = true
171
132
  i += 1
172
- when "--text-verbosity"
173
- verbosity = @argv[i + 1]
174
- validate_text_verbosity(verbosity)
175
- @args[:text_verbosity] = verbosity
176
- i += 2
177
133
  else
134
+ Exa::CLI::Base.reject_unknown_option(arg) if arg.start_with?("--")
135
+
178
136
  query_parts << arg
179
137
  i += 1
180
138
  end
@@ -199,10 +157,11 @@ module Exa
199
157
  raise ArgumentError, "Category must be one of: #{VALID_CATEGORIES.map { |c| "\"#{c}\"" }.join(', ')}"
200
158
  end
201
159
 
202
- def validate_text_verbosity(verbosity)
203
- return if VALID_TEXT_VERBOSITY.include?(verbosity)
160
+ # Raises ArgumentError unless compliance is a value the API accepts.
161
+ def validate_compliance(compliance)
162
+ return if VALID_COMPLIANCE.include?(compliance)
204
163
 
205
- raise ArgumentError, "Text verbosity must be one of: #{VALID_TEXT_VERBOSITY.join(', ')}"
164
+ raise ArgumentError, "Compliance must be one of: #{VALID_COMPLIANCE.join(', ')}"
206
165
  end
207
166
  end
208
167
  end