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
@@ -1,11 +1,14 @@
1
1
  require "json"
2
2
 
3
+ require_relative "parameter_converter"
4
+ require_relative "agent_run_stream"
5
+
3
6
  module Exa
4
7
  module Services
5
8
  class AnswerStream
6
9
  def initialize(connection, **params)
7
10
  @connection = connection
8
- @params = params.merge(stream: true)
11
+ @params = ParameterConverter.convert_keys(params.merge(stream: true))
9
12
  end
10
13
 
11
14
  def call(&block)
@@ -15,76 +18,82 @@ module Exa
15
18
  @buffer = ""
16
19
 
17
20
  # Configure the request to stream chunks via on_data callback
18
- @connection.post("/answer", @params) do |req|
21
+ @connection.post(path, @params) do |req|
22
+ req.headers.update(headers)
19
23
  req.options.on_data = proc do |chunk, _size, env|
20
24
  next env[:error_body] = "#{env[:error_body]}#{chunk}" if env&.status.to_i >= 400
21
25
 
22
- # Add chunk to buffer and process complete SSE events
23
- @buffer += chunk
26
+ # Normalise CRLF line endings. A "\r" at the end of one chunk joins
27
+ # its "\n" here once the next chunk arrives.
28
+ @buffer = (@buffer + chunk).gsub("\r\n", "\n")
24
29
  process_sse_buffer(&block)
25
30
  end
26
31
  end
27
32
 
28
- # Process any remaining data in buffer after stream ends
29
- process_remaining_buffer(&block) if @buffer.length.positive?
33
+ # Process the last frame when the stream ends without a blank line
34
+ process_frame(@buffer, &block)
30
35
  end
31
36
 
32
37
  private
33
38
 
34
- def process_sse_buffer
35
- # Extract and process complete SSE events (separated by \n\n)
36
- # If buffer ends with \n\n, all parts are complete.
37
- # Otherwise, keep the last part in buffer for next chunk.
39
+ # The endpoint this stream posts to. SearchStream overrides it.
40
+ def path
41
+ "/answer"
42
+ end
43
+
44
+ # Extra request headers for this stream. SearchStream overrides it.
45
+ def headers
46
+ {}
47
+ end
48
+
49
+ # Raises Exa::Error when a chunk is an error event.
50
+ # /search sends {"type":"error","error":{"message":...}}; /answer sends
51
+ # {"tag":"ERROR","payload":{"error":{"code":...,"message":...}}}.
52
+ # A chunk that is not a JSON object is never an error event. When the
53
+ # message is missing, the chunk itself becomes the message.
54
+ def raise_if_error_chunk(data)
55
+ return unless data.is_a?(Hash)
38
56
 
57
+ message = if data["type"] == "error"
58
+ data.dig("error", "message")
59
+ elsif data["tag"] == "ERROR"
60
+ data.dig("payload", "error", "message")
61
+ else
62
+ return
63
+ end
64
+ raise Exa::Error, message || JSON.generate(data)
65
+ end
66
+
67
+ # Yields each complete frame in the buffer and keeps the incomplete
68
+ # tail for the next chunk.
69
+ def process_sse_buffer(&block)
39
70
  return if @buffer.empty?
40
71
 
41
72
  parts = @buffer.split("\n\n")
42
73
 
43
- # When split by a delimiter, if the string ends with the delimiter,
44
- # split doesn't add a trailing empty string. So we need to track
45
- # whether the buffer ended with \n\n to know if the last part is incomplete.
46
74
  if @buffer.end_with?("\n\n")
47
- # All parts are complete, clear buffer
48
75
  complete_parts = parts
49
76
  @buffer = ""
50
77
  else
51
- # Last part is incomplete, keep it for next chunk
52
78
  complete_parts = parts[0...-1]
53
79
  @buffer = parts.last || ""
54
80
  end
55
81
 
56
- # Process all complete events
57
- complete_parts.each do |event|
58
- next if event.empty?
59
-
60
- lines = event.split("\n")
61
- lines.each do |line|
62
- if line.start_with?("data: ")
63
- json_str = line.sub(/^data: /, "").strip
64
- begin
65
- data = JSON.parse(json_str)
66
- yield(data)
67
- rescue JSON::ParserError
68
- # Skip lines that aren't valid JSON
69
- end
70
- end
71
- end
72
- end
82
+ complete_parts.each { |frame| process_frame(frame, &block) }
73
83
  end
74
84
 
75
- def process_remaining_buffer
76
- # Process any remaining incomplete buffer
77
- lines = @buffer.split("\n")
78
- lines.each do |line|
79
- if line.start_with?("data: ")
80
- json_str = line.sub(/^data: /, "").strip
81
- begin
82
- data = JSON.parse(json_str)
83
- yield(data)
84
- rescue JSON::ParserError
85
- # Skip lines that aren't valid JSON
86
- end
87
- end
85
+ # Yields the data of each data: line in one SSE frame. Each line is its
86
+ # own JSON value, so a bad line does not drop a good one next to it.
87
+ # Lines that are not data lines, and data that is not JSON such as
88
+ # [DONE], are skipped.
89
+ def process_frame(frame)
90
+ frame.split("\n").each do |line|
91
+ event = AgentRunStream.parse_frame(line)
92
+ next unless event
93
+
94
+ data = event[1]
95
+ raise_if_error_chunk(data)
96
+ yield(data)
88
97
  end
89
98
  end
90
99
  end
@@ -1,5 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require_relative "parameter_converter"
4
+
3
5
  module Exa
4
6
  module Services
5
7
  class Context
@@ -9,7 +11,7 @@ module Exa
9
11
  end
10
12
 
11
13
  def call
12
- response = @connection.post("/context", @params)
14
+ response = @connection.post("/context", ParameterConverter.convert_keys(@params))
13
15
  body = response.body
14
16
 
15
17
  Resources::ContextResult.new(
@@ -2,6 +2,9 @@
2
2
 
3
3
  require_relative "../resources/find_similar_result"
4
4
 
5
+ require_relative "parameter_converter"
6
+ require_relative "search"
7
+
5
8
  module Exa
6
9
  module Services
7
10
  class FindSimilar
@@ -11,14 +14,18 @@ module Exa
11
14
  end
12
15
 
13
16
  def call
14
- response = @connection.post("/findSimilar", @params)
17
+ request_body = ParameterConverter.convert(@params)
18
+ response = @connection.post("/findSimilar", request_body) do |request|
19
+ request.headers.update(Search.beta_headers(request_body))
20
+ end
15
21
  body = response.body
16
22
 
17
23
  Resources::FindSimilarResult.new(
18
24
  results: body["results"],
19
25
  request_id: body["requestId"],
20
26
  context: body["context"],
21
- cost_dollars: body["costDollars"]
27
+ cost_dollars: body["costDollars"],
28
+ search_time: body["searchTime"]
22
29
  )
23
30
  end
24
31
  end
@@ -1,5 +1,8 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require_relative "parameter_converter"
4
+ require_relative "search"
5
+
3
6
  module Exa
4
7
  module Services
5
8
  class GetContents
@@ -9,35 +12,31 @@ module Exa
9
12
  end
10
13
 
11
14
  def call
12
- response = @connection.post("/contents", @params)
15
+ request_body = ParameterConverter.convert_contents(@params)
16
+ response = @connection.post("/contents", request_body) do |request|
17
+ request.headers.update(Search.beta_headers(request_body))
18
+ end
13
19
  body = response.body
14
20
 
15
21
  results = body["results"]
16
- results = parse_json_summaries(results) if summary_schema?
22
+ results = Search.parse_json_summaries(results) if summary_schema?(request_body)
17
23
 
18
24
  Resources::ContentsResult.new(
19
25
  results: results,
20
26
  request_id: body["requestId"],
21
27
  context: body["context"],
22
28
  statuses: body["statuses"],
23
- cost_dollars: body["costDollars"]
29
+ cost_dollars: body["costDollars"],
30
+ search_time: body["searchTime"]
24
31
  )
25
32
  end
26
33
 
27
34
  private
28
35
 
29
- def summary_schema?
30
- @params[:summary].is_a?(Hash) && @params[:summary][:schema]
31
- end
32
-
33
- def parse_json_summaries(results)
34
- results&.map do |r|
35
- if r["summary"].is_a?(String)
36
- r.merge("summary" => JSON.parse(r["summary"]))
37
- else
38
- r
39
- end
40
- end
36
+ # True when the request asked for JSON summaries. Reads the converted
37
+ # body, so a flat summary_schema: counts as well as summary: {schema:}.
38
+ def summary_schema?(request_body)
39
+ request_body[:summary].is_a?(Hash) && request_body[:summary][:schema]
41
40
  end
42
41
  end
43
42
  end
@@ -9,20 +9,53 @@ module Exa
9
9
  new.convert(params)
10
10
  end
11
11
 
12
+ # Folds flat content keys under their parent at the top level, with no
13
+ # :contents wrapper, then converts every key to camelCase. This is the
14
+ # shape /contents takes: text, summary and highlights sit at the top.
15
+ def self.convert_contents(params)
16
+ new.convert_contents(params)
17
+ end
18
+
19
+ # Converts every key, at every depth, to camelCase without folding or
20
+ # moving any key. For /answer and /context, which take no content
21
+ # sub-options.
22
+ def self.convert_keys(params)
23
+ new.convert_keys(params)
24
+ end
25
+
26
+ def convert_keys(params)
27
+ deep_convert(params)
28
+ end
29
+
30
+ # Instance form of ParameterConverter.convert_contents.
31
+ def convert_contents(params)
32
+ deep_convert(consolidate_content_params(params))
33
+ end
34
+
35
+ # Folds flat content keys under their parent, then moves content
36
+ # options under :contents. A caller's own contents hash, given under
37
+ # :contents or "contents", is merged with the folded keys into one
38
+ # :contents key; flat keys win on a real conflict. A String key that
39
+ # names a content option, at the top level, inside contents or inside
40
+ # an option such as text, is matched with the same Symbol key. Flat
41
+ # keys inside the caller's contents hash are not folded.
12
42
  def convert(params)
13
43
  consolidated = consolidate_content_params(params)
14
44
  converted = {}
15
45
  contents = {}
16
46
 
17
47
  consolidated.each do |key, value|
18
- if content_key?(key)
19
- contents[convert_content_key(key)] = convert_content_value(key, value)
48
+ converted_key = convert_key(key)
49
+ if key == :contents
50
+ converted[:contents] = merge_option(converted[:contents], deep_convert(value))
51
+ elsif content_key?(key)
52
+ contents[converted_key] = convert_value(converted_key, value)
20
53
  else
21
- converted[convert_key(key)] = value
54
+ converted[converted_key] = convert_value(converted_key, value)
22
55
  end
23
56
  end
24
57
 
25
- converted[:contents] = contents if contents.any?
58
+ converted[:contents] = merge_option(converted[:contents], contents) if contents.any?
26
59
  converted
27
60
  end
28
61
 
@@ -32,6 +65,9 @@ module Exa
32
65
  text_max_characters: { parent: :text, key: :max_characters },
33
66
  include_html_tags: { parent: :text, key: :include_html_tags },
34
67
  text_verbosity: { parent: :text, key: :verbosity },
68
+ text_link_style: { parent: :text, key: :link_style },
69
+ text_include_sections: { parent: :text, key: :include_sections },
70
+ text_exclude_sections: { parent: :text, key: :exclude_sections },
35
71
  summary_query: { parent: :summary, key: :query },
36
72
  summary_schema: { parent: :summary, key: :schema },
37
73
  context_max_characters: { parent: :context, key: :max_characters },
@@ -39,145 +75,126 @@ module Exa
39
75
  highlights_num_sentences: { parent: :highlights, key: :num_sentences },
40
76
  highlights_per_url: { parent: :highlights, key: :highlights_per_url },
41
77
  highlights_query: { parent: :highlights, key: :query },
78
+ highlights_verbosity: { parent: :highlights, key: :verbosity },
79
+ highlights_dynamic: { parent: :highlights, key: :dynamic },
42
80
  image_links: { parent: :extras, key: :image_links },
81
+ rich_image_links: { parent: :extras, key: :rich_image_links },
43
82
  links: { parent: :extras, key: :links }
44
83
  }.freeze
45
84
 
85
+ # Keys that go under :contents on /search and /findSimilar.
86
+ CONTENT_KEYS = %i[text summary context subpages subpage_target extras highlights livecrawl livecrawl_timeout
87
+ max_age_hours snapshot_as_of crawled_before_date].freeze
88
+
89
+ # The parents whose own option keys are all matched as Symbols.
90
+ OPTION_PARENTS = %i[text highlights summary extras context].freeze
91
+
92
+ # Content option names that a String key is matched against.
93
+ CONTENT_OPTION_NAMES = (CONTENT_KEYS + CONTENT_SUB_PARAMS.keys + [:contents]).map(&:to_s).freeze
94
+
95
+ # Returns the Symbol form of a String key that names a content option,
96
+ # so "text" and :text fold into one key. Any other key is returned as is.
97
+ def content_symbol(key)
98
+ return key unless key.is_a?(String) && CONTENT_OPTION_NAMES.include?(key)
99
+
100
+ key.to_sym
101
+ end
102
+
103
+ # Gives String keys inside a content option's Hash their Symbol form:
104
+ # every key inside text, highlights, summary, extras and context, and
105
+ # content option names inside contents (and their keys in turn). Keys
106
+ # that become the same Symbol merge with merge_option. Values under
107
+ # these keys, a schema included, are left as given.
108
+ def symbolize_option_keys(parent, value)
109
+ return value unless value.is_a?(Hash)
110
+ return value unless parent == :contents || OPTION_PARENTS.include?(parent)
111
+
112
+ value.reduce({}) do |result, (key, nested)|
113
+ if parent == :contents
114
+ key = content_symbol(key)
115
+ nested = symbolize_option_keys(key, nested)
116
+ elsif key.is_a?(String)
117
+ key = key.to_sym
118
+ end
119
+ merge_option(result, { key => nested })
120
+ end
121
+ end
122
+
123
+ # Folds each flat content key under its parent so the API gets one nested option per parent.
46
124
  def consolidate_content_params(params)
47
125
  result = {}
48
126
  params.each do |key, value|
127
+ key = content_symbol(key)
128
+ value = symbolize_option_keys(key, value)
49
129
  mapping = CONTENT_SUB_PARAMS[key]
50
130
  if mapping
51
131
  parent = mapping[:parent]
52
- result[parent] = {} if result[parent] == true || !result.key?(parent)
53
- result[parent] = {} unless result[parent].is_a?(Hash)
54
- result[parent][mapping[:key]] = value
132
+ result[parent] = merge_option(result[parent], { mapping[:key] => value })
55
133
  else
56
- result[key] = value
134
+ result[key] = merge_option(result[key], value)
57
135
  end
58
136
  end
59
137
  result
60
138
  end
61
139
 
62
- def convert_key(key)
63
- case key
64
- when :start_published_date then :startPublishedDate
65
- when :end_published_date then :endPublishedDate
66
- when :start_crawl_date then :startCrawlDate
67
- when :end_crawl_date then :endCrawlDate
68
- when :include_text then :includeText
69
- when :exclude_text then :excludeText
70
- when :external_id then :externalId
71
- when :additional_queries then :additionalQueries
72
- when :output_schema then :outputSchema
73
- when :user_location then :userLocation
74
- when :num_results then :numResults
75
- when :include_domains then :includeDomains
76
- when :exclude_domains then :excludeDomains
77
- when :system_prompt then :systemPrompt
78
- when :previous_run_id then :previousRunId
79
- when :data_sources then :dataSources
80
- else
81
- key
140
+ # Merges an incoming option value into an existing one. Two Hashes
141
+ # merge key by key; a Hash beats a bare true, which only turns the
142
+ # option on, so text: true and text_max_characters: 500 give the same
143
+ # result in either order. Otherwise the incoming value wins, so with
144
+ # false or nil the key given last wins. A value under a
145
+ # protected key (a user's schema) is replaced, never merged.
146
+ def merge_option(existing, incoming)
147
+ return existing if existing.is_a?(Hash) && incoming == true
148
+ return incoming unless existing.is_a?(Hash) && incoming.is_a?(Hash)
149
+
150
+ existing.merge(incoming) do |key, existing_value, incoming_value|
151
+ next incoming_value if PROTECTED_KEYS.include?(camelize(key).to_s)
152
+
153
+ merge_option(existing_value, incoming_value)
82
154
  end
83
155
  end
84
156
 
85
- def content_key?(key)
86
- %i[text summary context subpages subpage_target extras highlights livecrawl livecrawl_timeout max_age_hours].include?(key)
157
+ # Values under these keys are user data (JSON schemas, free-form maps,
158
+ # input records), so their keys are sent exactly as given.
159
+ PROTECTED_KEYS = %w[outputSchema schema metadata data exclusion].freeze
160
+
161
+ def convert_key(key)
162
+ camelize(key)
87
163
  end
88
164
 
89
- def convert_content_key(key)
90
- case key
91
- when :subpage_target then :subpageTarget
92
- when :livecrawl_timeout then :livecrawlTimeout
93
- when :max_age_hours then :maxAgeHours
94
- else
95
- key
96
- end
165
+ # Turns foo_bar_baz into fooBarBaz and keeps the key's type (Symbol or
166
+ # String). A key with no underscore, camelCase included, is left alone.
167
+ def camelize(key)
168
+ return key unless key.is_a?(Symbol) || key.is_a?(String)
169
+ return key unless key.to_s.include?("_")
170
+
171
+ camelized = key.to_s.gsub(/_([a-z\d])/) { Regexp.last_match(1).upcase }
172
+ key.is_a?(Symbol) ? camelized.to_sym : camelized
97
173
  end
98
174
 
99
- def convert_content_value(key, value)
100
- case key
101
- when :text
102
- if value.is_a?(Hash)
103
- convert_hash_value(value, text_hash_mappings)
104
- else
105
- value
106
- end
107
- when :summary
108
- if value.is_a?(Hash)
109
- convert_hash_value(value, summary_hash_mappings)
110
- else
111
- value
112
- end
113
- when :context
114
- if value.is_a?(Hash)
115
- convert_hash_value(value, context_hash_mappings)
116
- else
117
- value
118
- end
119
- when :extras
120
- if value.is_a?(Hash)
121
- convert_hash_value(value, extras_hash_mappings)
122
- else
123
- value
124
- end
125
- when :highlights
126
- if value.is_a?(Hash)
127
- convert_hash_value(value, highlights_hash_mappings)
128
- else
129
- value
175
+ def deep_convert(value)
176
+ case value
177
+ when Hash
178
+ value.each_with_object({}) do |(key, nested), result|
179
+ converted_key = convert_key(key)
180
+ result[converted_key] = convert_value(converted_key, nested)
130
181
  end
182
+ when Array
183
+ value.map { |element| deep_convert(element) }
131
184
  else
132
185
  value
133
186
  end
134
187
  end
135
188
 
136
- def convert_hash_value(hash, mappings)
137
- converted = {}
138
- hash.each do |k, v|
139
- converted_key = mappings[k] || k
140
- converted[converted_key] = v
141
- end
142
- converted
143
- end
144
-
145
- def text_hash_mappings
146
- {
147
- max_characters: :maxCharacters,
148
- include_html_tags: :includeHtmlTags,
149
- include_sections: :includeSections,
150
- exclude_sections: :excludeSections,
151
- verbosity: :verbosity
152
- }
153
- end
154
-
155
- def summary_hash_mappings
156
- {
157
- query: :query,
158
- schema: :schema
159
- }
160
- end
189
+ def convert_value(converted_key, value)
190
+ return value if PROTECTED_KEYS.include?(converted_key.to_s)
161
191
 
162
- def context_hash_mappings
163
- {
164
- max_characters: :maxCharacters
165
- }
192
+ deep_convert(value)
166
193
  end
167
194
 
168
- def extras_hash_mappings
169
- {
170
- image_links: :imageLinks
171
- }
172
- end
173
-
174
- def highlights_hash_mappings
175
- {
176
- max_characters: :maxCharacters,
177
- num_sentences: :numSentences,
178
- highlights_per_url: :highlightsPerUrl,
179
- query: :query
180
- }
195
+ # True for keys that convert moves under :contents, where /search and /findSimilar expect them.
196
+ def content_key?(key)
197
+ CONTENT_KEYS.include?(key)
181
198
  end
182
199
  end
183
200
  end
@@ -5,8 +5,48 @@ require_relative "parameter_converter"
5
5
  module Exa
6
6
  module Services
7
7
  class Search
8
- VALID_SEARCH_TYPES = ["auto", "neural", "fast", "deep", "deep-reasoning", "instant"].freeze
8
+ VALID_SEARCH_TYPES = ["auto", "lite", "deep-lite", "neural", "fast", "deep", "deep-reasoning", "instant"].freeze
9
9
  DEFAULT_SEARCH_TYPE = "auto"
10
+ DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28"
11
+ BETA_HIGHLIGHTS_KEYS = %w[dynamic verbosity].freeze
12
+
13
+ # Returns the Exa-Beta header that a converted request body needs, or an
14
+ # empty hash. The API rejects highlights.dynamic and highlights.verbosity
15
+ # without it. Highlights sit under contents on /search and /findSimilar
16
+ # and at the top level on /contents, so both places are checked.
17
+ def self.beta_headers(body)
18
+ contents = body[:contents] || body["contents"]
19
+ highlights = contents[:highlights] || contents["highlights"] if contents.is_a?(Hash)
20
+ highlights ||= body[:highlights] || body["highlights"]
21
+ return {} unless highlights.is_a?(Hash)
22
+ return {} unless highlights.keys.any? { |key| BETA_HIGHLIGHTS_KEYS.include?(key.to_s) }
23
+
24
+ { "Exa-Beta" => DYNAMIC_HIGHLIGHTS_BETA }
25
+ end
26
+
27
+ # Raises ArgumentError unless search_type is one of VALID_SEARCH_TYPES.
28
+ def self.validate_search_type!(search_type)
29
+ return if VALID_SEARCH_TYPES.include?(search_type)
30
+
31
+ raise ArgumentError, "Invalid search type: '#{search_type}'. Must be one of: #{VALID_SEARCH_TYPES.join(', ')}"
32
+ end
33
+
34
+ # Parses each result whose summary is a String of JSON into a Hash. The
35
+ # API returns a summary as JSON text when the request gave a schema.
36
+ # A summary that is not valid JSON, an empty one included, is kept as
37
+ # received, so one bad summary does not lose the other results.
38
+ # GetContents uses it too.
39
+ def self.parse_json_summaries(results)
40
+ results&.map do |r|
41
+ next r unless r["summary"].is_a?(String)
42
+
43
+ begin
44
+ r.merge("summary" => JSON.parse(r["summary"]))
45
+ rescue JSON::ParserError
46
+ r
47
+ end
48
+ end
49
+ end
10
50
 
11
51
  def initialize(connection, **params)
12
52
  @connection = connection
@@ -15,11 +55,14 @@ module Exa
15
55
  end
16
56
 
17
57
  def call
18
- response = @connection.post("/search", ParameterConverter.convert(@params))
58
+ request_body = ParameterConverter.convert(@params)
59
+ response = @connection.post("/search", request_body) do |request|
60
+ request.headers.update(self.class.beta_headers(request_body))
61
+ end
19
62
  body = response.body
20
63
 
21
64
  results = body["results"]
22
- results = parse_json_summaries(results) if summary_schema?
65
+ results = self.class.parse_json_summaries(results) if summary_schema?(request_body)
23
66
 
24
67
  Resources::SearchResult.new(
25
68
  results: results,
@@ -28,7 +71,10 @@ module Exa
28
71
  search_type: body["searchType"],
29
72
  context: body["context"],
30
73
  cost_dollars: body["costDollars"],
31
- output: body["output"]
74
+ output: body["output"],
75
+ warnings: body["warnings"],
76
+ notices: body["notices"],
77
+ search_time: body["searchTime"]
32
78
  )
33
79
  end
34
80
 
@@ -42,24 +88,17 @@ module Exa
42
88
  end
43
89
 
44
90
  def validate_search_type!
45
- search_type = @params[:type]
46
- return if VALID_SEARCH_TYPES.include?(search_type)
47
-
48
- raise ArgumentError, "Invalid search type: '#{search_type}'. Must be one of: #{VALID_SEARCH_TYPES.join(', ')}"
91
+ self.class.validate_search_type!(@params[:type])
49
92
  end
50
93
 
51
- def summary_schema?
52
- @params[:summary].is_a?(Hash) && @params[:summary][:schema]
53
- end
94
+ # True when the request asked for JSON summaries. Reads the converted
95
+ # body, so a flat summary_schema: and a caller's contents: {summary:
96
+ # {schema:}} count as well as summary: {schema:}.
97
+ def summary_schema?(request_body)
98
+ contents = request_body[:contents]
99
+ return false unless contents.is_a?(Hash)
54
100
 
55
- def parse_json_summaries(results)
56
- results&.map do |r|
57
- if r["summary"].is_a?(String)
58
- r.merge("summary" => JSON.parse(r["summary"]))
59
- else
60
- r
61
- end
62
- end
101
+ contents[:summary].is_a?(Hash) && contents[:summary][:schema]
63
102
  end
64
103
  end
65
104
  end