1use std::fmt;
100use std::time::Duration;
101
102use serde::de::DeserializeOwned;
103use serde::{Deserialize, Serialize};
104use serde_json::{json, Map, Value};
105
106use crate::codes::Code;
107use crate::error::{Error, Fault};
108use crate::host;
109use crate::storage::DocumentHandle;
110
111const ORCHESTRATOR: &str = "logic:dev.simple.system/ai-orchestrator";
113
114const UPLOAD_EPHEMERAL: &str = "action:documents/upload-ephemeral";
116
117const FACE_ENROLL: &str = "action:ai/face/enroll";
119
120const FACE_SEARCH: &str = "action:ai/face/search";
122
123const FACE_DELETE: &str = "action:ai/face/delete";
125
126#[non_exhaustive]
131#[derive(Clone, Copy, Debug, PartialEq, Eq)]
132pub enum Model {
133 Lite,
135 Medium,
137 Large,
139 Xl,
141}
142
143impl Model {
144 pub fn as_str(&self) -> &str {
146 match self {
147 Model::Lite => "lite",
148 Model::Medium => "medium",
149 Model::Large => "large",
150 Model::Xl => "xl",
151 }
152 }
153}
154
155impl fmt::Display for Model {
156 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
157 formatter.write_str(self.as_str())
158 }
159}
160
161#[non_exhaustive]
169#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]
170#[serde(rename_all = "lowercase")]
171pub enum Delivery {
172 Document,
175 Text,
177}
178
179#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]
188pub struct Pages {
189 pub first_page: u32,
191 pub last_page: u32,
193}
194
195impl Pages {
196 pub fn new(first: u32, last: u32) -> Pages {
198 Pages {
199 first_page: first,
200 last_page: last,
201 }
202 }
203}
204
205#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
263pub struct DocumentInput {
264 #[serde(flatten)]
267 pub file: DocumentHandle,
268
269 #[serde(default, flatten)]
271 pub pages: Option<Pages>,
272
273 #[serde(default, skip_serializing_if = "Option::is_none")]
277 pub deliver_as: Option<Delivery>,
278}
279
280#[non_exhaustive]
283#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]
284#[serde(rename_all = "lowercase")]
285pub enum Transcription {
286 Standard,
288 Precise,
290}
291
292#[derive(Clone, Debug)]
306pub struct Options {
307 pub transcription: Option<Transcription>,
310
311 pub model: Option<Model>,
313
314 pub system_prompt: Option<String>,
317
318 pub temperature: Option<f64>,
321
322 pub reasoning: bool,
325
326 pub reasoning_budget: Option<u32>,
329
330 pub regenerate: bool,
333
334 pub timeout: Option<Duration>,
336}
337
338impl Default for Options {
339 fn default() -> Options {
341 Options {
342 transcription: None,
343 model: None,
344 system_prompt: None,
345 temperature: None,
346 reasoning: true,
347 reasoning_budget: None,
348 regenerate: false,
349 timeout: None,
350 }
351 }
352}
353
354#[derive(Clone, Debug, Default, PartialEq, Eq)]
356pub enum Participants {
357 #[default]
359 Ignore,
360
361 Detect,
364
365 Named(Vec<String>),
368}
369
370impl Participants {
371 fn wanted(&self) -> bool {
373 !matches!(self, Participants::Ignore)
374 }
375
376 fn names(&self) -> Option<String> {
378 match self {
379 Participants::Named(names) if !names.is_empty() => Some(names.join(", ")),
380 _ => None,
381 }
382 }
383}
384
385#[derive(Clone, Debug, Default)]
390pub struct TranscribeOptions {
391 pub include_transcript: bool,
393
394 pub include_timestamps: bool,
397
398 pub summarize: bool,
400
401 pub participants: Participants,
403}
404
405#[derive(Clone, Debug, Default, Deserialize)]
410#[serde(default)]
411pub struct Transcript {
412 pub language: String,
414
415 pub transcript: Option<String>,
417
418 pub summary: Option<String>,
420
421 pub participants: Vec<String>,
423}
424
425#[derive(Clone, Debug, Default)]
431pub struct TranscribePagesOptions {
432 pub transcription: Option<Transcription>,
435
436 pub regenerate: bool,
440
441 pub timeout: Option<Duration>,
443}
444
445#[derive(Clone, Debug, PartialEq, Eq)]
451pub enum PageTranscription {
452 Read {
454 page: u32,
456
457 text: String,
461 },
462
463 Unread {
465 page: u32,
467
468 error: String,
470 },
471}
472
473impl PageTranscription {
474 pub fn page(&self) -> u32 {
476 match self {
477 PageTranscription::Read { page, .. } | PageTranscription::Unread { page, .. } => *page,
478 }
479 }
480
481 pub fn text(&self) -> Option<&str> {
483 match self {
484 PageTranscription::Read { text, .. } => Some(text),
485 PageTranscription::Unread { .. } => None,
486 }
487 }
488}
489
490#[derive(Clone, Debug)]
492pub struct Execution<T> {
493 pub data: T,
495
496 pub metadata: Metadata,
498}
499
500#[derive(Clone, Debug, Default, PartialEq, Eq)]
502pub struct Metadata {
503 pub input_tokens: u64,
505
506 pub output_tokens: u64,
508
509 pub reasoning_tokens: Option<u64>,
511
512 pub reasoning: Option<String>,
514
515 pub delivery: Vec<FileDelivery>,
519}
520
521#[derive(Clone, Debug, PartialEq, Eq)]
578pub struct FileDelivery {
579 pub filename: String,
581
582 pub delivered_as: DeliveredAs,
584
585 pub pages: Option<Pages>,
588
589 pub transcribed_pages: Vec<u32>,
592
593 pub fallback: Option<DeliveryFallback>,
596}
597
598#[non_exhaustive]
606#[derive(Clone, Copy, Debug, PartialEq, Eq)]
607pub enum DeliveredAs {
608 Document,
611 Text,
614 Image,
616}
617
618#[derive(Clone, Debug, Default, PartialEq, Eq)]
620pub struct DeliveryFallback {
621 pub reason: String,
626
627 pub pages: Vec<u32>,
629
630 pub message: String,
632}
633
634#[derive(Clone, Debug, Default)]
636pub struct FaceSearch {
637 pub max_faces: Option<u32>,
639
640 pub similarity_threshold: Option<f64>,
643}
644
645pub fn extract<T: DeserializeOwned>(
680 input: Value,
681 prompt: &str,
682 schema: Value,
683 options: Options,
684) -> Result<Execution<T>, Error> {
685 refuse_empty(
686 &input,
687 "extract needs something to read.",
688 "Pass the text, the document handle, or the object the extraction is to read.",
689 )?;
690 refuse_empty_prompt(prompt, "extract")?;
691
692 if !schema.is_object() {
693 return Err(
694 Error::invalid("extract needs a JSON Schema object describing the answer.").hint(
695 "Pass a schema object naming the type and the properties the answer is to have.",
696 ),
697 );
698 }
699
700 run("extract", input, Some(prompt), Some(schema), &options)
701}
702
703pub fn summarize(input: Value, prompt: &str, options: Options) -> Result<Execution<String>, Error> {
722 refuse_empty(
723 &input,
724 "summarize needs something to read.",
725 "Pass the text, the document handle, or the object the summary is to be written from.",
726 )?;
727 refuse_empty_prompt(prompt, "summarize")?;
728
729 run("summarize", input, Some(prompt), None, &options)
730}
731
732pub fn transcribe(
767 document: Value,
768 wanted: TranscribeOptions,
769 options: Options,
770) -> Result<Execution<Transcript>, Error> {
771 refuse_unless_media(&document)?;
772
773 if !wanted.include_transcript && !wanted.summarize {
774 return Err(
775 Error::invalid("transcribe needs to be told what to produce.")
776 .hint("Set include_transcript, summarize, or both."),
777 );
778 }
779
780 let prompt = transcribe_prompt(&wanted);
781
782 run(
783 "extract",
784 document,
785 Some(&prompt),
786 Some(transcribe_schema(&wanted)),
787 &options,
788 )
789}
790
791pub fn transcribe_pages(
862 document: &DocumentHandle,
863 pages: Option<Pages>,
864 options: TranscribePagesOptions,
865) -> Result<Execution<Vec<PageTranscription>>, Error> {
866 refuse_unless_pdf(document)?;
867
868 let input = json!(DocumentInput {
869 file: document.clone(),
870 pages,
871 deliver_as: None,
872 });
873
874 let options = Options {
877 transcription: options.transcription,
878 regenerate: options.regenerate,
879 timeout: options.timeout,
880 ..Options::default()
881 };
882
883 let read: Execution<Value> = run("transcribe", input, None, None, &options)?;
884
885 Ok(Execution {
886 data: page_transcriptions(&read.data),
887 metadata: read.metadata,
888 })
889}
890
891pub fn enroll_face(subject_id: &str, image: Value) -> Result<String, Error> {
906 if subject_id.trim().is_empty() {
907 return Err(
908 Error::invalid("enroll_face needs the subject the face belongs to.")
909 .hint("Pass the id the face is to be found under, such as an employee or user id."),
910 );
911 }
912
913 refuse_empty(
914 &image,
915 "enroll_face needs an image of the face.",
916 "Pass a base64 image, or the handle of an uploaded one.",
917 )?;
918
919 let image = upload_pending(image)?;
920
921 let enrolled = host::transport()?
922 .call(
923 FACE_ENROLL.to_string(),
924 json!({ "image": image, "subject_id": subject_id }),
925 )
926 .map_err(|cause| {
927 cause.hint(
928 "Search the subject before enrolling the same face again, and report the failure.",
929 )
930 })?;
931
932 enrolled
933 .get("face_id")
934 .and_then(Value::as_str)
935 .map(str::to_string)
936 .ok_or_else(|| {
937 Error::Json(Fault::new(
938 Code::unspecified(),
939 "The enrolment answered without the id of the face it enrolled.",
940 ))
941 .hint("Search the subject to establish what was enrolled before enrolling again.")
942 })
943}
944
945pub fn search_face<T: DeserializeOwned>(image: Value, options: FaceSearch) -> Result<T, Error> {
968 refuse_empty(
969 &image,
970 "search_face needs an image to search with.",
971 "Pass a base64 image, or the handle of an uploaded one.",
972 )?;
973
974 let image = upload_pending(image)?;
975
976 let mut narrowing = Map::new();
977
978 if let Some(max_faces) = options.max_faces {
979 narrowing.insert("max_faces".to_string(), Value::from(max_faces));
980 }
981
982 if let Some(threshold) = options
983 .similarity_threshold
984 .filter(|value| value.is_finite())
985 {
986 narrowing.insert("similarity_threshold".to_string(), Value::from(threshold));
987 }
988
989 let found = host::transport()?
990 .call(
991 FACE_SEARCH.to_string(),
992 json!({ "image": image, "options": narrowing }),
993 )
994 .map_err(|cause| {
995 cause.hint("Nothing in the collection was changed. Report the search failure.")
996 })?;
997
998 serde_json::from_value(found).map_err(|cause| {
999 Error::Json(Fault::new(
1000 Code::unspecified(),
1001 format!("The matches could not be read into the type this action asked for: {cause}"),
1002 ))
1003 .hint("Read the matches as a Value, or name a type that matches what the search answers.")
1004 })
1005}
1006
1007pub fn delete_face(face_ids: &[String]) -> Result<Vec<String>, Error> {
1022 if face_ids.is_empty() {
1023 return Err(Error::invalid("delete_face needs at least one face id.")
1024 .hint("Pass the ids enroll_face answered with."));
1025 }
1026
1027 let removed = host::transport()?
1028 .call(FACE_DELETE.to_string(), json!({ "face_ids": face_ids }))
1029 .map_err(|cause| {
1030 cause.hint(
1031 "Treat the removal as unfinished: search the collection to establish what is \
1032 still in it before deleting again.",
1033 )
1034 })?;
1035
1036 let listed = match &removed {
1037 Value::Array(ids) => Some(ids),
1038 other => other.get("deleted").and_then(Value::as_array),
1039 };
1040
1041 Ok(listed
1042 .map(|ids| {
1043 ids.iter()
1044 .filter_map(Value::as_str)
1045 .map(str::to_string)
1046 .collect()
1047 })
1048 .unwrap_or_default())
1049}
1050
1051fn run<T: DeserializeOwned>(
1053 operation: &str,
1054 input: Value,
1055 prompt: Option<&str>,
1056 schema: Option<Value>,
1057 options: &Options,
1058) -> Result<Execution<T>, Error> {
1059 let input = upload_pending(input)?;
1060
1061 let answered = host::transport()?
1062 .call(
1063 ORCHESTRATOR.to_string(),
1064 payload(operation, input, prompt, schema, options),
1065 )
1066 .map_err(|cause| {
1067 cause.hint(
1068 "No tenant record was changed. Review the input, the prompt and the schema, \
1069 and report the failure.",
1070 )
1071 })?;
1072
1073 let metadata = metadata_of(answered.get("metadata"));
1076 let data = answered.get("data").cloned().unwrap_or(Value::Null);
1077
1078 let data = serde_json::from_value(data).map_err(|cause| {
1079 Error::Json(Fault::new(
1080 Code::unspecified(),
1081 format!("The {operation} answer could not be read into the type this action asked for: {cause}"),
1082 ))
1083 .hint(
1084 "The operation ran. Read the answer as a Value, or name a type that matches the \
1085 schema, rather than running it again.",
1086 )
1087 })?;
1088
1089 Ok(Execution { data, metadata })
1090}
1091
1092fn payload(
1097 operation: &str,
1098 input: Value,
1099 prompt: Option<&str>,
1100 schema: Option<Value>,
1101 options: &Options,
1102) -> Value {
1103 let mut universal = Map::new();
1106
1107 universal.insert("reasoning".to_string(), Value::Bool(options.reasoning));
1108
1109 if let Some(transcription) = options.transcription {
1110 universal.insert("transcription".to_string(), json!(transcription));
1111 }
1112
1113 if let Some(budget) = options.reasoning_budget {
1114 universal.insert("reasoning_budget".to_string(), Value::from(budget));
1115 }
1116
1117 if let Some(temperature) = options.temperature.filter(|value| value.is_finite()) {
1118 universal.insert("temperature".to_string(), Value::from(temperature));
1119 }
1120
1121 let mut payload = Map::new();
1122
1123 payload.insert("operation".to_string(), Value::from(operation));
1124 payload.insert("input".to_string(), input);
1125 payload.insert("options".to_string(), Value::Object(universal));
1126
1127 if let Some(prompt) = prompt {
1130 payload.insert("prompt".to_string(), Value::from(prompt));
1131 }
1132 payload.insert("regenerate".to_string(), Value::Bool(options.regenerate));
1133
1134 if let Some(schema) = schema {
1135 payload.insert("schema".to_string(), schema);
1136 }
1137
1138 if let Some(model) = options.model {
1139 payload.insert("model".to_string(), Value::from(model.as_str()));
1140 }
1141
1142 if let Some(system_prompt) = &options.system_prompt {
1143 payload.insert(
1144 "systemPrompt".to_string(),
1145 Value::from(system_prompt.as_str()),
1146 );
1147 }
1148
1149 if let Some(timeout) = options.timeout {
1150 payload.insert("timeout".to_string(), Value::from(milliseconds(timeout)));
1151 }
1152
1153 Value::Object(payload)
1154}
1155
1156fn milliseconds(timeout: Duration) -> u64 {
1158 u64::try_from(timeout.as_millis()).unwrap_or(u64::MAX)
1159}
1160
1161fn metadata_of(metadata: Option<&Value>) -> Metadata {
1163 let Some(metadata) = metadata else {
1164 return Metadata::default();
1165 };
1166
1167 Metadata {
1168 input_tokens: count(metadata, "input_tokens").unwrap_or(0),
1169 output_tokens: count(metadata, "output_tokens").unwrap_or(0),
1170 reasoning_tokens: count(metadata, "reasoning_tokens"),
1171 reasoning: metadata
1172 .get("reasoning")
1173 .and_then(Value::as_str)
1174 .map(str::to_string),
1175 delivery: delivery_of(metadata.get("delivery")),
1176 }
1177}
1178
1179fn count(metadata: &Value, key: &str) -> Option<u64> {
1181 metadata.get(key).and_then(Value::as_u64)
1182}
1183
1184fn delivery_of(delivery: Option<&Value>) -> Vec<FileDelivery> {
1190 delivery
1191 .and_then(Value::as_array)
1192 .map(|files| files.iter().filter_map(file_delivery).collect())
1193 .unwrap_or_default()
1194}
1195
1196fn file_delivery(file: &Value) -> Option<FileDelivery> {
1201 let delivered_as = match file.get("delivered_as").and_then(Value::as_str)? {
1202 "document" => DeliveredAs::Document,
1203 "text" => DeliveredAs::Text,
1204 "image" => DeliveredAs::Image,
1205 _ => return None,
1206 };
1207
1208 let first_page = file.get("first_page").and_then(page_number);
1209 let last_page = file.get("last_page").and_then(page_number);
1210
1211 Some(FileDelivery {
1212 filename: file.get("filename").and_then(Value::as_str)?.to_string(),
1213 delivered_as,
1214 pages: first_page
1215 .zip(last_page)
1216 .map(|(first, last)| Pages::new(first, last)),
1217 transcribed_pages: page_numbers(file.get("transcribed_pages")),
1218 fallback: file
1219 .get("fallback")
1220 .filter(|fallback| fallback.is_object())
1221 .map(delivery_fallback),
1222 })
1223}
1224
1225fn delivery_fallback(fallback: &Value) -> DeliveryFallback {
1228 let text = |key: &str| {
1229 fallback
1230 .get(key)
1231 .and_then(Value::as_str)
1232 .unwrap_or_default()
1233 .to_string()
1234 };
1235
1236 DeliveryFallback {
1237 reason: text("reason"),
1238 pages: page_numbers(fallback.get("pages")),
1239 message: text("message"),
1240 }
1241}
1242
1243fn page_number(value: &Value) -> Option<u32> {
1245 value
1246 .as_u64()
1247 .and_then(|number| u32::try_from(number).ok())
1248 .filter(|page| *page > 0)
1249}
1250
1251fn page_numbers(pages: Option<&Value>) -> Vec<u32> {
1253 pages
1254 .and_then(Value::as_array)
1255 .map(|pages| pages.iter().filter_map(page_number).collect())
1256 .unwrap_or_default()
1257}
1258
1259const NO_TRANSCRIPTION: &str = "no transcription was returned for this page";
1261
1262fn page_transcriptions(data: &Value) -> Vec<PageTranscription> {
1267 data.get("pages")
1268 .and_then(Value::as_array)
1269 .map(|pages| pages.iter().filter_map(page_transcription).collect())
1270 .unwrap_or_default()
1271}
1272
1273fn page_transcription(entry: &Value) -> Option<PageTranscription> {
1279 let page = entry.get("page").and_then(page_number)?;
1280 let error = entry.get("error").and_then(Value::as_str);
1281 let text = entry.get("text").and_then(Value::as_str);
1282
1283 Some(match (error, text) {
1284 (None, Some(text)) => PageTranscription::Read {
1285 page,
1286 text: text.to_string(),
1287 },
1288 (error, _) => PageTranscription::Unread {
1289 page,
1290 error: error.unwrap_or(NO_TRANSCRIPTION).to_string(),
1291 },
1292 })
1293}
1294
1295fn upload_pending(value: Value) -> Result<Value, Error> {
1301 if is_pending(&value) {
1302 let stored = host::transport()?
1303 .call(UPLOAD_EPHEMERAL.to_string(), value.clone())
1304 .map_err(|cause| {
1305 cause.hint(
1306 "The file was not uploaded and the operation did not run. Upload the file, \
1307 then pass the handle that upload answered with.",
1308 )
1309 })?;
1310
1311 return Ok(stored_handle(value, stored));
1312 }
1313
1314 if let Value::Array(items) = value {
1315 let mut uploaded = Vec::with_capacity(items.len());
1316
1317 for item in items {
1318 uploaded.push(upload_pending(item)?);
1319 }
1320
1321 return Ok(Value::Array(uploaded));
1322 }
1323
1324 Ok(value)
1325}
1326
1327fn stored_handle(handle: Value, stored: Value) -> Value {
1345 match (handle, stored) {
1346 (Value::Object(mut handle), Value::Object(stored)) => {
1347 handle.remove("pending");
1348 handle.extend(stored);
1349
1350 Value::Object(handle)
1351 }
1352 (_, stored) => stored,
1353 }
1354}
1355
1356fn is_pending(value: &Value) -> bool {
1361 value.get("pending").and_then(Value::as_bool) == Some(true) && has_file_hash(value)
1362}
1363
1364fn has_file_hash(value: &Value) -> bool {
1366 value
1367 .get("file_hash")
1368 .and_then(Value::as_str)
1369 .is_some_and(|hash| !hash.is_empty())
1370}
1371
1372fn refuse_empty(value: &Value, message: &str, hint: &str) -> Result<(), Error> {
1374 let empty = match value {
1375 Value::Null => true,
1376 Value::String(text) => text.is_empty(),
1377 _ => false,
1378 };
1379
1380 if empty {
1381 return Err(Error::invalid(message).hint(hint));
1382 }
1383
1384 Ok(())
1385}
1386
1387fn refuse_empty_prompt(prompt: &str, operation: &str) -> Result<(), Error> {
1389 if prompt.trim().is_empty() {
1390 return Err(Error::invalid(format!("{operation} needs a prompt."))
1391 .hint("Say what the operation is to produce, in a sentence the model can act on."));
1392 }
1393
1394 Ok(())
1395}
1396
1397fn refuse_unless_media(document: &Value) -> Result<(), Error> {
1399 if !has_file_hash(document) {
1400 return Err(
1401 Error::invalid("transcribe needs a document handle to work on.").hint(
1402 "Pass the handle of the uploaded file, the one carrying file_hash and mime_type.",
1403 ),
1404 );
1405 }
1406
1407 let media = document
1408 .get("mime_type")
1409 .and_then(Value::as_str)
1410 .map(str::to_lowercase)
1411 .is_some_and(|mime| mime.starts_with("audio/") || mime.starts_with("video/"));
1412
1413 if !media {
1414 return Err(Error::invalid("transcribe works on audio and video.")
1415 .hint("Pass a handle whose mime_type begins audio/ or video/."));
1416 }
1417
1418 Ok(())
1419}
1420
1421fn refuse_unless_pdf(document: &DocumentHandle) -> Result<(), Error> {
1426 if document.file_hash.is_empty() {
1427 return Err(
1428 Error::invalid("transcribe_pages needs the handle of a stored file.").hint(
1429 "Pass the handle the upload or the record answered with, the one carrying \
1430 file_hash.",
1431 ),
1432 );
1433 }
1434
1435 let essence = document.mime_type.split(';').next().unwrap_or_default();
1436
1437 if !essence.trim().eq_ignore_ascii_case("application/pdf") {
1438 return Err(Error::invalid("transcribe_pages reads the pages of a PDF.")
1439 .hint("Pass the handle of a PDF. Read any other file with extract or summarize."));
1440 }
1441
1442 Ok(())
1443}
1444
1445fn transcribe_schema(wanted: &TranscribeOptions) -> Value {
1447 let identify = wanted.participants.wanted();
1448
1449 let mut properties = Map::new();
1450 let mut required = vec![Value::from("language")];
1451
1452 properties.insert(
1453 "language".to_string(),
1454 json!({
1455 "description": "The detected language of the audio (ISO 639-1 code, e.g., \"en\", \"es\")",
1456 "type": "string"
1457 }),
1458 );
1459
1460 if wanted.include_transcript {
1461 let description = match (identify, wanted.include_timestamps) {
1462 (true, true) => {
1463 "The full transcript with participant labels and timestamps. \
1464 Format: [MM:SS] Participant Name: text"
1465 }
1466 (true, false) => {
1467 "The full transcript with participant labels. Format: Participant Name: text"
1468 }
1469 (false, true) => "The full transcript with timestamps. Format: [MM:SS] text",
1470 (false, false) => "The full transcript of the audio",
1471 };
1472
1473 properties.insert(
1474 "transcript".to_string(),
1475 json!({ "description": description, "type": "string" }),
1476 );
1477 required.push(Value::from("transcript"));
1478 }
1479
1480 if wanted.summarize {
1481 let description = if identify {
1482 "A concise summary of the audio content, including key points from each participant"
1483 } else {
1484 "A concise summary of the audio content"
1485 };
1486
1487 properties.insert(
1488 "summary".to_string(),
1489 json!({ "description": description, "type": "string" }),
1490 );
1491 required.push(Value::from("summary"));
1492 }
1493
1494 if identify {
1495 properties.insert(
1496 "participants".to_string(),
1497 json!({
1498 "description": "List of identified participants in the audio",
1499 "items": { "type": "string" },
1500 "type": "array"
1501 }),
1502 );
1503 required.push(Value::from("participants"));
1504 }
1505
1506 json!({ "properties": properties, "required": required, "type": "object" })
1507}
1508
1509fn transcribe_prompt(wanted: &TranscribeOptions) -> String {
1511 let identify = wanted.participants.wanted();
1512 let names = wanted.participants.names();
1513
1514 let mut prompt = String::from("Analyze this audio/video file and provide:\n");
1515
1516 if wanted.include_transcript {
1517 if identify {
1518 match &names {
1519 Some(names) => {
1520 prompt.push_str("- A complete transcript identifying these participants: ");
1521 prompt.push_str(names);
1522 prompt.push_str(". ");
1523 }
1524 None => prompt.push_str(
1525 "- A complete transcript with participant identification \
1526 (label participants as Participant 1, Participant 2, etc.). ",
1527 ),
1528 }
1529
1530 if wanted.include_timestamps {
1531 prompt.push_str(
1532 "Include timestamps in [MM:SS] format before each participant segment.\n",
1533 );
1534 } else {
1535 prompt.push_str("Format each line as \"Participant Name: text\".\n");
1536 }
1537 } else if wanted.include_timestamps {
1538 prompt.push_str(
1539 "- A complete transcript with timestamps in [MM:SS] format before each segment\n",
1540 );
1541 } else {
1542 prompt.push_str("- A complete transcript of all spoken content\n");
1543 }
1544 }
1545
1546 if wanted.summarize {
1547 if identify {
1548 prompt.push_str("- A concise summary highlighting key points from each participant\n");
1549 } else {
1550 prompt.push_str("- A concise summary of the main points and key information\n");
1551 }
1552 }
1553
1554 if identify {
1555 match &names {
1556 Some(names) => {
1557 prompt.push_str("- Identify and distinguish between these participants: ");
1558 prompt.push_str(names);
1559 prompt.push('\n');
1560 }
1561 None => prompt.push_str("- Identify and list all distinct participants in the audio\n"),
1562 }
1563 }
1564
1565 prompt.push_str("- The detected language code (ISO 639-1 format)\n");
1566
1567 prompt
1568}
1569
1570#[cfg(test)]
1571mod tests {
1572 #[test]
1573 fn transcription_posts_exact_options_on_all_four_calls() {
1574 for transcription in [
1575 None,
1576 Some(Transcription::Standard),
1577 Some(Transcription::Precise),
1578 ] {
1579 for operation in ["extract", "summarize", "transcribe", "transcribe_pages"] {
1580 let session = testing::install(move |_name, _params| {
1581 Ok(
1582 json!({ "data": if operation == "summarize" { json!("summary") } else { json!({ "pages": [] }) } }),
1583 )
1584 });
1585 let options = Options {
1586 transcription,
1587 ..Default::default()
1588 };
1589 match operation {
1590 "extract" => {
1591 let _: Execution<Value> = extract(
1592 json!(stored()),
1593 "Read it.",
1594 json!({ "type": "object" }),
1595 options,
1596 )
1597 .unwrap();
1598 }
1599 "summarize" => {
1600 summarize(json!(stored()), "Read it.", options).unwrap();
1601 }
1602 "transcribe" => {
1603 transcribe(
1604 json!({ "file_hash": "abc", "mime_type": "audio/wav" }),
1605 TranscribeOptions {
1606 include_transcript: true,
1607 ..Default::default()
1608 },
1609 options,
1610 )
1611 .unwrap();
1612 }
1613 _ => {
1614 transcribe_pages(
1615 &stored(),
1616 None,
1617 TranscribePagesOptions {
1618 transcription,
1619 ..Default::default()
1620 },
1621 )
1622 .unwrap();
1623 }
1624 }
1625 let expected = match transcription {
1626 None => json!({ "reasoning": true }),
1627 Some(Transcription::Standard) => {
1628 json!({ "reasoning": true, "transcription": "standard" })
1629 }
1630 Some(Transcription::Precise) => {
1631 json!({ "reasoning": true, "transcription": "precise" })
1632 }
1633 };
1634 assert_eq!(session.calls().len(), 1);
1635 assert_eq!(session.calls()[0].name, ORCHESTRATOR);
1636 assert_eq!(session.calls()[0].params["options"], expected);
1637 assert_eq!(session.calls()[0].params["regenerate"], json!(false));
1638 }
1639 }
1640 }
1641
1642 #[test]
1643 fn transcription_preserves_existing_options_and_adds_only_its_wire_key() {
1644 for operation in ["extract", "summarize", "transcribe", "transcribe_pages"] {
1645 let session = testing::install(move |_name, _params| {
1646 Ok(
1647 json!({ "data": if operation == "summarize" { json!("summary") } else { json!({ "pages": [] }) } }),
1648 )
1649 });
1650 for transcription in [None, Some(Transcription::Precise)] {
1651 let options = Options {
1652 transcription,
1653 reasoning: false,
1654 reasoning_budget: Some(2048),
1655 temperature: Some(0.25),
1656 regenerate: true,
1657 timeout: Some(Duration::from_secs(90)),
1658 ..Default::default()
1659 };
1660 match operation {
1661 "extract" => {
1662 let _: Execution<Value> = extract(
1663 json!(stored()),
1664 "Read it.",
1665 json!({ "type": "object" }),
1666 options,
1667 )
1668 .unwrap();
1669 }
1670 "summarize" => {
1671 summarize(json!(stored()), "Read it.", options).unwrap();
1672 }
1673 "transcribe" => {
1674 transcribe(
1675 json!({ "file_hash": "abc", "mime_type": "audio/wav" }),
1676 TranscribeOptions {
1677 include_transcript: true,
1678 ..Default::default()
1679 },
1680 options,
1681 )
1682 .unwrap();
1683 }
1684 _ => {
1685 transcribe_pages(
1686 &stored(),
1687 None,
1688 TranscribePagesOptions {
1689 transcription,
1690 regenerate: true,
1691 timeout: Some(Duration::from_secs(90)),
1692 },
1693 )
1694 .unwrap();
1695 }
1696 }
1697 }
1698 let calls = session.calls();
1699 let expected = if operation == "transcribe_pages" {
1700 json!({ "reasoning": true })
1701 } else {
1702 json!({ "reasoning": false, "reasoning_budget": 2048, "temperature": 0.25 })
1703 };
1704 assert_eq!(calls[0].params["options"], expected);
1705 let mut precise = calls[0].params.clone();
1706 precise["options"]["transcription"] = json!("precise");
1707 assert_eq!(calls[1].params, precise);
1708 }
1709 }
1710
1711 #[test]
1712 fn transcription_refuses_invalid_values_before_any_host_call() {
1713 let session = testing::install(|_name, _params| Ok(answered()));
1714 for value in [
1715 json!("other"),
1716 json!(""),
1717 Value::Null,
1718 json!(0),
1719 json!(false),
1720 json!({}),
1721 json!([]),
1722 ] {
1723 let error = serde_json::from_value::<Transcription>(value).unwrap_err();
1724 if error.to_string().contains("unknown variant") {
1725 assert!(error.to_string().contains("standard"));
1726 assert!(error.to_string().contains("precise"));
1727 }
1728 }
1729 assert!(session.calls().is_empty());
1730 }
1731
1732 use serde_json::json;
1733
1734 use super::*;
1735 use crate::testing;
1736
1737 fn answered() -> Value {
1739 json!({ "data": { "ok": true }, "metadata": { "input_tokens": 1, "output_tokens": 2 } })
1740 }
1741
1742 fn stored() -> DocumentHandle {
1744 DocumentHandle {
1745 file_hash: "ffce20f1".to_string(),
1746 filename: "contract.pdf".to_string(),
1747 mime_type: "application/pdf".to_string(),
1748 size: 1_234,
1749 storage_path: "acme/documents/ffce20f1".to_string(),
1750 }
1751 }
1752
1753 #[test]
1754 fn a_document_input_travels_as_the_handle_with_the_keys_the_engine_reads() {
1755 let sent = json!(DocumentInput {
1756 file: stored(),
1757 pages: Some(Pages::new(12, 30)),
1758 deliver_as: Some(Delivery::Text),
1759 });
1760
1761 assert_eq!(sent["storage_path"], json!("acme/documents/ffce20f1"));
1762 assert_eq!(sent["file_hash"], json!("ffce20f1"));
1763 assert_eq!(sent["mime_type"], json!("application/pdf"));
1764 assert_eq!(
1765 sent["first_page"],
1766 json!(12),
1767 "a range travels as the two keys the engine reads, not as a nested one"
1768 );
1769 assert_eq!(sent["last_page"], json!(30));
1770 assert_eq!(sent["deliver_as"], json!("text"));
1771 }
1772
1773 #[test]
1774 fn a_document_input_that_asks_for_nothing_carries_neither_key() {
1775 let sent = json!(DocumentInput {
1776 file: stored(),
1777 ..Default::default()
1778 });
1779
1780 assert_eq!(sent["filename"], json!("contract.pdf"));
1781 assert_eq!(
1782 sent.get("deliver_as"),
1783 None,
1784 "asking for nothing says nothing, so the default stays the engine's"
1785 );
1786 assert_eq!(sent.get("first_page"), None);
1787 assert_eq!(sent.get("last_page"), None);
1788 }
1789
1790 #[test]
1791 fn an_extraction_asks_the_primitive_and_answers_with_the_type_it_was_asked_for() {
1792 #[derive(Debug, Deserialize, PartialEq)]
1793 struct Invoice {
1794 number: String,
1795 total: f64,
1796 }
1797
1798 let session = testing::install(|name, params| {
1799 assert_eq!(name, ORCHESTRATOR);
1800 assert_eq!(params["operation"], json!("extract"));
1801 assert_eq!(params["prompt"], json!("Read it."));
1802 assert_eq!(params["input"], json!("INV-8, 240.00"));
1803 assert_eq!(params["schema"]["type"], json!("object"));
1804
1805 Ok(json!({
1806 "data": { "number": "INV-8", "total": 240.0 },
1807 "metadata": { "input_tokens": 11, "output_tokens": 3 }
1808 }))
1809 });
1810
1811 let read: Execution<Invoice> = extract(
1812 json!("INV-8, 240.00"),
1813 "Read it.",
1814 json!({ "type": "object" }),
1815 Options::default(),
1816 )
1817 .unwrap();
1818
1819 assert_eq!(
1820 read.data,
1821 Invoice {
1822 number: "INV-8".to_string(),
1823 total: 240.0
1824 }
1825 );
1826 assert_eq!(read.metadata.input_tokens, 11);
1827 assert_eq!(read.metadata.output_tokens, 3);
1828 assert_eq!(session.calls().len(), 1);
1829 }
1830
1831 #[test]
1832 fn a_default_call_reasons_does_not_regenerate_and_leaves_the_rest_to_the_platform() {
1833 let session = testing::install(|_name, _params| Ok(answered()));
1834
1835 let _: Execution<Value> = extract(
1836 json!("text"),
1837 "Read it.",
1838 json!({ "type": "object" }),
1839 Options::default(),
1840 )
1841 .unwrap();
1842
1843 let sent = session.calls()[0].params.clone();
1844
1845 assert_eq!(sent["options"], json!({ "reasoning": true }));
1846 assert_eq!(sent["regenerate"], json!(false));
1847 assert!(sent.get("model").is_none());
1848 assert!(sent.get("systemPrompt").is_none());
1849 assert!(sent.get("timeout").is_none());
1850 }
1851
1852 #[test]
1853 fn every_option_that_was_set_travels_with_the_operation() {
1854 let session = testing::install(|_name, _params| Ok(answered()));
1855
1856 let _: Execution<Value> = extract(
1857 json!("text"),
1858 "Read it.",
1859 json!({ "type": "object" }),
1860 Options {
1861 model: Some(Model::Xl),
1862 transcription: None,
1863 system_prompt: Some("You are an auditor.".to_string()),
1864 temperature: Some(0.25),
1865 reasoning: false,
1866 reasoning_budget: Some(2_048),
1867 regenerate: true,
1868 timeout: Some(Duration::from_secs(90)),
1869 },
1870 )
1871 .unwrap();
1872
1873 let sent = session.calls()[0].params.clone();
1874
1875 assert_eq!(sent["model"], json!("xl"));
1876 assert_eq!(sent["systemPrompt"], json!("You are an auditor."));
1877 assert_eq!(sent["regenerate"], json!(true));
1878 assert_eq!(sent["timeout"], json!(90_000));
1879 assert_eq!(
1880 sent["options"],
1881 json!({ "reasoning": false, "reasoning_budget": 2_048, "temperature": 0.25 })
1882 );
1883 }
1884
1885 #[test]
1886 fn a_summary_answers_with_the_prose_and_carries_no_schema() {
1887 let session = testing::install(|_name, params| {
1888 assert_eq!(params["operation"], json!("summarize"));
1889 assert!(params.get("schema").is_none());
1890
1891 Ok(json!({ "data": "A refund was agreed.", "metadata": { "output_tokens": 5 } }))
1892 });
1893
1894 let written = summarize(json!("A long thread."), "One sentence.", Options::default())
1895 .expect("a summary answers with prose");
1896
1897 assert_eq!(written.data, "A refund was agreed.");
1898 assert_eq!(written.metadata.output_tokens, 5);
1899 assert_eq!(session.calls().len(), 1);
1900 }
1901
1902 #[test]
1903 fn a_pending_document_is_uploaded_before_the_operation_reads_it() {
1904 let session = testing::install(|name, _params| {
1905 if name == UPLOAD_EPHEMERAL {
1906 return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
1907 }
1908
1909 Ok(answered())
1910 });
1911
1912 let _: Execution<Value> = extract(
1913 json!({ "file_hash": "abc", "pending": true }),
1914 "Read it.",
1915 json!({ "type": "object" }),
1916 Options::default(),
1917 )
1918 .unwrap();
1919
1920 let calls = session.calls();
1921
1922 assert_eq!(calls.len(), 2);
1923 assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
1924 assert_eq!(calls[1].name, ORCHESTRATOR);
1925 assert_eq!(
1926 calls[1].params["input"],
1927 json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }),
1928 "the operation reads the handle the upload answered with"
1929 );
1930 }
1931
1932 #[test]
1933 fn a_pending_document_is_read_the_way_the_caller_asked_for_it() {
1934 let session = testing::install(|name, _params| {
1935 if name == UPLOAD_EPHEMERAL {
1936 return Ok(json!({
1937 "file_hash": "ffce20f1",
1938 "filename": "contract.pdf",
1939 "mime_type": "application/pdf",
1940 "size": 1_234,
1941 "storage_path": "acme/ephemeral/ffce20f1"
1942 }));
1943 }
1944
1945 Ok(answered())
1946 });
1947
1948 let _: Execution<Value> = extract(
1949 json!({
1950 "file_hash": "staged",
1951 "first_page": 12,
1952 "last_page": 30,
1953 "pending": true,
1954 "deliver_as": "text",
1955 "storage_path": "acme/staged/staged"
1956 }),
1957 "Read it.",
1958 json!({ "type": "object" }),
1959 Options::default(),
1960 )
1961 .unwrap();
1962
1963 let calls = session.calls();
1964 let sent = calls[1].params["input"].clone();
1965
1966 assert_eq!(
1967 sent["deliver_as"],
1968 json!("text"),
1969 "the caller said how the file was to be sent"
1970 );
1971 assert_eq!(
1972 sent["first_page"],
1973 json!(12),
1974 "the caller asked for a range"
1975 );
1976 assert_eq!(sent["last_page"], json!(30), "the caller asked for a range");
1977 assert_eq!(
1978 sent["file_hash"],
1979 json!("ffce20f1"),
1980 "the file is the one the upload stored"
1981 );
1982 assert_eq!(
1983 sent["storage_path"],
1984 json!("acme/ephemeral/ffce20f1"),
1985 "the file is read from where the upload put it"
1986 );
1987 assert_eq!(sent["filename"], json!("contract.pdf"));
1988 assert_eq!(sent["mime_type"], json!("application/pdf"));
1989 assert_eq!(sent["size"], json!(1_234));
1990 assert!(
1991 sent.get("pending").is_none(),
1992 "the file is stored, so the handle may not still call itself pending"
1993 );
1994 }
1995
1996 #[test]
1997 fn a_document_that_is_already_stored_is_read_where_it_is() {
1998 let session = testing::install(|_name, _params| Ok(answered()));
1999
2000 let handle = json!({ "file_hash": "abc", "mime_type": "application/pdf" });
2001
2002 let _: Execution<Value> = extract(
2003 handle.clone(),
2004 "Read it.",
2005 json!({ "type": "object" }),
2006 Options::default(),
2007 )
2008 .unwrap();
2009
2010 let calls = session.calls();
2011
2012 assert_eq!(calls.len(), 1, "nothing was uploaded");
2013 assert_eq!(calls[0].params["input"], handle);
2014 }
2015
2016 #[test]
2017 fn a_list_of_documents_is_uploaded_item_by_item() {
2018 let session = testing::install(|name, params| {
2019 if name == UPLOAD_EPHEMERAL {
2020 let hash = params["file_hash"].as_str().unwrap_or_default();
2021
2022 return Ok(json!({
2023 "file_hash": hash,
2024 "storage_path": format!("ephemeral/{hash}")
2025 }));
2026 }
2027
2028 Ok(answered())
2029 });
2030
2031 let _: Execution<Value> = extract(
2032 json!([
2033 { "file_hash": "one", "pending": true },
2034 { "file_hash": "two", "mime_type": "image/png" },
2035 { "file_hash": "three", "pending": true }
2036 ]),
2037 "Read them.",
2038 json!({ "type": "object" }),
2039 Options::default(),
2040 )
2041 .unwrap();
2042
2043 let calls = session.calls();
2044
2045 assert_eq!(calls.len(), 3, "two uploads and the operation");
2046 assert_eq!(
2047 calls[2].params["input"],
2048 json!([
2049 { "file_hash": "one", "storage_path": "ephemeral/one" },
2050 { "file_hash": "two", "mime_type": "image/png" },
2051 { "file_hash": "three", "storage_path": "ephemeral/three" }
2052 ])
2053 );
2054 }
2055
2056 #[test]
2057 fn a_handle_is_pending_only_while_it_says_so_and_carries_a_hash_to_upload_by() {
2058 assert!(is_pending(&json!({ "file_hash": "abc", "pending": true })));
2059 assert!(!is_pending(&json!({ "file_hash": "abc" })));
2060 assert!(!is_pending(&json!({ "pending": true })));
2061 assert!(!is_pending(&json!({ "file_hash": "", "pending": true })));
2062 assert!(!is_pending(
2063 &json!({ "file_hash": "abc", "pending": "yes" })
2064 ));
2065 assert!(!is_pending(&json!("some words")));
2066 assert!(!is_pending(&json!([
2067 { "file_hash": "abc", "pending": true }
2068 ])));
2069 }
2070
2071 #[test]
2072 fn an_answer_that_reports_nothing_about_its_cost_is_still_an_answer() {
2073 let _session = testing::install(|_name, _params| Ok(json!({ "data": "done" })));
2074
2075 let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
2076
2077 assert_eq!(written.data, "done");
2078 assert_eq!(written.metadata, Metadata::default());
2079 }
2080
2081 #[test]
2082 fn reasoning_reaches_the_caller_when_the_run_reported_it() {
2083 let _session = testing::install(|_name, _params| {
2084 Ok(json!({
2085 "data": "done",
2086 "metadata": {
2087 "input_tokens": 9,
2088 "output_tokens": 4,
2089 "reasoning": "Read the total from the last line.",
2090 "reasoning_tokens": 120
2091 }
2092 }))
2093 });
2094
2095 let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
2096
2097 assert_eq!(written.metadata.reasoning_tokens, Some(120));
2098 assert_eq!(
2099 written.metadata.reasoning.as_deref(),
2100 Some("Read the total from the last line.")
2101 );
2102 }
2103
2104 #[test]
2105 fn a_run_reports_how_each_file_travelled_in_the_order_the_files_were_given() {
2106 let _session = testing::install(|_name, _params| {
2107 Ok(json!({
2108 "data": "done",
2109 "metadata": {
2110 "input_tokens": 9,
2111 "output_tokens": 4,
2112 "delivery": [
2113 {
2114 "filename": "contract.pdf",
2115 "delivered_as": "text",
2116 "first_page": 40,
2117 "last_page": 52,
2118 "transcribed_pages": [41, 44],
2119 "fallback": null
2120 },
2121 {
2122 "filename": "drawings.pdf",
2123 "delivered_as": "document",
2124 "first_page": null,
2125 "last_page": null,
2126 "transcribed_pages": [],
2127 "fallback": {
2128 "reason": "transcription_failed",
2129 "pages": [3, 7],
2130 "message": "page 3: timed out; page 7: blank answer"
2131 }
2132 },
2133 {
2134 "filename": "site.jpg",
2135 "delivered_as": "image",
2136 "first_page": null,
2137 "last_page": null,
2138 "transcribed_pages": [],
2139 "fallback": null
2140 }
2141 ]
2142 }
2143 }))
2144 });
2145
2146 let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
2147
2148 assert_eq!(
2149 written.metadata.delivery,
2150 vec![
2151 FileDelivery {
2152 filename: "contract.pdf".to_string(),
2153 delivered_as: DeliveredAs::Text,
2154 pages: Some(Pages::new(40, 52)),
2155 transcribed_pages: vec![41, 44],
2156 fallback: None,
2157 },
2158 FileDelivery {
2159 filename: "drawings.pdf".to_string(),
2160 delivered_as: DeliveredAs::Document,
2161 pages: None,
2162 transcribed_pages: Vec::new(),
2163 fallback: Some(DeliveryFallback {
2164 reason: "transcription_failed".to_string(),
2165 pages: vec![3, 7],
2166 message: "page 3: timed out; page 7: blank answer".to_string(),
2167 }),
2168 },
2169 FileDelivery {
2170 filename: "site.jpg".to_string(),
2171 delivered_as: DeliveredAs::Image,
2172 pages: None,
2173 transcribed_pages: Vec::new(),
2174 fallback: None,
2175 },
2176 ]
2177 );
2178 assert_eq!(
2179 written.metadata.input_tokens, 9,
2180 "the members a result already had read as they did"
2181 );
2182 }
2183
2184 #[test]
2185 fn an_answer_without_a_delivery_report_carries_none() {
2186 for metadata in [
2187 json!({ "input_tokens": 1 }),
2188 json!({ "delivery": null }),
2189 json!({ "delivery": "document" }),
2190 json!({ "delivery": { "filename": "contract.pdf", "delivered_as": "text" } }),
2191 ] {
2192 let _session = testing::install(move |_name, _params| {
2193 Ok(json!({ "data": "done", "metadata": metadata.clone() }))
2194 });
2195
2196 let written = summarize(json!("text"), "One sentence.", Options::default())
2197 .expect("a report that cannot be read never fails the run");
2198
2199 assert!(written.metadata.delivery.is_empty());
2200 }
2201 }
2202
2203 #[test]
2204 fn a_delivery_entry_that_cannot_be_read_is_left_out_and_the_rest_are_kept() {
2205 let delivery = delivery_of(Some(&json!([
2206 "contract.pdf",
2207 { "filename": "no-way.pdf" },
2208 { "filename": "audio.mp3", "delivered_as": "audio" },
2209 { "delivered_as": "text" },
2210 { "filename": 7, "delivered_as": "text" },
2211 {
2212 "filename": "kept.pdf",
2213 "delivered_as": "text",
2214 "first_page": 4,
2215 "transcribed_pages": ["5", -1, 0, 6, 4_294_967_296_u64, null]
2216 }
2217 ])));
2218
2219 assert_eq!(
2220 delivery,
2221 vec![FileDelivery {
2222 filename: "kept.pdf".to_string(),
2223 delivered_as: DeliveredAs::Text,
2224 pages: None,
2225 transcribed_pages: vec![6],
2226 fallback: None,
2227 }],
2228 "a range with one end is not a range, and only whole pages from 1 are pages"
2229 );
2230 }
2231
2232 #[test]
2233 fn a_fallback_that_is_reported_is_never_lost_to_a_missing_member() {
2234 let delivery = delivery_of(Some(&json!([
2235 {
2236 "filename": "contract.pdf",
2237 "delivered_as": "document",
2238 "fallback": { "reason": "transcription_failed" }
2239 },
2240 {
2241 "filename": "drawings.pdf",
2242 "delivered_as": "document",
2243 "fallback": "transcription_failed"
2244 }
2245 ])));
2246
2247 assert_eq!(
2248 delivery[0].fallback,
2249 Some(DeliveryFallback {
2250 reason: "transcription_failed".to_string(),
2251 pages: Vec::new(),
2252 message: String::new(),
2253 })
2254 );
2255 assert_eq!(
2256 delivery[1].fallback, None,
2257 "a fallback that is not an object says nothing that can be read"
2258 );
2259 assert!(delivery[0].transcribed_pages.is_empty());
2260 }
2261
2262 #[test]
2263 fn an_operation_with_nothing_to_do_is_refused_before_anything_is_sent() {
2264 let session = testing::install(|_name, _params| Ok(answered()));
2265
2266 let missing_input = extract::<Value>(
2267 json!(null),
2268 "Read it.",
2269 json!({ "type": "object" }),
2270 Options::default(),
2271 )
2272 .unwrap_err();
2273
2274 let missing_prompt = extract::<Value>(
2275 json!("text"),
2276 " ",
2277 json!({ "type": "object" }),
2278 Options::default(),
2279 )
2280 .unwrap_err();
2281
2282 let missing_schema =
2283 extract::<Value>(json!("text"), "Read it.", json!([]), Options::default()).unwrap_err();
2284
2285 let missing_summary_input =
2286 summarize(json!(""), "One sentence.", Options::default()).unwrap_err();
2287
2288 for refusal in [
2289 &missing_input,
2290 &missing_prompt,
2291 &missing_schema,
2292 &missing_summary_input,
2293 ] {
2294 assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
2295 }
2296
2297 assert!(session.calls().is_empty());
2298 }
2299
2300 #[test]
2301 fn a_transcription_writes_its_own_schema_and_prompt() {
2302 let session = testing::install(|_name, _params| {
2303 Ok(json!({
2304 "data": { "language": "en", "transcript": "Hello." },
2305 "metadata": { "input_tokens": 400, "output_tokens": 12 }
2306 }))
2307 });
2308
2309 let heard = transcribe(
2310 json!({ "file_hash": "abc", "mime_type": "AUDIO/MPEG" }),
2311 TranscribeOptions {
2312 include_transcript: true,
2313 ..Default::default()
2314 },
2315 Options::default(),
2316 )
2317 .expect("an uppercase mime type is the same mime type");
2318
2319 assert_eq!(heard.data.language, "en");
2320 assert_eq!(heard.data.transcript.as_deref(), Some("Hello."));
2321 assert_eq!(heard.data.summary, None);
2322 assert!(heard.data.participants.is_empty());
2323
2324 let sent = session.calls()[0].params.clone();
2325
2326 assert_eq!(sent["operation"], json!("extract"));
2327 assert_eq!(
2328 sent["schema"]["required"],
2329 json!(["language", "transcript"])
2330 );
2331 assert_eq!(sent["schema"]["properties"]["transcript"]["type"], "string");
2332 assert_eq!(
2333 sent["prompt"],
2334 json!(
2335 "Analyze this audio/video file and provide:\n\
2336 - A complete transcript of all spoken content\n\
2337 - The detected language code (ISO 639-1 format)\n"
2338 )
2339 );
2340 }
2341
2342 #[test]
2343 fn named_participants_reach_both_the_prompt_and_the_schema() {
2344 let session = testing::install(|_name, _params| {
2345 Ok(json!({ "data": { "language": "en", "participants": ["Customer", "Agent"] } }))
2346 });
2347
2348 let heard = transcribe(
2349 json!({ "file_hash": "abc", "mime_type": "video/mp4" }),
2350 TranscribeOptions {
2351 include_transcript: true,
2352 include_timestamps: true,
2353 summarize: true,
2354 participants: Participants::Named(vec![
2355 "Customer".to_string(),
2356 "Agent".to_string(),
2357 ]),
2358 },
2359 Options::default(),
2360 )
2361 .unwrap();
2362
2363 assert_eq!(heard.data.participants, ["Customer", "Agent"]);
2364
2365 let sent = session.calls()[0].params.clone();
2366 let prompt = sent["prompt"].as_str().unwrap_or_default().to_string();
2367
2368 assert_eq!(
2369 sent["schema"]["required"],
2370 json!(["language", "transcript", "summary", "participants"])
2371 );
2372 assert_eq!(
2373 sent["schema"]["properties"]["participants"]["items"]["type"],
2374 json!("string")
2375 );
2376 assert!(prompt.contains("identifying these participants: Customer, Agent. "));
2377 assert!(prompt.contains("Include timestamps in [MM:SS] format"));
2378 assert!(
2379 prompt.contains("- A concise summary highlighting key points from each participant\n")
2380 );
2381 assert!(prompt
2382 .contains("- Identify and distinguish between these participants: Customer, Agent\n"));
2383 }
2384
2385 #[test]
2386 fn detected_participants_are_labelled_rather_than_named() {
2387 let session =
2388 testing::install(|_name, _params| Ok(json!({ "data": { "language": "en" } })));
2389
2390 let _ = transcribe(
2391 json!({ "file_hash": "abc", "mime_type": "audio/wav" }),
2392 TranscribeOptions {
2393 include_transcript: true,
2394 participants: Participants::Detect,
2395 ..Default::default()
2396 },
2397 Options::default(),
2398 )
2399 .unwrap();
2400
2401 let prompt = session.calls()[0].params["prompt"]
2402 .as_str()
2403 .unwrap_or_default()
2404 .to_string();
2405
2406 assert!(prompt.contains("label participants as Participant 1, Participant 2, etc."));
2407 assert!(prompt.contains("Format each line as \"Participant Name: text\".\n"));
2408 assert!(prompt.contains("- Identify and list all distinct participants in the audio\n"));
2409 }
2410
2411 #[test]
2412 fn naming_nobody_asks_for_the_same_thing_as_detecting() {
2413 let wanted = |participants| TranscribeOptions {
2414 include_transcript: true,
2415 participants,
2416 ..Default::default()
2417 };
2418
2419 assert_eq!(
2420 transcribe_prompt(&wanted(Participants::Named(Vec::new()))),
2421 transcribe_prompt(&wanted(Participants::Detect))
2422 );
2423 assert_eq!(
2424 transcribe_schema(&wanted(Participants::Named(Vec::new()))),
2425 transcribe_schema(&wanted(Participants::Detect))
2426 );
2427 }
2428
2429 #[test]
2430 fn a_transcription_that_cannot_run_is_refused_before_anything_is_sent() {
2431 let session = testing::install(|_name, _params| Ok(answered()));
2432
2433 let audio = json!({ "file_hash": "abc", "mime_type": "audio/mpeg" });
2434
2435 let nothing_wanted = transcribe(
2436 audio.clone(),
2437 TranscribeOptions::default(),
2438 Options::default(),
2439 )
2440 .unwrap_err();
2441
2442 let not_media = transcribe(
2443 json!({ "file_hash": "abc", "mime_type": "application/pdf" }),
2444 TranscribeOptions {
2445 include_transcript: true,
2446 ..Default::default()
2447 },
2448 Options::default(),
2449 )
2450 .unwrap_err();
2451
2452 let not_a_handle = transcribe(
2453 json!("some words"),
2454 TranscribeOptions {
2455 summarize: true,
2456 ..Default::default()
2457 },
2458 Options::default(),
2459 )
2460 .unwrap_err();
2461
2462 for refusal in [¬hing_wanted, ¬_media, ¬_a_handle] {
2463 assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
2464 }
2465
2466 assert!(session.calls().is_empty());
2467 }
2468
2469 #[test]
2470 fn a_page_transcription_asks_for_the_transcribe_operation_with_the_range_and_no_prompt() {
2471 let session = testing::install(|_name, _params| {
2472 Ok(json!({
2473 "data": {
2474 "pages": [
2475 { "page": 41, "text": "Scope of Work" },
2476 { "page": 42, "error": "the answer carries no pages" }
2477 ]
2478 },
2479 "metadata": {
2480 "delivery": null,
2481 "input_tokens": 0,
2482 "output_tokens": 0,
2483 "reasoning_tokens": 0
2484 }
2485 }))
2486 });
2487
2488 let read = transcribe_pages(
2489 &stored(),
2490 Some(Pages::new(40, 52)),
2491 TranscribePagesOptions::default(),
2492 )
2493 .unwrap();
2494
2495 let calls = session.calls();
2496
2497 assert_eq!(calls.len(), 1);
2498 assert_eq!(calls[0].name, ORCHESTRATOR);
2499 assert_eq!(
2500 calls[0].params,
2501 json!({
2502 "operation": "transcribe",
2503 "input": {
2504 "file_hash": "ffce20f1",
2505 "filename": "contract.pdf",
2506 "mime_type": "application/pdf",
2507 "size": 1_234,
2508 "storage_path": "acme/documents/ffce20f1",
2509 "first_page": 40,
2510 "last_page": 52
2511 },
2512 "options": { "reasoning": true },
2513 "regenerate": false
2514 }),
2515 "no prompt, schema, model or delivery: the instructions are the platform's"
2516 );
2517
2518 assert_eq!(
2519 read.data,
2520 vec![
2521 PageTranscription::Read {
2522 page: 41,
2523 text: "Scope of Work".to_string()
2524 },
2525 PageTranscription::Unread {
2526 page: 42,
2527 error: "the answer carries no pages".to_string()
2528 },
2529 ]
2530 );
2531 assert_eq!(read.metadata.input_tokens, 0);
2532 assert!(read.metadata.delivery.is_empty());
2533 }
2534
2535 #[test]
2536 fn a_page_transcription_carries_only_the_whole_file_and_the_options_it_was_given() {
2537 let session = testing::install(|_name, _params| Ok(json!({ "data": { "pages": [] } })));
2538
2539 let read = transcribe_pages(
2540 &stored(),
2541 None,
2542 TranscribePagesOptions {
2543 regenerate: true,
2544 timeout: Some(Duration::from_secs(90)),
2545 transcription: None,
2546 },
2547 )
2548 .unwrap();
2549
2550 let sent = session.calls()[0].params.clone();
2551
2552 assert!(read.data.is_empty());
2553 assert!(sent["input"].get("first_page").is_none());
2554 assert!(sent["input"].get("last_page").is_none());
2555 assert_eq!(sent["regenerate"], json!(true));
2556 assert_eq!(sent["timeout"], json!(90_000));
2557 assert_eq!(sent["options"], json!({ "reasoning": true }));
2558 }
2559
2560 #[test]
2561 fn a_page_with_no_text_is_answered_as_unread_never_as_text_that_is_not_there() {
2562 let _session = testing::install(|_name, _params| {
2563 Ok(json!({
2564 "data": {
2565 "pages": [
2566 { "page": 7, "text": "" },
2567 { "page": 8, "error": "the model timed out", "text": "Scope of" },
2568 { "page": 9 },
2569 { "page": 10, "transcriptions": ["Scope of Work", "Scope of Work"] },
2570 { "page": 11, "error": null, "text": "Clause 4" },
2571 { "page": 12, "error": 500, "text": "Clause 5" },
2572 { "page": 13, "text": null },
2573 { "text": "a page with no number" },
2574 { "page": "14", "text": "a number that is a string" },
2575 "page 15"
2576 ]
2577 }
2578 }))
2579 });
2580
2581 let read = transcribe_pages(&stored(), None, TranscribePagesOptions::default()).unwrap();
2582
2583 let unread = |page: u32, error: &str| PageTranscription::Unread {
2584 page,
2585 error: error.to_string(),
2586 };
2587 let read_as = |page: u32, text: &str| PageTranscription::Read {
2588 page,
2589 text: text.to_string(),
2590 };
2591
2592 assert_eq!(
2593 read.data,
2594 vec![
2595 read_as(7, ""),
2596 unread(8, "the model timed out"),
2597 unread(9, NO_TRANSCRIPTION),
2598 unread(10, NO_TRANSCRIPTION),
2599 read_as(11, "Clause 4"),
2600 read_as(12, "Clause 5"),
2601 unread(13, NO_TRANSCRIPTION),
2602 ]
2603 );
2604 assert_eq!(read.data[1].text(), None, "an error wins over partial text");
2605 assert_eq!(read.data[0].text(), Some(""), "a blank page is a read");
2606 assert_eq!(read.data[2].page(), 9);
2607 }
2608
2609 #[test]
2610 fn an_answer_without_a_list_of_pages_has_no_pages() {
2611 for data in [
2612 json!(null),
2613 json!({}),
2614 json!({ "pages": "none" }),
2615 json!([]),
2616 ] {
2617 let _session =
2618 testing::install(move |_name, _params| Ok(json!({ "data": data.clone() })));
2619
2620 let read =
2621 transcribe_pages(&stored(), None, TranscribePagesOptions::default()).unwrap();
2622
2623 assert!(read.data.is_empty());
2624 }
2625 }
2626
2627 #[test]
2628 fn a_page_transcription_of_anything_but_a_pdf_is_refused_before_the_host_is_asked() {
2629 let session = testing::install(|_name, _params| Ok(json!({ "data": { "pages": [] } })));
2630
2631 let spreadsheet = transcribe_pages(
2632 &DocumentHandle {
2633 filename: "rates.csv".to_string(),
2634 mime_type: "text/csv".to_string(),
2635 ..stored()
2636 },
2637 None,
2638 TranscribePagesOptions::default(),
2639 )
2640 .unwrap_err();
2641
2642 let unstored = transcribe_pages(
2643 &DocumentHandle {
2644 file_hash: String::new(),
2645 ..stored()
2646 },
2647 None,
2648 TranscribePagesOptions::default(),
2649 )
2650 .unwrap_err();
2651
2652 for refusal in [&spreadsheet, &unstored] {
2653 assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
2654 }
2655
2656 assert!(spreadsheet.message().contains("reads the pages of a PDF"));
2657 assert!(session.calls().is_empty());
2658
2659 transcribe_pages(
2660 &DocumentHandle {
2661 mime_type: "Application/PDF; version=1.7".to_string(),
2662 ..stored()
2663 },
2664 None,
2665 TranscribePagesOptions::default(),
2666 )
2667 .expect("a PDF type with parameters or in capitals is still a PDF");
2668
2669 assert_eq!(session.calls().len(), 1);
2670 }
2671
2672 #[test]
2673 fn an_enrolment_answers_with_the_id_the_face_was_filed_under() {
2674 let session = testing::install(|name, params| {
2675 assert_eq!(name, FACE_ENROLL);
2676 assert_eq!(params["subject_id"], json!("EMP-42"));
2677 assert_eq!(params["image"], json!("iVBORw0KGgo"));
2678
2679 Ok(json!({ "face_id": "FACE-1" }))
2680 });
2681
2682 assert_eq!(
2683 enroll_face("EMP-42", json!("iVBORw0KGgo")).unwrap(),
2684 "FACE-1"
2685 );
2686 assert_eq!(session.calls().len(), 1);
2687 }
2688
2689 #[test]
2690 fn an_enrolment_uploads_a_pending_image_first() {
2691 let session = testing::install(|name, _params| {
2692 if name == UPLOAD_EPHEMERAL {
2693 return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
2694 }
2695
2696 Ok(json!({ "face_id": "FACE-1" }))
2697 });
2698
2699 enroll_face("EMP-42", json!({ "file_hash": "abc", "pending": true })).unwrap();
2700
2701 let calls = session.calls();
2702
2703 assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
2704 assert_eq!(
2705 calls[1].params["image"],
2706 json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" })
2707 );
2708 }
2709
2710 #[test]
2711 fn an_enrolment_without_a_subject_or_an_image_is_refused() {
2712 let session = testing::install(|_name, _params| Ok(json!({ "face_id": "FACE-1" })));
2713
2714 assert_eq!(
2715 enroll_face(" ", json!("image"))
2716 .unwrap_err()
2717 .code()
2718 .as_str(),
2719 "INVALID_TOOL_INPUT"
2720 );
2721 assert_eq!(
2722 enroll_face("EMP-42", json!(null))
2723 .unwrap_err()
2724 .code()
2725 .as_str(),
2726 "INVALID_TOOL_INPUT"
2727 );
2728 assert!(session.calls().is_empty());
2729 }
2730
2731 #[test]
2732 fn an_enrolment_that_answers_without_an_id_is_reported_rather_than_guessed_at() {
2733 let _session = testing::install(|_name, _params| Ok(json!({ "enrolled": true })));
2734
2735 let error = enroll_face("EMP-42", json!("image")).unwrap_err();
2736
2737 assert!(matches!(error, Error::Json(_)));
2738 assert_eq!(error.code().as_str(), "ACTION_FAILED");
2739 }
2740
2741 #[test]
2742 fn a_search_carries_only_the_narrowing_it_was_given() {
2743 let session = testing::install(|name, params| {
2744 assert_eq!(name, FACE_SEARCH);
2745
2746 Ok(json!({ "matches": params["options"].clone() }))
2747 });
2748
2749 let wide: Value = search_face(json!("image"), FaceSearch::default()).unwrap();
2750
2751 let narrow: Value = search_face(
2752 json!("image"),
2753 FaceSearch {
2754 max_faces: Some(3),
2755 similarity_threshold: Some(92.5),
2756 },
2757 )
2758 .unwrap();
2759
2760 assert_eq!(wide["matches"], json!({}), "the platform's own defaults");
2761 assert_eq!(
2762 narrow["matches"],
2763 json!({ "max_faces": 3, "similarity_threshold": 92.5 })
2764 );
2765 assert_eq!(session.calls().len(), 2);
2766 }
2767
2768 #[test]
2769 fn a_search_answers_with_the_type_the_call_asked_for() {
2770 #[derive(Debug, Deserialize, PartialEq)]
2771 struct Match {
2772 similarity: f64,
2773 subject_id: String,
2774 }
2775
2776 let _session = testing::install(|_name, _params| {
2777 Ok(json!([{ "similarity": 99.1, "subject_id": "EMP-42" }]))
2778 });
2779
2780 let found: Vec<Match> = search_face(json!("image"), FaceSearch::default()).unwrap();
2781
2782 assert_eq!(
2783 found,
2784 vec![Match {
2785 similarity: 99.1,
2786 subject_id: "EMP-42".to_string()
2787 }]
2788 );
2789 }
2790
2791 #[test]
2792 fn a_search_with_no_image_is_refused_before_anything_is_sent() {
2793 let session = testing::install(|_name, _params| Ok(json!([])));
2794
2795 let error = search_face::<Value>(json!(null), FaceSearch::default()).unwrap_err();
2796
2797 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
2798 assert!(session.calls().is_empty());
2799 }
2800
2801 #[test]
2802 fn a_removal_reports_the_ids_the_platform_says_it_removed() {
2803 let session = testing::install(|name, params| {
2804 assert_eq!(name, FACE_DELETE);
2805 assert_eq!(params["face_ids"], json!(["FACE-1", "FACE-2"]));
2806
2807 Ok(json!({ "deleted": ["FACE-1"] }))
2808 });
2809
2810 let removed = delete_face(&["FACE-1".to_string(), "FACE-2".to_string()]).unwrap();
2811
2812 assert_eq!(removed, ["FACE-1"]);
2813 assert_eq!(session.calls().len(), 1);
2814 }
2815
2816 #[test]
2817 fn a_removal_reads_a_bare_list_of_ids_as_well() {
2818 let _session = testing::install(|_name, _params| Ok(json!(["FACE-1", "FACE-2"])));
2819
2820 assert_eq!(
2821 delete_face(&["FACE-1".to_string()]).unwrap(),
2822 ["FACE-1", "FACE-2"]
2823 );
2824 }
2825
2826 #[test]
2827 fn a_removal_that_names_nothing_removed_answers_with_nothing() {
2828 let _session = testing::install(|_name, _params| Ok(json!({ "ok": true })));
2829
2830 assert!(delete_face(&["FACE-1".to_string()]).unwrap().is_empty());
2831 }
2832
2833 #[test]
2834 fn a_removal_with_no_ids_is_refused_before_anything_is_sent() {
2835 let session = testing::install(|_name, _params| Ok(json!([])));
2836
2837 let error = delete_face(&[]).unwrap_err();
2838
2839 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
2840 assert!(session.calls().is_empty());
2841 }
2842
2843 #[test]
2844 fn what_the_host_said_survives_into_every_failure() {
2845 let _session = testing::install(|_name, _params| Err(Error::failed("the engine is busy")));
2846
2847 let operation = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
2848 let enrolment = enroll_face("EMP-42", json!("image")).unwrap_err();
2849 let search = search_face::<Value>(json!("image"), FaceSearch::default()).unwrap_err();
2850 let removal = delete_face(&["FACE-1".to_string()]).unwrap_err();
2851
2852 for failure in [&operation, &enrolment, &search, &removal] {
2853 assert!(failure.message().contains("the engine is busy"));
2854 assert!(!failure.fault().hint().is_empty(), "and says what to do");
2855 }
2856 }
2857
2858 #[test]
2859 fn an_answer_that_does_not_fit_the_type_is_reported_as_having_run() {
2860 let _session = testing::install(|_name, _params| Ok(json!({ "data": { "total": 240.0 } })));
2861
2862 let error = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
2863
2864 assert!(matches!(error, Error::Json(_)));
2865 assert_eq!(error.code().as_str(), "ACTION_FAILED");
2866 assert!(error
2867 .fault()
2868 .hint()
2869 .contains("rather than running it again"));
2870 }
2871
2872 #[test]
2873 fn a_timeout_travels_as_the_milliseconds_the_wire_carries() {
2874 assert_eq!(milliseconds(Duration::from_secs(30)), 30_000);
2875 assert_eq!(milliseconds(Duration::from_millis(1)), 1);
2876 assert_eq!(milliseconds(Duration::MAX), u64::MAX);
2877 }
2878
2879 #[test]
2880 fn every_model_names_itself_as_the_wire_spells_it() {
2881 assert_eq!(Model::Lite.to_string(), "lite");
2882 assert_eq!(Model::Medium.to_string(), "medium");
2883 assert_eq!(Model::Large.to_string(), "large");
2884 assert_eq!(Model::Xl.to_string(), "xl");
2885 }
2886}