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.
- checksums.yaml +4 -4
- data/README.md +119 -73
- data/exe/exa-ai +41 -136
- data/exe/exa-ai-agent-run-create +55 -20
- data/exe/exa-ai-agent-run-delete +1 -8
- data/exe/exa-ai-agent-run-events +21 -1
- data/exe/exa-ai-agent-run-list +1 -1
- data/exe/exa-ai-agent-run-stop +93 -0
- data/exe/exa-ai-answer +25 -0
- data/exe/exa-ai-context +6 -2
- data/exe/exa-ai-find-similar +26 -68
- data/exe/exa-ai-get-contents +138 -42
- data/exe/exa-ai-search +27 -104
- data/exe/exa-ai-search-monitor-batch +93 -0
- data/exe/exa-ai-search-monitor-create +104 -0
- data/exe/exa-ai-search-monitor-delete +69 -0
- data/exe/exa-ai-search-monitor-get +69 -0
- data/exe/exa-ai-search-monitor-list +73 -0
- data/exe/exa-ai-search-monitor-runs-get +68 -0
- data/exe/exa-ai-search-monitor-runs-list +75 -0
- data/exe/exa-ai-search-monitor-trigger +69 -0
- data/exe/exa-ai-search-monitor-update +102 -0
- data/lib/exa/cli/base.rb +57 -0
- data/lib/exa/cli/contents_flags.rb +199 -0
- data/lib/exa/cli/formatters/agent_run_formatter.rb +79 -3
- data/lib/exa/cli/formatters/search_formatter.rb +18 -2
- data/lib/exa/cli/formatters/search_monitor_formatter.rb +98 -0
- data/lib/exa/cli/search_parser.rb +46 -87
- data/lib/exa/client.rb +186 -310
- data/lib/exa/resources/agent_run.rb +5 -3
- data/lib/exa/resources/agent_run_deletion.rb +17 -0
- data/lib/exa/resources/answer.rb +3 -3
- data/lib/exa/resources/contents_result.rb +5 -1
- data/lib/exa/resources/find_similar_result.rb +5 -1
- data/lib/exa/resources/search_monitor.rb +42 -0
- data/lib/exa/resources/search_monitor_batch_result.rb +11 -0
- data/lib/exa/resources/search_monitor_list.rb +19 -0
- data/lib/exa/resources/search_monitor_run.rb +46 -0
- data/lib/exa/resources/search_monitor_trigger_result.rb +11 -0
- data/lib/exa/resources/search_result.rb +11 -1
- data/lib/exa/services/agent_run_cancel.rb +1 -12
- data/lib/exa/services/agent_run_create.rb +1 -12
- data/lib/exa/services/agent_run_delete.rb +6 -14
- data/lib/exa/services/agent_run_events.rb +33 -4
- data/lib/exa/services/agent_run_get.rb +1 -12
- data/lib/exa/services/agent_run_list.rb +1 -12
- data/lib/exa/services/agent_run_stop.rb +21 -0
- data/lib/exa/services/agent_run_stream.rb +53 -51
- data/lib/exa/services/answer.rb +5 -2
- data/lib/exa/services/answer_stream.rb +54 -45
- data/lib/exa/services/context.rb +3 -1
- data/lib/exa/services/find_similar.rb +9 -2
- data/lib/exa/services/get_contents.rb +14 -15
- data/lib/exa/services/parameter_converter.rb +128 -111
- data/lib/exa/services/search.rb +58 -19
- data/lib/exa/services/search_monitors/batch.rb +36 -0
- data/lib/exa/services/search_monitors/create.rb +37 -0
- data/lib/exa/services/search_monitors/delete.rb +22 -0
- data/lib/exa/services/search_monitors/get.rb +22 -0
- data/lib/exa/services/search_monitors/list.rb +29 -0
- data/lib/exa/services/search_monitors/runs_get.rb +23 -0
- data/lib/exa/services/search_monitors/runs_list.rb +29 -0
- data/lib/exa/services/search_monitors/trigger.rb +22 -0
- data/lib/exa/services/search_monitors/update.rb +42 -0
- data/lib/exa/services/search_stream.rb +38 -0
- data/lib/exa/version.rb +1 -1
- data/lib/exa.rb +18 -50
- metadata +30 -84
- data/exe/exa-ai-enrichment-cancel +0 -108
- data/exe/exa-ai-enrichment-create +0 -226
- data/exe/exa-ai-enrichment-delete +0 -122
- data/exe/exa-ai-enrichment-get +0 -104
- data/exe/exa-ai-enrichment-list +0 -99
- data/exe/exa-ai-enrichment-update +0 -171
- data/exe/exa-ai-import-create +0 -253
- data/exe/exa-ai-import-delete +0 -92
- data/exe/exa-ai-import-get +0 -92
- data/exe/exa-ai-import-list +0 -72
- data/exe/exa-ai-import-update +0 -164
- data/exe/exa-ai-monitor-create +0 -223
- data/exe/exa-ai-monitor-delete +0 -101
- data/exe/exa-ai-monitor-get +0 -92
- data/exe/exa-ai-monitor-list +0 -90
- data/exe/exa-ai-monitor-runs-get +0 -103
- data/exe/exa-ai-monitor-runs-list +0 -110
- data/exe/exa-ai-monitor-update +0 -207
- data/exe/exa-ai-webset-cancel +0 -97
- data/exe/exa-ai-webset-create +0 -254
- data/exe/exa-ai-webset-delete +0 -111
- data/exe/exa-ai-webset-get +0 -93
- data/exe/exa-ai-webset-item-delete +0 -111
- data/exe/exa-ai-webset-item-get +0 -105
- data/exe/exa-ai-webset-item-list +0 -108
- data/exe/exa-ai-webset-list +0 -91
- data/exe/exa-ai-webset-search-cancel +0 -104
- data/exe/exa-ai-webset-search-create +0 -247
- data/exe/exa-ai-webset-search-get +0 -105
- data/exe/exa-ai-webset-update +0 -143
- data/lib/exa/cli/formatters/enrichment_formatter.rb +0 -125
- data/lib/exa/cli/formatters/import_formatter.rb +0 -153
- data/lib/exa/cli/formatters/monitor_formatter.rb +0 -144
- data/lib/exa/cli/formatters/monitor_run_formatter.rb +0 -126
- data/lib/exa/cli/formatters/webset_formatter.rb +0 -134
- data/lib/exa/cli/formatters/webset_item_formatter.rb +0 -131
- data/lib/exa/cli/formatters/webset_search_formatter.rb +0 -57
- data/lib/exa/constants/websets.rb +0 -19
- data/lib/exa/resources/import.rb +0 -86
- data/lib/exa/resources/import_collection.rb +0 -33
- data/lib/exa/resources/monitor.rb +0 -48
- data/lib/exa/resources/monitor_collection.rb +0 -30
- data/lib/exa/resources/monitor_run.rb +0 -52
- data/lib/exa/resources/monitor_run_collection.rb +0 -30
- data/lib/exa/resources/webset.rb +0 -74
- data/lib/exa/resources/webset_collection.rb +0 -33
- data/lib/exa/resources/webset_enrichment.rb +0 -71
- data/lib/exa/resources/webset_enrichment_collection.rb +0 -28
- data/lib/exa/resources/webset_item_collection.rb +0 -33
- data/lib/exa/resources/webset_search.rb +0 -112
- data/lib/exa/services/websets/cancel.rb +0 -36
- data/lib/exa/services/websets/cancel_enrichment.rb +0 -35
- data/lib/exa/services/websets/cancel_search.rb +0 -44
- data/lib/exa/services/websets/create.rb +0 -45
- data/lib/exa/services/websets/create_enrichment.rb +0 -35
- data/lib/exa/services/websets/create_search.rb +0 -48
- data/lib/exa/services/websets/create_search_validator.rb +0 -128
- data/lib/exa/services/websets/create_validator.rb +0 -213
- data/lib/exa/services/websets/delete.rb +0 -36
- data/lib/exa/services/websets/delete_enrichment.rb +0 -35
- data/lib/exa/services/websets/delete_item.rb +0 -20
- data/lib/exa/services/websets/get_item.rb +0 -20
- data/lib/exa/services/websets/get_search.rb +0 -43
- data/lib/exa/services/websets/import_create.rb +0 -40
- data/lib/exa/services/websets/import_delete.rb +0 -37
- data/lib/exa/services/websets/import_get.rb +0 -37
- data/lib/exa/services/websets/import_list.rb +0 -25
- data/lib/exa/services/websets/import_update.rb +0 -38
- data/lib/exa/services/websets/import_upload.rb +0 -59
- data/lib/exa/services/websets/list.rb +0 -25
- data/lib/exa/services/websets/list_items.rb +0 -26
- data/lib/exa/services/websets/monitors/create.rb +0 -42
- data/lib/exa/services/websets/monitors/delete.rb +0 -32
- data/lib/exa/services/websets/monitors/get.rb +0 -33
- data/lib/exa/services/websets/monitors/list.rb +0 -27
- data/lib/exa/services/websets/monitors/runs/get.rb +0 -37
- data/lib/exa/services/websets/monitors/runs/list.rb +0 -30
- data/lib/exa/services/websets/monitors/update.rb +0 -33
- data/lib/exa/services/websets/retrieve.rb +0 -47
- data/lib/exa/services/websets/retrieve_enrichment.rb +0 -35
- data/lib/exa/services/websets/update.rb +0 -37
- data/lib/exa/services/websets/update_enrichment.rb +0 -36
- 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(
|
|
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
|
-
#
|
|
23
|
-
|
|
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
|
|
29
|
-
|
|
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
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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
|
-
|
|
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
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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
|
data/lib/exa/services/context.rb
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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
|
-
|
|
19
|
-
|
|
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[
|
|
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] =
|
|
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
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
-
|
|
86
|
-
|
|
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
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
|
100
|
-
case
|
|
101
|
-
when
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
|
137
|
-
|
|
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
|
-
|
|
163
|
-
{
|
|
164
|
-
max_characters: :maxCharacters
|
|
165
|
-
}
|
|
192
|
+
deep_convert(value)
|
|
166
193
|
end
|
|
167
194
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
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
|
data/lib/exa/services/search.rb
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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
|
-
|
|
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
|