Explain: shorter answers, streamed, remembered, and prepared for settings
ai-explain spec, amendment 1 (EX-22 to EX-28): - answers are three or four sentences, max_tokens 160, cut at 700 chars; - POST /api/explain streams the answer as server-sent events; - each node remembers answers in memory (1,000, 24 h), keyed by the facts, prompt version and model, shared by server-level administrators; - resources/explain/settings.json.gz ships answers for settings at their defaults, generated with prepare_setting_explanations (717 for 2026.9.27); - the system prompt no longer carries the per-request marker, so a model server can reuse it; - inbuxa:Explanation gains source, answeredAt and preparedFor.
This commit is contained in:
@@ -88,6 +88,7 @@ pub fn body(
|
||||
user: &str,
|
||||
temperature: f64,
|
||||
max_tokens: u32,
|
||||
stream: bool,
|
||||
) -> Value {
|
||||
let temperature = temperature.clamp(0.0, 1.0);
|
||||
match kind {
|
||||
@@ -102,7 +103,7 @@ pub fn body(
|
||||
"messages": messages,
|
||||
"temperature": temperature,
|
||||
"max_tokens": max_tokens,
|
||||
"stream": false,
|
||||
"stream": stream,
|
||||
})
|
||||
}
|
||||
Kind::Text => {
|
||||
@@ -115,7 +116,7 @@ pub fn body(
|
||||
"prompt": prompt,
|
||||
"temperature": temperature,
|
||||
"max_tokens": max_tokens,
|
||||
"stream": false,
|
||||
"stream": stream,
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -138,6 +139,48 @@ pub fn answer(kind: Kind, body: &[u8]) -> Option<String> {
|
||||
(!text.is_empty()).then(|| text.to_string())
|
||||
}
|
||||
|
||||
/// One line of a streamed answer (ai-explain spec, EX-23), as model servers
|
||||
/// send it: server-sent events, one `data:` line per piece.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum StreamLine {
|
||||
/// The next piece of the answer.
|
||||
Delta(String),
|
||||
/// The answer is complete.
|
||||
Done,
|
||||
/// A comment, an empty line, or a piece with no text (a role, a finish
|
||||
/// reason on its own).
|
||||
Ignore,
|
||||
}
|
||||
|
||||
/// Reads one line of a streamed answer: `choices[0].delta.content` for
|
||||
/// chat, `choices[0].text` for text, `[DONE]` at the end.
|
||||
pub fn stream_line(kind: Kind, line: &str) -> StreamLine {
|
||||
let Some(data) = line.trim().strip_prefix("data:") else {
|
||||
return StreamLine::Ignore;
|
||||
};
|
||||
let data = data.trim();
|
||||
if data == "[DONE]" {
|
||||
return StreamLine::Done;
|
||||
}
|
||||
let Ok(value) = serde_json::from_str::<Value>(data) else {
|
||||
return StreamLine::Ignore;
|
||||
};
|
||||
let Some(choice) = value.get("choices").and_then(|c| c.get(0)) else {
|
||||
return StreamLine::Ignore;
|
||||
};
|
||||
let text = match kind {
|
||||
Kind::Chat => choice
|
||||
.get("delta")
|
||||
.and_then(|d| d.get("content"))
|
||||
.and_then(Value::as_str),
|
||||
Kind::Text => choice.get("text").and_then(Value::as_str),
|
||||
};
|
||||
match text {
|
||||
Some(text) if !text.is_empty() => StreamLine::Delta(text.to_string()),
|
||||
_ => StreamLine::Ignore,
|
||||
}
|
||||
}
|
||||
|
||||
/// Cuts an answer or prompt to `max_bytes` on a character boundary.
|
||||
pub fn cut(text: &str, max_bytes: usize) -> String {
|
||||
truncate(text, max_bytes).0.to_string()
|
||||
@@ -161,15 +204,15 @@ mod tests {
|
||||
assert!(text.contains("[truncated]"));
|
||||
assert_eq!(text.matches('é').count(), 25);
|
||||
|
||||
let chat = body(Kind::Chat, "m", Some("sys"), "usr", 1.5, 200);
|
||||
let chat = body(Kind::Chat, "m", Some("sys"), "usr", 1.5, 200, false);
|
||||
assert_eq!(chat["messages"][0]["role"], "system");
|
||||
assert_eq!(chat["messages"][1]["content"], "usr");
|
||||
assert_eq!(chat["temperature"], 1.0);
|
||||
assert_eq!(chat["stream"], false);
|
||||
assert!(chat.get("user").is_none());
|
||||
let text = body(Kind::Text, "m", Some("sys"), "usr", 0.5, 200);
|
||||
let text = body(Kind::Text, "m", Some("sys"), "usr", 0.5, 200, false);
|
||||
assert_eq!(text["prompt"], "sys\n\nusr");
|
||||
let sieve = body(Kind::Chat, "m", None, "hello", 0.5, 1000);
|
||||
let sieve = body(Kind::Chat, "m", None, "hello", 0.5, 1000, false);
|
||||
assert_eq!(sieve["messages"].as_array().unwrap().len(), 1);
|
||||
}
|
||||
|
||||
@@ -186,4 +229,18 @@ mod tests {
|
||||
assert_eq!(answer(Kind::Chat, br#"{"choices":[]}"#), None);
|
||||
assert_eq!(answer(Kind::Chat, &vec![b' '; MAX_RESPONSE_BYTES + 1]), None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn reads_streamed_answers() {
|
||||
let chat = r#"data: {"choices":[{"index":0,"delta":{"content":"Hel"}}]}"#;
|
||||
assert_eq!(stream_line(Kind::Chat, chat), StreamLine::Delta("Hel".into()));
|
||||
let role = r#"data: {"choices":[{"index":0,"delta":{"role":"assistant"}}]}"#;
|
||||
assert_eq!(stream_line(Kind::Chat, role), StreamLine::Ignore);
|
||||
let text = r#"data: {"choices":[{"index":0,"text":"lo"}]}"#;
|
||||
assert_eq!(stream_line(Kind::Text, text), StreamLine::Delta("lo".into()));
|
||||
assert_eq!(stream_line(Kind::Chat, "data: [DONE]"), StreamLine::Done);
|
||||
assert_eq!(stream_line(Kind::Chat, ": keep-alive"), StreamLine::Ignore);
|
||||
assert_eq!(stream_line(Kind::Chat, ""), StreamLine::Ignore);
|
||||
assert_eq!(stream_line(Kind::Chat, "data: {not json"), StreamLine::Ignore);
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user