Luxe 0.1.3: your sessions on your phone, joinable sessions, and nested AGENTS.md
- luxe remote puts the sessions on your computer in reach of your own phone or tablet over Tailscale: write, steer, answer prompts, send photos, browse files, diffs and GitHub, with a paired device and your own Tailscale login. - luxe join lets another program on the same machine join a running session over the RPC protocol. - An AGENTS.md in a subfolder reaches the model the first time it works there. - Long sessions stay fast: no stall before each model call, lighter memory, cheaper drawing. - A session is open in one Luxe at a time, web_search shares results across its phrasings, and a grep glob starting with ! excludes. The CHANGELOG has the full list.
This commit is contained in:
@@ -6,11 +6,10 @@
|
||||
//! `EXA_API_KEY` still wins, since an explicit choice outranks the fallback, but having none does
|
||||
//! not mean having no web search.
|
||||
//!
|
||||
//! The endpoint also carries the whole feature set worth having: several query variations in one
|
||||
//! call, domain include/exclude, a published-after date, and extracted highlights. That last one is
|
||||
//! the point. Returning titles and snippets forces the model into one `web_fetch` per result — a
|
||||
//! research question becomes six round-trips. Returning the passages *with* the results answers it
|
||||
//! in one.
|
||||
//! The endpoint also carries the whole feature set worth having: domain include/exclude, a
|
||||
//! published-after date, and extracted highlights. That last one is the point. Returning titles
|
||||
//! and snippets forces the model into one `web_fetch` per result — a research question becomes six
|
||||
//! round-trips. Returning the passages *with* the results answers it in one.
|
||||
|
||||
use serde::Deserialize;
|
||||
|
||||
@@ -98,9 +97,8 @@ impl SearchBackend for ExaMcpBackend {
|
||||
self.search_with(query, n, options).await
|
||||
}
|
||||
|
||||
/// Exa's advanced tool takes every phrasing as one call, which is the whole reason it is the
|
||||
/// default: one round-trip covers the angles a caller would otherwise pay for separately.
|
||||
fn batches_queries(&self) -> bool {
|
||||
/// The keyless endpoint turns away even two searches at once.
|
||||
fn one_phrasing_at_a_time(&self) -> bool {
|
||||
true
|
||||
}
|
||||
}
|
||||
@@ -113,9 +111,6 @@ fn build_arguments(query: &str, n: usize, options: &SearchOptions) -> serde_json
|
||||
"type": "auto",
|
||||
});
|
||||
let map = arguments.as_object_mut().expect("object literal");
|
||||
if !options.also.is_empty() {
|
||||
map.insert("additionalQueries".into(), serde_json::json!(options.also));
|
||||
}
|
||||
if !options.include_domains.is_empty() {
|
||||
map.insert("includeDomains".into(), serde_json::json!(options.include_domains));
|
||||
}
|
||||
@@ -147,6 +142,16 @@ struct RpcResult {
|
||||
content: Vec<RpcContent>,
|
||||
#[serde(default, rename = "isError")]
|
||||
is_error: bool,
|
||||
#[serde(default, rename = "_meta")]
|
||||
meta: RpcMeta,
|
||||
}
|
||||
|
||||
/// Flags the endpoint sets beside a result.
|
||||
#[derive(Debug, Default, Deserialize)]
|
||||
struct RpcMeta {
|
||||
/// Set on the reply to a search over the keyless limit, which carries a notice, not results
|
||||
#[serde(default, rename = "ai.exa/rateLimited")]
|
||||
rate_limited: bool,
|
||||
}
|
||||
|
||||
#[derive(Debug, Deserialize)]
|
||||
@@ -173,6 +178,11 @@ fn parse_response(body: &str, n: usize) -> Result<Vec<SearchHit>, WebError> {
|
||||
let result = envelope
|
||||
.result
|
||||
.ok_or_else(|| WebError::Backend("exa mcp returned no result".to_string()))?;
|
||||
if result.meta.rate_limited {
|
||||
return Err(WebError::Backend(
|
||||
"exa's free search is rate limited; try again shortly, or set EXA_API_KEY".to_string(),
|
||||
));
|
||||
}
|
||||
if result.is_error {
|
||||
let detail = result.content.first().map(|c| c.text.as_str()).unwrap_or("unknown error");
|
||||
return Err(WebError::Backend(format!("exa mcp: {detail}")));
|
||||
@@ -291,150 +301,4 @@ fn flush(hits: &mut [SearchHit], snippet: &mut String) {
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
/// The exact shape the live endpoint returned during development.
|
||||
const SAMPLE: &str = "event: message\n\
|
||||
data: {\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"Title: select in tokio - Rust\\nURL: https://docs.rs/tokio/latest/tokio/macro.select.html\\nPublished: N/A\\nAuthor: N/A\\nHighlights:\\n## Cancellation safety\\n...\\nCancellation safety describes what happens when a future is dropped.\\nTitle: Second Result\\nURL: https://example.com/two\\nHighlights:\\nSomething else entirely.\"}]}}\n";
|
||||
|
||||
#[test]
|
||||
fn an_sse_framed_response_parses_into_hits_with_content() {
|
||||
let hits = parse_response(SAMPLE, 10).expect("parses");
|
||||
assert_eq!(hits.len(), 2);
|
||||
assert_eq!(hits[0].title, "select in tokio - Rust");
|
||||
assert_eq!(hits[0].url, "https://docs.rs/tokio/latest/tokio/macro.select.html");
|
||||
assert!(
|
||||
hits[0].snippet.contains("Cancellation safety describes"),
|
||||
"the extracted passage rides along, so no follow-up fetch is needed: {:?}",
|
||||
hits[0].snippet
|
||||
);
|
||||
assert!(!hits[0].snippet.contains("N/A"), "metadata noise is dropped");
|
||||
assert_eq!(hits[1].url, "https://example.com/two");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_result_count_is_honored() {
|
||||
assert_eq!(parse_response(SAMPLE, 1).expect("parses").len(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_bare_json_body_parses_too() {
|
||||
let bare =
|
||||
r#"{"result":{"content":[{"type":"text","text":"Title: A\nURL: https://a.test"}]}}"#;
|
||||
assert_eq!(parse_response(bare, 5).expect("parses")[0].url, "https://a.test");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_rpc_error_surfaces_instead_of_an_empty_result() {
|
||||
let body = r#"{"error":{"code":-32602,"message":"bad arguments"}}"#;
|
||||
let error = parse_response(body, 5).expect_err("must not look like zero results");
|
||||
assert!(error.to_string().contains("bad arguments"), "{error}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_tool_level_error_surfaces_too() {
|
||||
let body =
|
||||
r#"{"result":{"isError":true,"content":[{"type":"text","text":"rate limited"}]}}"#;
|
||||
let error = parse_response(body, 5).expect_err("isError must not be silently empty");
|
||||
assert!(error.to_string().contains("rate limited"), "{error}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn garbage_is_an_error_not_a_panic() {
|
||||
assert!(parse_response("not json at all", 5).is_err());
|
||||
assert!(parse_response("", 5).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn options_map_onto_exas_argument_names() {
|
||||
let options = SearchOptions {
|
||||
also: vec!["second phrasing".into()],
|
||||
include_domains: vec!["arxiv.org".into()],
|
||||
exclude_domains: vec!["spam.example".into()],
|
||||
recency: Some(crate::web::Recency::Month),
|
||||
include_content: true,
|
||||
};
|
||||
let args = build_arguments("tokio cancellation", 7, &options);
|
||||
|
||||
assert_eq!(args["query"], "tokio cancellation");
|
||||
assert_eq!(args["numResults"], 7);
|
||||
assert_eq!(args["additionalQueries"][0], "second phrasing");
|
||||
assert_eq!(args["includeDomains"][0], "arxiv.org");
|
||||
assert_eq!(args["excludeDomains"][0], "spam.example");
|
||||
assert_eq!(args["startPublishedDate"].as_str().expect("a date").len(), 10);
|
||||
assert_eq!(args["enableHighlights"], true);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn defaults_stay_off_the_wire_and_the_count_is_clamped() {
|
||||
let args = build_arguments("q", 999, &SearchOptions::default());
|
||||
assert_eq!(args["numResults"], 25, "clamped to Exa's practical ceiling");
|
||||
for absent in [
|
||||
"additionalQueries",
|
||||
"includeDomains",
|
||||
"excludeDomains",
|
||||
"startPublishedDate",
|
||||
"enableHighlights",
|
||||
] {
|
||||
assert!(args.get(absent).is_none(), "{absent} must not be sent by default");
|
||||
}
|
||||
}
|
||||
|
||||
/// The advanced tool answers with a JSON envelope, not the basic tool's prose. Parsing only the
|
||||
/// prose form meant every advanced search reported "No results" while the endpoint was
|
||||
/// returning perfectly good ones.
|
||||
#[test]
|
||||
fn the_advanced_tools_json_envelope_parses() {
|
||||
let inner = serde_json::json!({
|
||||
"requestId": "abc",
|
||||
"results": [
|
||||
{
|
||||
"id": "https://tokio.rs/x",
|
||||
"url": "https://tokio.rs/x",
|
||||
"title": "Select | Tokio",
|
||||
"text": "Select | Tokio\n\n# Select\n\nSo far...",
|
||||
"highlights": ["Futures can implement Drop to clean up.", "oneshot is cancel safe."],
|
||||
"publishedDate": "2026-03-18T00:00:00.000Z"
|
||||
},
|
||||
{ "url": "", "title": "dropped: no url" }
|
||||
]
|
||||
})
|
||||
.to_string();
|
||||
let body = serde_json::json!({
|
||||
"result": { "content": [{ "type": "text", "text": inner }] }
|
||||
})
|
||||
.to_string();
|
||||
|
||||
let hits = parse_response(&body, 10).expect("parses");
|
||||
assert_eq!(hits.len(), 1, "a result with no url is not a result");
|
||||
assert_eq!(hits[0].title, "Select | Tokio");
|
||||
assert_eq!(hits[0].url, "https://tokio.rs/x");
|
||||
assert!(hits[0].snippet.contains("cancel safe"), "highlights lead: {:?}", hits[0].snippet);
|
||||
assert!(!hits[0].snippet.contains('\n'), "whitespace is collapsed");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_result_without_highlights_falls_back_to_its_text() {
|
||||
let inner = serde_json::json!({
|
||||
"results": [{ "url": "https://a.test", "title": "A", "text": " body text here " }]
|
||||
})
|
||||
.to_string();
|
||||
let body = serde_json::json!({ "result": { "content": [{ "text": inner }] } }).to_string();
|
||||
let hits = parse_response(&body, 5).expect("parses");
|
||||
assert_eq!(hits[0].snippet, "body text here");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_long_snippet_is_clipped() {
|
||||
let long = "word ".repeat(400);
|
||||
let inner = serde_json::json!({
|
||||
"results": [{ "url": "https://a.test", "title": "A", "text": long }]
|
||||
})
|
||||
.to_string();
|
||||
let body = serde_json::json!({ "result": { "content": [{ "text": inner }] } }).to_string();
|
||||
let hits = parse_response(&body, 5).expect("parses");
|
||||
assert!(hits[0].snippet.chars().count() <= SNIPPET_CHARS + 1, "clipped");
|
||||
assert!(hits[0].snippet.ends_with('…'));
|
||||
}
|
||||
}
|
||||
mod tests;
|
||||
|
||||
152
crates/luxe-tools/src/exa_mcp/tests.rs
Normal file
152
crates/luxe-tools/src/exa_mcp/tests.rs
Normal file
@@ -0,0 +1,152 @@
|
||||
use super::*;
|
||||
|
||||
/// The exact shape the live endpoint returned during development.
|
||||
const SAMPLE: &str = "event: message\n\
|
||||
data: {\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"Title: select in tokio - Rust\\nURL: https://docs.rs/tokio/latest/tokio/macro.select.html\\nPublished: N/A\\nAuthor: N/A\\nHighlights:\\n## Cancellation safety\\n...\\nCancellation safety describes what happens when a future is dropped.\\nTitle: Second Result\\nURL: https://example.com/two\\nHighlights:\\nSomething else entirely.\"}]}}\n";
|
||||
|
||||
/// A burst of searches crossed the keyless limit; this is the reply, copied from the endpoint.
|
||||
const RATE_LIMITED: &str = "event: message\ndata: {\"result\":{\"_meta\":{\"ai.exa/rateLimited\":true},\"content\":[{\"type\":\"text\",\"text\":\"You've hit Exa's free MCP rate limit. To continue using without limits, create your own Exa API key.\\n\\nFix: Create API key at https://dashboard.exa.ai/api-keys , and then update Exa MCP URL to this https://mcp.exa.ai/mcp?exaApiKey=YOUR_EXA_API_KEY\"}]},\"jsonrpc\":\"2.0\",\"id\":1}\n";
|
||||
|
||||
#[test]
|
||||
fn an_sse_framed_response_parses_into_hits_with_content() {
|
||||
let hits = parse_response(SAMPLE, 10).expect("parses");
|
||||
assert_eq!(hits.len(), 2);
|
||||
assert_eq!(hits[0].title, "select in tokio - Rust");
|
||||
assert_eq!(hits[0].url, "https://docs.rs/tokio/latest/tokio/macro.select.html");
|
||||
assert!(
|
||||
hits[0].snippet.contains("Cancellation safety describes"),
|
||||
"the extracted passage rides along, so no follow-up fetch is needed: {:?}",
|
||||
hits[0].snippet
|
||||
);
|
||||
assert!(!hits[0].snippet.contains("N/A"), "metadata noise is dropped");
|
||||
assert_eq!(hits[1].url, "https://example.com/two");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_result_count_is_honored() {
|
||||
assert_eq!(parse_response(SAMPLE, 1).expect("parses").len(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_bare_json_body_parses_too() {
|
||||
let bare = r#"{"result":{"content":[{"type":"text","text":"Title: A\nURL: https://a.test"}]}}"#;
|
||||
assert_eq!(parse_response(bare, 5).expect("parses")[0].url, "https://a.test");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_rpc_error_surfaces_instead_of_an_empty_result() {
|
||||
let body = r#"{"error":{"code":-32602,"message":"bad arguments"}}"#;
|
||||
let error = parse_response(body, 5).expect_err("must not look like zero results");
|
||||
assert!(error.to_string().contains("bad arguments"), "{error}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_tool_level_error_surfaces_too() {
|
||||
let body = r#"{"result":{"isError":true,"content":[{"type":"text","text":"rate limited"}]}}"#;
|
||||
let error = parse_response(body, 5).expect_err("isError must not be silently empty");
|
||||
assert!(error.to_string().contains("rate limited"), "{error}");
|
||||
}
|
||||
|
||||
/// The break this catches: a rate-limited reply, which isn't flagged as an error, reading as a
|
||||
/// search that found nothing, so the model gave up on a question the web could answer.
|
||||
#[test]
|
||||
fn a_rate_limited_reply_is_an_error_not_zero_results() {
|
||||
let error = parse_response(RATE_LIMITED, 5).expect_err("rate limited is not empty");
|
||||
assert!(error.to_string().contains("rate limit"), "{error}");
|
||||
assert!(error.to_string().contains("EXA_API_KEY"), "says how to lift it: {error}");
|
||||
}
|
||||
|
||||
/// The break this catches: the keyless endpoint getting a search's phrasings all at once, which
|
||||
/// crosses its limit and turns all but one of them away.
|
||||
#[test]
|
||||
fn the_keyless_endpoint_gets_one_phrasing_at_a_time() {
|
||||
assert!(ExaMcpBackend::new().one_phrasing_at_a_time());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn garbage_is_an_error_not_a_panic() {
|
||||
assert!(parse_response("not json at all", 5).is_err());
|
||||
assert!(parse_response("", 5).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn options_map_onto_exas_argument_names() {
|
||||
let options = SearchOptions {
|
||||
include_domains: vec!["arxiv.org".into()],
|
||||
exclude_domains: vec!["spam.example".into()],
|
||||
recency: Some(crate::web::Recency::Month),
|
||||
include_content: true,
|
||||
};
|
||||
let args = build_arguments("tokio cancellation", 7, &options);
|
||||
|
||||
assert_eq!(args["query"], "tokio cancellation");
|
||||
assert_eq!(args["numResults"], 7);
|
||||
assert_eq!(args["highlightsQuery"], "tokio cancellation", "passages for this phrasing");
|
||||
assert_eq!(args["includeDomains"][0], "arxiv.org");
|
||||
assert_eq!(args["excludeDomains"][0], "spam.example");
|
||||
assert_eq!(args["startPublishedDate"].as_str().expect("a date").len(), 10);
|
||||
assert_eq!(args["enableHighlights"], true);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn defaults_stay_off_the_wire_and_the_count_is_clamped() {
|
||||
let args = build_arguments("q", 999, &SearchOptions::default());
|
||||
assert_eq!(args["numResults"], 25, "clamped to Exa's practical ceiling");
|
||||
for absent in ["includeDomains", "excludeDomains", "startPublishedDate", "enableHighlights"] {
|
||||
assert!(args.get(absent).is_none(), "{absent} must not be sent by default");
|
||||
}
|
||||
}
|
||||
|
||||
/// The advanced tool answers with a JSON envelope, not the basic tool's prose. Parsing only the
|
||||
/// prose form meant every advanced search reported "No results" while the endpoint was returning
|
||||
/// perfectly good ones.
|
||||
#[test]
|
||||
fn the_advanced_tools_json_envelope_parses() {
|
||||
let inner = serde_json::json!({
|
||||
"requestId": "abc",
|
||||
"results": [
|
||||
{
|
||||
"id": "https://tokio.rs/x",
|
||||
"url": "https://tokio.rs/x",
|
||||
"title": "Select | Tokio",
|
||||
"text": "Select | Tokio\n\n# Select\n\nSo far...",
|
||||
"highlights": ["Futures can implement Drop to clean up.", "oneshot is cancel safe."],
|
||||
"publishedDate": "2026-03-18T00:00:00.000Z"
|
||||
},
|
||||
{ "url": "", "title": "dropped: no url" }
|
||||
]
|
||||
})
|
||||
.to_string();
|
||||
let body = serde_json::json!({ "result": { "content": [{ "type": "text", "text": inner }] } })
|
||||
.to_string();
|
||||
|
||||
let hits = parse_response(&body, 10).expect("parses");
|
||||
assert_eq!(hits.len(), 1, "a result with no url is not a result");
|
||||
assert_eq!(hits[0].title, "Select | Tokio");
|
||||
assert_eq!(hits[0].url, "https://tokio.rs/x");
|
||||
assert!(hits[0].snippet.contains("cancel safe"), "highlights lead: {:?}", hits[0].snippet);
|
||||
assert!(!hits[0].snippet.contains('\n'), "whitespace is collapsed");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_result_without_highlights_falls_back_to_its_text() {
|
||||
let inner = serde_json::json!({
|
||||
"results": [{ "url": "https://a.test", "title": "A", "text": " body text here " }]
|
||||
})
|
||||
.to_string();
|
||||
let body = serde_json::json!({ "result": { "content": [{ "text": inner }] } }).to_string();
|
||||
let hits = parse_response(&body, 5).expect("parses");
|
||||
assert_eq!(hits[0].snippet, "body text here");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_long_snippet_is_clipped() {
|
||||
let long = "word ".repeat(400);
|
||||
let inner =
|
||||
serde_json::json!({ "results": [{ "url": "https://a.test", "title": "A", "text": long }] })
|
||||
.to_string();
|
||||
let body = serde_json::json!({ "result": { "content": [{ "text": inner }] } }).to_string();
|
||||
let hits = parse_response(&body, 5).expect("parses");
|
||||
assert!(hits[0].snippet.chars().count() <= SNIPPET_CHARS + 1, "clipped");
|
||||
assert!(hits[0].snippet.ends_with('…'));
|
||||
}
|
||||
@@ -52,7 +52,7 @@ fn grep_schema() -> ToolSchema {
|
||||
},
|
||||
"glob": {
|
||||
"type": "string",
|
||||
"description": "Glob pattern to filter files (e.g., '*.rs')"
|
||||
"description": "Glob pattern to filter files (e.g., '*.rs'); a leading '!' excludes (e.g., '!tests/**')"
|
||||
},
|
||||
"outputMode": {
|
||||
"type": "string",
|
||||
|
||||
@@ -76,6 +76,18 @@ fn the_native_search_honors_ignores_and_reports_ripgrep_shaped_rows() {
|
||||
assert!(native_search(cwd, &search("no_such_text")).expect("valid").is_empty());
|
||||
}
|
||||
|
||||
/// A glob that starts with `!` leaves out what it names and searches the rest.
|
||||
///
|
||||
/// The break this catches: `!` taken literally, so an exclude glob matched no file and the
|
||||
/// search came back empty.
|
||||
#[test]
|
||||
fn an_exclude_glob_searches_everything_else() {
|
||||
let dir = repo_with_build_output();
|
||||
let excluding = Search { glob: Some("!target/**"), all: true, ..search("needle") };
|
||||
let rows = native_search(dir.path(), &excluding).expect("a valid regex");
|
||||
assert_eq!(rows, vec!["src/main.rs:1:let needle = 1;"]);
|
||||
}
|
||||
|
||||
/// Context lines use `-` where a match uses `:`, the way ripgrep prints them, so a reader (and
|
||||
/// the model) can tell the answer from its surroundings.
|
||||
#[test]
|
||||
|
||||
@@ -174,6 +174,7 @@ impl Tool for QuestionTool {
|
||||
QuestionReply::Cancelled
|
||||
}
|
||||
};
|
||||
let _ = cx.event_tx.send(Event::PromptClosed { id: id.as_str().to_string() }).await;
|
||||
|
||||
let outcome = match reply {
|
||||
QuestionReply::Answered(answers) => QuestionOutcome::Answered(answers),
|
||||
|
||||
@@ -89,6 +89,9 @@ async fn interactive_question_emits_event_and_awaits_the_brokered_answer() {
|
||||
assert!(!result.is_error);
|
||||
let ContentBlock::Text(text) = &result.content[0] else { panic!("expected text") };
|
||||
assert!(text.contains("The user answered: Rust"), "got: {text}");
|
||||
// Any other front-end showing the question is told to take it down
|
||||
let closed = event_rx.recv().await;
|
||||
assert_eq!(closed, Some(Event::PromptClosed { id: id.as_str().to_string() }));
|
||||
}
|
||||
|
||||
/// A multi-select answer reaches the model as a list, and comes back off the text as the same
|
||||
|
||||
@@ -129,7 +129,6 @@ mod tests {
|
||||
exclude_domains: vec!["reddit.com".to_string()],
|
||||
recency: Some(crate::web::Recency::Year),
|
||||
include_content: true,
|
||||
..Default::default()
|
||||
});
|
||||
assert_eq!(body["query"], "tokio");
|
||||
assert_eq!(body["max_results"], 3);
|
||||
|
||||
@@ -26,9 +26,9 @@ pub trait SearchBackend: Send + Sync {
|
||||
Vec::new()
|
||||
}
|
||||
|
||||
/// Whether one call covers every phrasing in [`SearchOptions::also`]. A plain search API does
|
||||
/// not, so the caller runs them itself and merges.
|
||||
fn batches_queries(&self) -> bool {
|
||||
/// Whether a search's phrasings must run one after another. A rate-limited endpoint turns a
|
||||
/// burst away, so its phrasings wait their turn instead of failing together.
|
||||
fn one_phrasing_at_a_time(&self) -> bool {
|
||||
false
|
||||
}
|
||||
}
|
||||
@@ -112,8 +112,6 @@ impl Recency {
|
||||
/// exposed all of them would cost more context than the answers it fetches.
|
||||
#[derive(Debug, Clone, Default)]
|
||||
pub struct SearchOptions {
|
||||
/// Extra query phrasings run alongside the main one, widening coverage in a single call.
|
||||
pub also: Vec<String>,
|
||||
/// Only these domains.
|
||||
pub include_domains: Vec<String>,
|
||||
/// Never these domains.
|
||||
@@ -170,48 +168,82 @@ pub async fn create_backend(config: &WebConfig) -> Result<Box<dyn SearchBackend>
|
||||
}
|
||||
}
|
||||
|
||||
/// What a search found, and a note for each phrasing that failed.
|
||||
#[derive(Debug)]
|
||||
pub(super) struct Searched {
|
||||
pub(super) hits: Vec<SearchHit>,
|
||||
pub(super) skipped: Vec<String>,
|
||||
}
|
||||
|
||||
/// Run every phrasing the caller asked for and merge the results.
|
||||
///
|
||||
/// One call per query for a backend that takes one query, first-seen order preserved and duplicate
|
||||
/// URLs dropped — the same page found by two phrasings is one result, and the earlier phrasing is
|
||||
/// the one that ranked it. A phrasing that errors is skipped rather than sinking the whole search;
|
||||
/// the error only surfaces when *nothing* answered.
|
||||
/// Each phrasing is its own search, so each gets its own ranking and its own passages; one call
|
||||
/// carrying the extras ranks everything against the first. A phrasing that errors is skipped and
|
||||
/// named rather than sinking the whole search; the error only fails it when *nothing* answered.
|
||||
pub(super) async fn run_search(
|
||||
backend: &dyn SearchBackend,
|
||||
queries: &[String],
|
||||
n: usize,
|
||||
options: &SearchOptions,
|
||||
) -> Result<Vec<SearchHit>, WebError> {
|
||||
let Some((query, also)) = queries.split_first() else {
|
||||
return Ok(Vec::new());
|
||||
};
|
||||
if backend.batches_queries() || also.is_empty() {
|
||||
return backend.search(query, n, options).await;
|
||||
}
|
||||
|
||||
// The extras are already in `queries`; passing them again would double a backend that reads
|
||||
// both. One phrasing at a time, and the option set minus the fan-out it has already served.
|
||||
let single = SearchOptions { also: Vec::new(), ..options.clone() };
|
||||
let mut merged: Vec<SearchHit> = Vec::new();
|
||||
) -> Result<Searched, WebError> {
|
||||
let mut lists = Vec::new();
|
||||
let mut skipped = Vec::new();
|
||||
let mut last_error = None;
|
||||
for query in queries {
|
||||
match backend.search(query, n, &single).await {
|
||||
Ok(hits) => {
|
||||
for hit in hits {
|
||||
if !merged.iter().any(|seen| seen.url == hit.url) {
|
||||
merged.push(hit);
|
||||
}
|
||||
}
|
||||
for (query, answer) in queries.iter().zip(search_each(backend, queries, n, options).await) {
|
||||
match answer {
|
||||
Ok(hits) => lists.push(hits),
|
||||
Err(error) => {
|
||||
skipped.push(format!("\"{query}\" wasn't searched: {error}"));
|
||||
last_error = Some(error);
|
||||
}
|
||||
Err(error) => last_error = Some(error),
|
||||
}
|
||||
}
|
||||
match (merged.is_empty(), last_error) {
|
||||
let hits = interleave(lists, n);
|
||||
match (hits.is_empty(), last_error) {
|
||||
(true, Some(error)) => Err(error),
|
||||
_ => Ok(merged),
|
||||
_ => Ok(Searched { hits, skipped }),
|
||||
}
|
||||
}
|
||||
|
||||
/// Each phrasing's answer, in order: all at once, or in turn where the backend needs that.
|
||||
async fn search_each(
|
||||
backend: &dyn SearchBackend,
|
||||
queries: &[String],
|
||||
n: usize,
|
||||
options: &SearchOptions,
|
||||
) -> Vec<Result<Vec<SearchHit>, WebError>> {
|
||||
if !backend.one_phrasing_at_a_time() {
|
||||
let searches = queries.iter().map(|query| backend.search(query, n, options));
|
||||
return futures::future::join_all(searches).await;
|
||||
}
|
||||
let mut answers = Vec::with_capacity(queries.len());
|
||||
for query in queries {
|
||||
answers.push(backend.search(query, n, options).await);
|
||||
}
|
||||
answers
|
||||
}
|
||||
|
||||
/// Up to `n` hits, rank by rank: the top of each list, then the next of each.
|
||||
///
|
||||
/// So every phrasing is represented. A page two phrasings found is one result, at its first
|
||||
/// position, and its second slot goes to the next page.
|
||||
fn interleave(lists: Vec<Vec<SearchHit>>, n: usize) -> Vec<SearchHit> {
|
||||
let mut lists: Vec<_> = lists.into_iter().map(Vec::into_iter).collect();
|
||||
let mut merged: Vec<SearchHit> = Vec::new();
|
||||
while merged.len() < n {
|
||||
let rank: Vec<SearchHit> = lists.iter_mut().filter_map(Iterator::next).collect();
|
||||
if rank.is_empty() {
|
||||
break;
|
||||
}
|
||||
for hit in rank {
|
||||
if merged.len() < n && !merged.iter().any(|seen| seen.url == hit.url) {
|
||||
merged.push(hit);
|
||||
}
|
||||
}
|
||||
}
|
||||
merged
|
||||
}
|
||||
|
||||
/// web_search tool — pluggable search backend.
|
||||
pub struct WebSearchTool {
|
||||
pub(super) config: Arc<RwLock<WebConfig>>,
|
||||
@@ -272,14 +304,13 @@ impl Tool for WebSearchTool {
|
||||
|
||||
async fn run(&self, args: serde_json::Value, _cx: &ToolContext) -> ToolResultData {
|
||||
let queries = search_queries(&args);
|
||||
let Some((_, also)) = queries.split_first() else {
|
||||
if queries.is_empty() {
|
||||
return ToolResultData::error("Error: 'query' (or 'queries') is required");
|
||||
};
|
||||
}
|
||||
|
||||
let n = (args.get("n").and_then(serde_json::Value::as_u64).unwrap_or(5) as usize)
|
||||
.clamp(1, MAX_RESULTS);
|
||||
let options = SearchOptions {
|
||||
also: also.to_vec(),
|
||||
include_content: args
|
||||
.get("content")
|
||||
.and_then(serde_json::Value::as_bool)
|
||||
@@ -297,8 +328,10 @@ impl Tool for WebSearchTool {
|
||||
Err(e) => return ToolResultData::error(format!("Backend error: {e}")),
|
||||
};
|
||||
match run_search(backend.as_ref(), &queries, n, &options).await {
|
||||
Ok(hits) => {
|
||||
ToolResultData::text(render_hits(&queries, &hits, &backend.honors(&options)))
|
||||
Ok(searched) => {
|
||||
let mut caveats = backend.honors(&options);
|
||||
caveats.extend(searched.skipped);
|
||||
ToolResultData::text(render_hits(&queries, &searched.hits, &caveats))
|
||||
}
|
||||
Err(e) => ToolResultData::error(format!("Search failed: {e}")),
|
||||
}
|
||||
@@ -336,3 +369,6 @@ pub(super) fn domain_filters(args: &serde_json::Value) -> SearchOptions {
|
||||
}
|
||||
options
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests;
|
||||
|
||||
142
crates/luxe-tools/src/web/search/tests.rs
Normal file
142
crates/luxe-tools/src/web/search/tests.rs
Normal file
@@ -0,0 +1,142 @@
|
||||
use super::*;
|
||||
use std::collections::HashMap;
|
||||
use std::sync::atomic::{AtomicUsize, Ordering};
|
||||
use std::sync::Mutex;
|
||||
|
||||
/// A backend with a result list per phrasing, which fails the phrasings it has no list for and
|
||||
/// keeps what it was asked and how many searches it ran at once.
|
||||
struct ByPhrasing {
|
||||
lists: HashMap<&'static str, Vec<&'static str>>,
|
||||
asked: Mutex<Vec<(String, usize)>>,
|
||||
in_turn: bool,
|
||||
running: AtomicUsize,
|
||||
most_at_once: AtomicUsize,
|
||||
}
|
||||
|
||||
impl ByPhrasing {
|
||||
fn new(lists: &[(&'static str, &[&'static str])]) -> Self {
|
||||
let lists = lists.iter().map(|(query, urls)| (*query, urls.to_vec())).collect();
|
||||
let (running, most_at_once) = (AtomicUsize::new(0), AtomicUsize::new(0));
|
||||
Self { lists, asked: Mutex::new(Vec::new()), in_turn: false, running, most_at_once }
|
||||
}
|
||||
|
||||
fn in_turn(self) -> Self {
|
||||
Self { in_turn: true, ..self }
|
||||
}
|
||||
|
||||
/// Holds a search open long enough for another to start beside it, if one is going to.
|
||||
async fn overlap(&self) {
|
||||
let now = self.running.fetch_add(1, Ordering::SeqCst) + 1;
|
||||
self.most_at_once.fetch_max(now, Ordering::SeqCst);
|
||||
tokio::time::sleep(std::time::Duration::from_millis(20)).await;
|
||||
self.running.fetch_sub(1, Ordering::SeqCst);
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl SearchBackend for ByPhrasing {
|
||||
async fn search(
|
||||
&self,
|
||||
query: &str,
|
||||
n: usize,
|
||||
_options: &SearchOptions,
|
||||
) -> Result<Vec<SearchHit>, WebError> {
|
||||
self.asked.lock().expect("no panic holds this lock").push((query.to_string(), n));
|
||||
self.overlap().await;
|
||||
let Some(urls) = self.lists.get(query) else {
|
||||
return Err(WebError::Backend(format!("no answer for {query}")));
|
||||
};
|
||||
Ok(urls.iter().take(n).map(|url| hit(url)).collect())
|
||||
}
|
||||
|
||||
fn one_phrasing_at_a_time(&self) -> bool {
|
||||
self.in_turn
|
||||
}
|
||||
}
|
||||
|
||||
fn hit(url: &str) -> SearchHit {
|
||||
SearchHit { title: url.to_string(), url: url.to_string(), snippet: String::new() }
|
||||
}
|
||||
|
||||
fn queries(list: &[&str]) -> Vec<String> {
|
||||
list.iter().map(|query| query.to_string()).collect()
|
||||
}
|
||||
|
||||
async fn searched(backend: &ByPhrasing, asked: &[&str], n: usize) -> Searched {
|
||||
let answer = run_search(backend, &queries(asked), n, &SearchOptions::default()).await;
|
||||
answer.expect("a phrasing answered")
|
||||
}
|
||||
|
||||
async fn urls(backend: &ByPhrasing, asked: &[&str], n: usize) -> Vec<String> {
|
||||
searched(backend, asked, n).await.hits.into_iter().map(|hit| hit.url).collect()
|
||||
}
|
||||
|
||||
/// Every phrasing gets its share of the results: the top of each, then the next of each.
|
||||
///
|
||||
/// The break this catches: the first phrasing's results filling every slot, so the other
|
||||
/// phrasings were searched and then thrown away.
|
||||
#[tokio::test]
|
||||
async fn each_phrasing_gets_its_share_of_the_results() {
|
||||
let backend = ByPhrasing::new(&[("one", &["a1", "a2", "a3"]), ("two", &["b1", "b2", "b3"])]);
|
||||
assert_eq!(urls(&backend, &["one", "two"], 4).await, ["a1", "b1", "a2", "b2"]);
|
||||
// An odd count stops partway through a rank
|
||||
assert_eq!(urls(&backend, &["one", "two"], 3).await, ["a1", "b1", "a2"]);
|
||||
}
|
||||
|
||||
/// Each phrasing is searched on its own and asked for the full count, so its own ranking and
|
||||
/// passages come back.
|
||||
///
|
||||
/// The break this catches: the extra phrasings riding along on the first one's search, which
|
||||
/// ranks and extracts passages against the first phrasing alone.
|
||||
#[tokio::test]
|
||||
async fn each_phrasing_is_searched_on_its_own() {
|
||||
let backend = ByPhrasing::new(&[("one", &["a1"]), ("two", &["b1"])]);
|
||||
urls(&backend, &["one", "two"], 5).await;
|
||||
let mut asked = backend.asked.lock().expect("no panic holds this lock").clone();
|
||||
asked.sort();
|
||||
assert_eq!(asked, [("one".to_string(), 5), ("two".to_string(), 5)]);
|
||||
}
|
||||
|
||||
/// Phrasings run together unless the backend needs them in turn, and then never overlap.
|
||||
///
|
||||
/// The break this catches: a burst at a rate-limited endpoint, which turned all but one phrasing
|
||||
/// away; or phrasings waiting on each other where nothing needed them to.
|
||||
#[tokio::test]
|
||||
async fn phrasings_wait_their_turn_only_where_the_backend_needs_it() {
|
||||
let lists: &[(&str, &[&str])] = &[("one", &["a1"]), ("two", &["b1"]), ("three", &["c1"])];
|
||||
let together = ByPhrasing::new(lists);
|
||||
urls(&together, &["one", "two", "three"], 5).await;
|
||||
assert_eq!(together.most_at_once.load(Ordering::SeqCst), 3, "all at once");
|
||||
let in_turn = ByPhrasing::new(lists).in_turn();
|
||||
assert_eq!(urls(&in_turn, &["one", "two", "three"], 5).await, ["a1", "b1", "c1"]);
|
||||
assert_eq!(in_turn.most_at_once.load(Ordering::SeqCst), 1, "one at a time");
|
||||
}
|
||||
|
||||
/// A page two phrasings found is one result, and its slot goes to the next page.
|
||||
///
|
||||
/// The break this catches: the same URL listed twice, spending a result on a repeat.
|
||||
#[tokio::test]
|
||||
async fn a_page_found_twice_is_one_result() {
|
||||
let backend = ByPhrasing::new(&[("one", &["same", "a2"]), ("two", &["same", "b2"])]);
|
||||
assert_eq!(urls(&backend, &["one", "two"], 3).await, ["same", "a2", "b2"]);
|
||||
}
|
||||
|
||||
/// A phrasing that fails is skipped and named while another answers; the error only fails the
|
||||
/// search when none did.
|
||||
///
|
||||
/// The break this catches: one failed phrasing sinking a search the others answered, a failure
|
||||
/// the model is never told about, or every phrasing failing and the reply reading as no results.
|
||||
#[tokio::test]
|
||||
async fn a_failed_phrasing_is_named_and_skipped_until_none_answer() {
|
||||
let backend = ByPhrasing::new(&[("works", &["a1"])]);
|
||||
let partial = searched(&backend, &["broken", "works"], 5).await;
|
||||
assert_eq!(partial.hits.len(), 1);
|
||||
assert_eq!(
|
||||
partial.skipped,
|
||||
["\"broken\" wasn't searched: backend error: no answer for broken"]
|
||||
);
|
||||
let broken = queries(&["broken"]);
|
||||
let all_failed = run_search(&backend, &broken, 5, &SearchOptions::default()).await;
|
||||
let error = all_failed.expect_err("nothing answered");
|
||||
assert!(error.to_string().contains("no answer for broken"), "{error}");
|
||||
}
|
||||
Reference in New Issue
Block a user