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
@@ -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 Answer
@@ -9,13 +11,14 @@ module Exa
9
11
  end
10
12
 
11
13
  def call
12
- response = @connection.post("/answer", @params)
14
+ response = @connection.post("/answer", ParameterConverter.convert_keys(@params))
13
15
  body = response.body
14
16
 
15
17
  Resources::Answer.new(
16
18
  answer: body["answer"],
17
19
  citations: body["citations"] || [],
18
- cost_dollars: body["costDollars"]
20
+ cost_dollars: body["costDollars"],
21
+ request_id: body["requestId"]
19
22
  )
20
23
  end
21
24
  end
@@ -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,74 +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|
19
- req.options.on_data = proc do |chunk|
20
- # Add chunk to buffer and process complete SSE events
21
- @buffer += chunk
21
+ @connection.post(path, @params) do |req|
22
+ req.headers.update(headers)
23
+ req.options.on_data = proc do |chunk, _size, env|
24
+ next env[:error_body] = "#{env[:error_body]}#{chunk}" if env&.status.to_i >= 400
25
+
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")
22
29
  process_sse_buffer(&block)
23
30
  end
24
31
  end
25
32
 
26
- # Process any remaining data in buffer after stream ends
27
- 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)
28
35
  end
29
36
 
30
37
  private
31
38
 
32
- def process_sse_buffer
33
- # Extract and process complete SSE events (separated by \n\n)
34
- # If buffer ends with \n\n, all parts are complete.
35
- # 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)
36
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)
37
70
  return if @buffer.empty?
38
71
 
39
72
  parts = @buffer.split("\n\n")
40
73
 
41
- # When split by a delimiter, if the string ends with the delimiter,
42
- # split doesn't add a trailing empty string. So we need to track
43
- # whether the buffer ended with \n\n to know if the last part is incomplete.
44
74
  if @buffer.end_with?("\n\n")
45
- # All parts are complete, clear buffer
46
75
  complete_parts = parts
47
76
  @buffer = ""
48
77
  else
49
- # Last part is incomplete, keep it for next chunk
50
78
  complete_parts = parts[0...-1]
51
79
  @buffer = parts.last || ""
52
80
  end
53
81
 
54
- # Process all complete events
55
- complete_parts.each do |event|
56
- next if event.empty?
57
-
58
- lines = event.split("\n")
59
- lines.each do |line|
60
- if line.start_with?("data: ")
61
- json_str = line.sub(/^data: /, "").strip
62
- begin
63
- data = JSON.parse(json_str)
64
- yield(data)
65
- rescue JSON::ParserError
66
- # Skip lines that aren't valid JSON
67
- end
68
- end
69
- end
70
- end
82
+ complete_parts.each { |frame| process_frame(frame, &block) }
71
83
  end
72
84
 
73
- def process_remaining_buffer
74
- # Process any remaining incomplete buffer
75
- lines = @buffer.split("\n")
76
- lines.each do |line|
77
- if line.start_with?("data: ")
78
- json_str = line.sub(/^data: /, "").strip
79
- begin
80
- data = JSON.parse(json_str)
81
- yield(data)
82
- rescue JSON::ParserError
83
- # Skip lines that aren't valid JSON
84
- end
85
- 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)
86
97
  end
87
98
  end
88
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