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#[derive(Clone, Debug)]
294pub struct Options {
295 pub model: Option<Model>,
297
298 pub system_prompt: Option<String>,
301
302 pub temperature: Option<f64>,
305
306 pub reasoning: bool,
309
310 pub reasoning_budget: Option<u32>,
313
314 pub regenerate: bool,
317
318 pub timeout: Option<Duration>,
320}
321
322impl Default for Options {
323 fn default() -> Options {
325 Options {
326 model: None,
327 system_prompt: None,
328 temperature: None,
329 reasoning: true,
330 reasoning_budget: None,
331 regenerate: false,
332 timeout: None,
333 }
334 }
335}
336
337#[derive(Clone, Debug, Default, PartialEq, Eq)]
339pub enum Participants {
340 #[default]
342 Ignore,
343
344 Detect,
347
348 Named(Vec<String>),
351}
352
353impl Participants {
354 fn wanted(&self) -> bool {
356 !matches!(self, Participants::Ignore)
357 }
358
359 fn names(&self) -> Option<String> {
361 match self {
362 Participants::Named(names) if !names.is_empty() => Some(names.join(", ")),
363 _ => None,
364 }
365 }
366}
367
368#[derive(Clone, Debug, Default)]
373pub struct TranscribeOptions {
374 pub include_transcript: bool,
376
377 pub include_timestamps: bool,
380
381 pub summarize: bool,
383
384 pub participants: Participants,
386}
387
388#[derive(Clone, Debug, Default, Deserialize)]
393#[serde(default)]
394pub struct Transcript {
395 pub language: String,
397
398 pub transcript: Option<String>,
400
401 pub summary: Option<String>,
403
404 pub participants: Vec<String>,
406}
407
408#[derive(Clone, Debug, Default)]
414pub struct TranscribePagesOptions {
415 pub regenerate: bool,
419
420 pub timeout: Option<Duration>,
422}
423
424#[derive(Clone, Debug, PartialEq, Eq)]
430pub enum PageTranscription {
431 Read {
433 page: u32,
435
436 text: String,
440 },
441
442 Unread {
444 page: u32,
446
447 error: String,
449 },
450}
451
452impl PageTranscription {
453 pub fn page(&self) -> u32 {
455 match self {
456 PageTranscription::Read { page, .. } | PageTranscription::Unread { page, .. } => *page,
457 }
458 }
459
460 pub fn text(&self) -> Option<&str> {
462 match self {
463 PageTranscription::Read { text, .. } => Some(text),
464 PageTranscription::Unread { .. } => None,
465 }
466 }
467}
468
469#[derive(Clone, Debug)]
471pub struct Execution<T> {
472 pub data: T,
474
475 pub metadata: Metadata,
477}
478
479#[derive(Clone, Debug, Default, PartialEq, Eq)]
481pub struct Metadata {
482 pub input_tokens: u64,
484
485 pub output_tokens: u64,
487
488 pub reasoning_tokens: Option<u64>,
490
491 pub reasoning: Option<String>,
493
494 pub delivery: Vec<FileDelivery>,
498}
499
500#[derive(Clone, Debug, PartialEq, Eq)]
557pub struct FileDelivery {
558 pub filename: String,
560
561 pub delivered_as: DeliveredAs,
563
564 pub pages: Option<Pages>,
567
568 pub transcribed_pages: Vec<u32>,
571
572 pub fallback: Option<DeliveryFallback>,
575}
576
577#[non_exhaustive]
585#[derive(Clone, Copy, Debug, PartialEq, Eq)]
586pub enum DeliveredAs {
587 Document,
590 Text,
593 Image,
595}
596
597#[derive(Clone, Debug, Default, PartialEq, Eq)]
599pub struct DeliveryFallback {
600 pub reason: String,
605
606 pub pages: Vec<u32>,
608
609 pub message: String,
611}
612
613#[derive(Clone, Debug, Default)]
615pub struct FaceSearch {
616 pub max_faces: Option<u32>,
618
619 pub similarity_threshold: Option<f64>,
622}
623
624pub fn extract<T: DeserializeOwned>(
659 input: Value,
660 prompt: &str,
661 schema: Value,
662 options: Options,
663) -> Result<Execution<T>, Error> {
664 refuse_empty(
665 &input,
666 "extract needs something to read.",
667 "Pass the text, the document handle, or the object the extraction is to read.",
668 )?;
669 refuse_empty_prompt(prompt, "extract")?;
670
671 if !schema.is_object() {
672 return Err(
673 Error::invalid("extract needs a JSON Schema object describing the answer.").hint(
674 "Pass a schema object naming the type and the properties the answer is to have.",
675 ),
676 );
677 }
678
679 run("extract", input, Some(prompt), Some(schema), &options)
680}
681
682pub fn summarize(input: Value, prompt: &str, options: Options) -> Result<Execution<String>, Error> {
701 refuse_empty(
702 &input,
703 "summarize needs something to read.",
704 "Pass the text, the document handle, or the object the summary is to be written from.",
705 )?;
706 refuse_empty_prompt(prompt, "summarize")?;
707
708 run("summarize", input, Some(prompt), None, &options)
709}
710
711pub fn transcribe(
746 document: Value,
747 wanted: TranscribeOptions,
748 options: Options,
749) -> Result<Execution<Transcript>, Error> {
750 refuse_unless_media(&document)?;
751
752 if !wanted.include_transcript && !wanted.summarize {
753 return Err(
754 Error::invalid("transcribe needs to be told what to produce.")
755 .hint("Set include_transcript, summarize, or both."),
756 );
757 }
758
759 let prompt = transcribe_prompt(&wanted);
760
761 run(
762 "extract",
763 document,
764 Some(&prompt),
765 Some(transcribe_schema(&wanted)),
766 &options,
767 )
768}
769
770pub fn transcribe_pages(
840 document: &DocumentHandle,
841 pages: Option<Pages>,
842 options: TranscribePagesOptions,
843) -> Result<Execution<Vec<PageTranscription>>, Error> {
844 refuse_unless_pdf(document)?;
845
846 let input = json!(DocumentInput {
847 file: document.clone(),
848 pages,
849 deliver_as: None,
850 });
851
852 let options = Options {
855 regenerate: options.regenerate,
856 timeout: options.timeout,
857 ..Options::default()
858 };
859
860 let read: Execution<Value> = run("transcribe", input, None, None, &options)?;
861
862 Ok(Execution {
863 data: page_transcriptions(&read.data),
864 metadata: read.metadata,
865 })
866}
867
868pub fn enroll_face(subject_id: &str, image: Value) -> Result<String, Error> {
883 if subject_id.trim().is_empty() {
884 return Err(
885 Error::invalid("enroll_face needs the subject the face belongs to.")
886 .hint("Pass the id the face is to be found under, such as an employee or user id."),
887 );
888 }
889
890 refuse_empty(
891 &image,
892 "enroll_face needs an image of the face.",
893 "Pass a base64 image, or the handle of an uploaded one.",
894 )?;
895
896 let image = upload_pending(image)?;
897
898 let enrolled = host::transport()?
899 .call(
900 FACE_ENROLL.to_string(),
901 json!({ "image": image, "subject_id": subject_id }),
902 )
903 .map_err(|cause| {
904 cause.hint(
905 "Search the subject before enrolling the same face again, and report the failure.",
906 )
907 })?;
908
909 enrolled
910 .get("face_id")
911 .and_then(Value::as_str)
912 .map(str::to_string)
913 .ok_or_else(|| {
914 Error::Json(Fault::new(
915 Code::unspecified(),
916 "The enrolment answered without the id of the face it enrolled.",
917 ))
918 .hint("Search the subject to establish what was enrolled before enrolling again.")
919 })
920}
921
922pub fn search_face<T: DeserializeOwned>(image: Value, options: FaceSearch) -> Result<T, Error> {
945 refuse_empty(
946 &image,
947 "search_face needs an image to search with.",
948 "Pass a base64 image, or the handle of an uploaded one.",
949 )?;
950
951 let image = upload_pending(image)?;
952
953 let mut narrowing = Map::new();
954
955 if let Some(max_faces) = options.max_faces {
956 narrowing.insert("max_faces".to_string(), Value::from(max_faces));
957 }
958
959 if let Some(threshold) = options
960 .similarity_threshold
961 .filter(|value| value.is_finite())
962 {
963 narrowing.insert("similarity_threshold".to_string(), Value::from(threshold));
964 }
965
966 let found = host::transport()?
967 .call(
968 FACE_SEARCH.to_string(),
969 json!({ "image": image, "options": narrowing }),
970 )
971 .map_err(|cause| {
972 cause.hint("Nothing in the collection was changed. Report the search failure.")
973 })?;
974
975 serde_json::from_value(found).map_err(|cause| {
976 Error::Json(Fault::new(
977 Code::unspecified(),
978 format!("The matches could not be read into the type this action asked for: {cause}"),
979 ))
980 .hint("Read the matches as a Value, or name a type that matches what the search answers.")
981 })
982}
983
984pub fn delete_face(face_ids: &[String]) -> Result<Vec<String>, Error> {
999 if face_ids.is_empty() {
1000 return Err(Error::invalid("delete_face needs at least one face id.")
1001 .hint("Pass the ids enroll_face answered with."));
1002 }
1003
1004 let removed = host::transport()?
1005 .call(FACE_DELETE.to_string(), json!({ "face_ids": face_ids }))
1006 .map_err(|cause| {
1007 cause.hint(
1008 "Treat the removal as unfinished: search the collection to establish what is \
1009 still in it before deleting again.",
1010 )
1011 })?;
1012
1013 let listed = match &removed {
1014 Value::Array(ids) => Some(ids),
1015 other => other.get("deleted").and_then(Value::as_array),
1016 };
1017
1018 Ok(listed
1019 .map(|ids| {
1020 ids.iter()
1021 .filter_map(Value::as_str)
1022 .map(str::to_string)
1023 .collect()
1024 })
1025 .unwrap_or_default())
1026}
1027
1028fn run<T: DeserializeOwned>(
1030 operation: &str,
1031 input: Value,
1032 prompt: Option<&str>,
1033 schema: Option<Value>,
1034 options: &Options,
1035) -> Result<Execution<T>, Error> {
1036 let input = upload_pending(input)?;
1037
1038 let answered = host::transport()?
1039 .call(
1040 ORCHESTRATOR.to_string(),
1041 payload(operation, input, prompt, schema, options),
1042 )
1043 .map_err(|cause| {
1044 cause.hint(
1045 "No tenant record was changed. Review the input, the prompt and the schema, \
1046 and report the failure.",
1047 )
1048 })?;
1049
1050 let metadata = metadata_of(answered.get("metadata"));
1053 let data = answered.get("data").cloned().unwrap_or(Value::Null);
1054
1055 let data = serde_json::from_value(data).map_err(|cause| {
1056 Error::Json(Fault::new(
1057 Code::unspecified(),
1058 format!("The {operation} answer could not be read into the type this action asked for: {cause}"),
1059 ))
1060 .hint(
1061 "The operation ran. Read the answer as a Value, or name a type that matches the \
1062 schema, rather than running it again.",
1063 )
1064 })?;
1065
1066 Ok(Execution { data, metadata })
1067}
1068
1069fn payload(
1074 operation: &str,
1075 input: Value,
1076 prompt: Option<&str>,
1077 schema: Option<Value>,
1078 options: &Options,
1079) -> Value {
1080 let mut universal = Map::new();
1083
1084 universal.insert("reasoning".to_string(), Value::Bool(options.reasoning));
1085
1086 if let Some(budget) = options.reasoning_budget {
1087 universal.insert("reasoning_budget".to_string(), Value::from(budget));
1088 }
1089
1090 if let Some(temperature) = options.temperature.filter(|value| value.is_finite()) {
1091 universal.insert("temperature".to_string(), Value::from(temperature));
1092 }
1093
1094 let mut payload = Map::new();
1095
1096 payload.insert("operation".to_string(), Value::from(operation));
1097 payload.insert("input".to_string(), input);
1098 payload.insert("options".to_string(), Value::Object(universal));
1099
1100 if let Some(prompt) = prompt {
1103 payload.insert("prompt".to_string(), Value::from(prompt));
1104 }
1105 payload.insert("regenerate".to_string(), Value::Bool(options.regenerate));
1106
1107 if let Some(schema) = schema {
1108 payload.insert("schema".to_string(), schema);
1109 }
1110
1111 if let Some(model) = options.model {
1112 payload.insert("model".to_string(), Value::from(model.as_str()));
1113 }
1114
1115 if let Some(system_prompt) = &options.system_prompt {
1116 payload.insert(
1117 "systemPrompt".to_string(),
1118 Value::from(system_prompt.as_str()),
1119 );
1120 }
1121
1122 if let Some(timeout) = options.timeout {
1123 payload.insert("timeout".to_string(), Value::from(milliseconds(timeout)));
1124 }
1125
1126 Value::Object(payload)
1127}
1128
1129fn milliseconds(timeout: Duration) -> u64 {
1131 u64::try_from(timeout.as_millis()).unwrap_or(u64::MAX)
1132}
1133
1134fn metadata_of(metadata: Option<&Value>) -> Metadata {
1136 let Some(metadata) = metadata else {
1137 return Metadata::default();
1138 };
1139
1140 Metadata {
1141 input_tokens: count(metadata, "input_tokens").unwrap_or(0),
1142 output_tokens: count(metadata, "output_tokens").unwrap_or(0),
1143 reasoning_tokens: count(metadata, "reasoning_tokens"),
1144 reasoning: metadata
1145 .get("reasoning")
1146 .and_then(Value::as_str)
1147 .map(str::to_string),
1148 delivery: delivery_of(metadata.get("delivery")),
1149 }
1150}
1151
1152fn count(metadata: &Value, key: &str) -> Option<u64> {
1154 metadata.get(key).and_then(Value::as_u64)
1155}
1156
1157fn delivery_of(delivery: Option<&Value>) -> Vec<FileDelivery> {
1163 delivery
1164 .and_then(Value::as_array)
1165 .map(|files| files.iter().filter_map(file_delivery).collect())
1166 .unwrap_or_default()
1167}
1168
1169fn file_delivery(file: &Value) -> Option<FileDelivery> {
1174 let delivered_as = match file.get("delivered_as").and_then(Value::as_str)? {
1175 "document" => DeliveredAs::Document,
1176 "text" => DeliveredAs::Text,
1177 "image" => DeliveredAs::Image,
1178 _ => return None,
1179 };
1180
1181 let first_page = file.get("first_page").and_then(page_number);
1182 let last_page = file.get("last_page").and_then(page_number);
1183
1184 Some(FileDelivery {
1185 filename: file.get("filename").and_then(Value::as_str)?.to_string(),
1186 delivered_as,
1187 pages: first_page
1188 .zip(last_page)
1189 .map(|(first, last)| Pages::new(first, last)),
1190 transcribed_pages: page_numbers(file.get("transcribed_pages")),
1191 fallback: file
1192 .get("fallback")
1193 .filter(|fallback| fallback.is_object())
1194 .map(delivery_fallback),
1195 })
1196}
1197
1198fn delivery_fallback(fallback: &Value) -> DeliveryFallback {
1201 let text = |key: &str| {
1202 fallback
1203 .get(key)
1204 .and_then(Value::as_str)
1205 .unwrap_or_default()
1206 .to_string()
1207 };
1208
1209 DeliveryFallback {
1210 reason: text("reason"),
1211 pages: page_numbers(fallback.get("pages")),
1212 message: text("message"),
1213 }
1214}
1215
1216fn page_number(value: &Value) -> Option<u32> {
1218 value
1219 .as_u64()
1220 .and_then(|number| u32::try_from(number).ok())
1221 .filter(|page| *page > 0)
1222}
1223
1224fn page_numbers(pages: Option<&Value>) -> Vec<u32> {
1226 pages
1227 .and_then(Value::as_array)
1228 .map(|pages| pages.iter().filter_map(page_number).collect())
1229 .unwrap_or_default()
1230}
1231
1232const NO_TRANSCRIPTION: &str = "no transcription was returned for this page";
1234
1235fn page_transcriptions(data: &Value) -> Vec<PageTranscription> {
1240 data.get("pages")
1241 .and_then(Value::as_array)
1242 .map(|pages| pages.iter().filter_map(page_transcription).collect())
1243 .unwrap_or_default()
1244}
1245
1246fn page_transcription(entry: &Value) -> Option<PageTranscription> {
1252 let page = entry.get("page").and_then(page_number)?;
1253 let error = entry.get("error").and_then(Value::as_str);
1254 let text = entry.get("text").and_then(Value::as_str);
1255
1256 Some(match (error, text) {
1257 (None, Some(text)) => PageTranscription::Read {
1258 page,
1259 text: text.to_string(),
1260 },
1261 (error, _) => PageTranscription::Unread {
1262 page,
1263 error: error.unwrap_or(NO_TRANSCRIPTION).to_string(),
1264 },
1265 })
1266}
1267
1268fn upload_pending(value: Value) -> Result<Value, Error> {
1274 if is_pending(&value) {
1275 let stored = host::transport()?
1276 .call(UPLOAD_EPHEMERAL.to_string(), value.clone())
1277 .map_err(|cause| {
1278 cause.hint(
1279 "The file was not uploaded and the operation did not run. Upload the file, \
1280 then pass the handle that upload answered with.",
1281 )
1282 })?;
1283
1284 return Ok(stored_handle(value, stored));
1285 }
1286
1287 if let Value::Array(items) = value {
1288 let mut uploaded = Vec::with_capacity(items.len());
1289
1290 for item in items {
1291 uploaded.push(upload_pending(item)?);
1292 }
1293
1294 return Ok(Value::Array(uploaded));
1295 }
1296
1297 Ok(value)
1298}
1299
1300fn stored_handle(handle: Value, stored: Value) -> Value {
1318 match (handle, stored) {
1319 (Value::Object(mut handle), Value::Object(stored)) => {
1320 handle.remove("pending");
1321 handle.extend(stored);
1322
1323 Value::Object(handle)
1324 }
1325 (_, stored) => stored,
1326 }
1327}
1328
1329fn is_pending(value: &Value) -> bool {
1334 value.get("pending").and_then(Value::as_bool) == Some(true) && has_file_hash(value)
1335}
1336
1337fn has_file_hash(value: &Value) -> bool {
1339 value
1340 .get("file_hash")
1341 .and_then(Value::as_str)
1342 .is_some_and(|hash| !hash.is_empty())
1343}
1344
1345fn refuse_empty(value: &Value, message: &str, hint: &str) -> Result<(), Error> {
1347 let empty = match value {
1348 Value::Null => true,
1349 Value::String(text) => text.is_empty(),
1350 _ => false,
1351 };
1352
1353 if empty {
1354 return Err(Error::invalid(message).hint(hint));
1355 }
1356
1357 Ok(())
1358}
1359
1360fn refuse_empty_prompt(prompt: &str, operation: &str) -> Result<(), Error> {
1362 if prompt.trim().is_empty() {
1363 return Err(Error::invalid(format!("{operation} needs a prompt."))
1364 .hint("Say what the operation is to produce, in a sentence the model can act on."));
1365 }
1366
1367 Ok(())
1368}
1369
1370fn refuse_unless_media(document: &Value) -> Result<(), Error> {
1372 if !has_file_hash(document) {
1373 return Err(
1374 Error::invalid("transcribe needs a document handle to work on.").hint(
1375 "Pass the handle of the uploaded file, the one carrying file_hash and mime_type.",
1376 ),
1377 );
1378 }
1379
1380 let media = document
1381 .get("mime_type")
1382 .and_then(Value::as_str)
1383 .map(str::to_lowercase)
1384 .is_some_and(|mime| mime.starts_with("audio/") || mime.starts_with("video/"));
1385
1386 if !media {
1387 return Err(Error::invalid("transcribe works on audio and video.")
1388 .hint("Pass a handle whose mime_type begins audio/ or video/."));
1389 }
1390
1391 Ok(())
1392}
1393
1394fn refuse_unless_pdf(document: &DocumentHandle) -> Result<(), Error> {
1399 if document.file_hash.is_empty() {
1400 return Err(
1401 Error::invalid("transcribe_pages needs the handle of a stored file.").hint(
1402 "Pass the handle the upload or the record answered with, the one carrying \
1403 file_hash.",
1404 ),
1405 );
1406 }
1407
1408 let essence = document.mime_type.split(';').next().unwrap_or_default();
1409
1410 if !essence.trim().eq_ignore_ascii_case("application/pdf") {
1411 return Err(Error::invalid("transcribe_pages reads the pages of a PDF.")
1412 .hint("Pass the handle of a PDF. Read any other file with extract or summarize."));
1413 }
1414
1415 Ok(())
1416}
1417
1418fn transcribe_schema(wanted: &TranscribeOptions) -> Value {
1420 let identify = wanted.participants.wanted();
1421
1422 let mut properties = Map::new();
1423 let mut required = vec![Value::from("language")];
1424
1425 properties.insert(
1426 "language".to_string(),
1427 json!({
1428 "description": "The detected language of the audio (ISO 639-1 code, e.g., \"en\", \"es\")",
1429 "type": "string"
1430 }),
1431 );
1432
1433 if wanted.include_transcript {
1434 let description = match (identify, wanted.include_timestamps) {
1435 (true, true) => {
1436 "The full transcript with participant labels and timestamps. \
1437 Format: [MM:SS] Participant Name: text"
1438 }
1439 (true, false) => {
1440 "The full transcript with participant labels. Format: Participant Name: text"
1441 }
1442 (false, true) => "The full transcript with timestamps. Format: [MM:SS] text",
1443 (false, false) => "The full transcript of the audio",
1444 };
1445
1446 properties.insert(
1447 "transcript".to_string(),
1448 json!({ "description": description, "type": "string" }),
1449 );
1450 required.push(Value::from("transcript"));
1451 }
1452
1453 if wanted.summarize {
1454 let description = if identify {
1455 "A concise summary of the audio content, including key points from each participant"
1456 } else {
1457 "A concise summary of the audio content"
1458 };
1459
1460 properties.insert(
1461 "summary".to_string(),
1462 json!({ "description": description, "type": "string" }),
1463 );
1464 required.push(Value::from("summary"));
1465 }
1466
1467 if identify {
1468 properties.insert(
1469 "participants".to_string(),
1470 json!({
1471 "description": "List of identified participants in the audio",
1472 "items": { "type": "string" },
1473 "type": "array"
1474 }),
1475 );
1476 required.push(Value::from("participants"));
1477 }
1478
1479 json!({ "properties": properties, "required": required, "type": "object" })
1480}
1481
1482fn transcribe_prompt(wanted: &TranscribeOptions) -> String {
1484 let identify = wanted.participants.wanted();
1485 let names = wanted.participants.names();
1486
1487 let mut prompt = String::from("Analyze this audio/video file and provide:\n");
1488
1489 if wanted.include_transcript {
1490 if identify {
1491 match &names {
1492 Some(names) => {
1493 prompt.push_str("- A complete transcript identifying these participants: ");
1494 prompt.push_str(names);
1495 prompt.push_str(". ");
1496 }
1497 None => prompt.push_str(
1498 "- A complete transcript with participant identification \
1499 (label participants as Participant 1, Participant 2, etc.). ",
1500 ),
1501 }
1502
1503 if wanted.include_timestamps {
1504 prompt.push_str(
1505 "Include timestamps in [MM:SS] format before each participant segment.\n",
1506 );
1507 } else {
1508 prompt.push_str("Format each line as \"Participant Name: text\".\n");
1509 }
1510 } else if wanted.include_timestamps {
1511 prompt.push_str(
1512 "- A complete transcript with timestamps in [MM:SS] format before each segment\n",
1513 );
1514 } else {
1515 prompt.push_str("- A complete transcript of all spoken content\n");
1516 }
1517 }
1518
1519 if wanted.summarize {
1520 if identify {
1521 prompt.push_str("- A concise summary highlighting key points from each participant\n");
1522 } else {
1523 prompt.push_str("- A concise summary of the main points and key information\n");
1524 }
1525 }
1526
1527 if identify {
1528 match &names {
1529 Some(names) => {
1530 prompt.push_str("- Identify and distinguish between these participants: ");
1531 prompt.push_str(names);
1532 prompt.push('\n');
1533 }
1534 None => prompt.push_str("- Identify and list all distinct participants in the audio\n"),
1535 }
1536 }
1537
1538 prompt.push_str("- The detected language code (ISO 639-1 format)\n");
1539
1540 prompt
1541}
1542
1543#[cfg(test)]
1544mod tests {
1545 use serde_json::json;
1546
1547 use super::*;
1548 use crate::testing;
1549
1550 fn answered() -> Value {
1552 json!({ "data": { "ok": true }, "metadata": { "input_tokens": 1, "output_tokens": 2 } })
1553 }
1554
1555 fn stored() -> DocumentHandle {
1557 DocumentHandle {
1558 file_hash: "ffce20f1".to_string(),
1559 filename: "contract.pdf".to_string(),
1560 mime_type: "application/pdf".to_string(),
1561 size: 1_234,
1562 storage_path: "acme/documents/ffce20f1".to_string(),
1563 }
1564 }
1565
1566 #[test]
1567 fn a_document_input_travels_as_the_handle_with_the_keys_the_engine_reads() {
1568 let sent = json!(DocumentInput {
1569 file: stored(),
1570 pages: Some(Pages::new(12, 30)),
1571 deliver_as: Some(Delivery::Text),
1572 });
1573
1574 assert_eq!(sent["storage_path"], json!("acme/documents/ffce20f1"));
1575 assert_eq!(sent["file_hash"], json!("ffce20f1"));
1576 assert_eq!(sent["mime_type"], json!("application/pdf"));
1577 assert_eq!(
1578 sent["first_page"],
1579 json!(12),
1580 "a range travels as the two keys the engine reads, not as a nested one"
1581 );
1582 assert_eq!(sent["last_page"], json!(30));
1583 assert_eq!(sent["deliver_as"], json!("text"));
1584 }
1585
1586 #[test]
1587 fn a_document_input_that_asks_for_nothing_carries_neither_key() {
1588 let sent = json!(DocumentInput {
1589 file: stored(),
1590 ..Default::default()
1591 });
1592
1593 assert_eq!(sent["filename"], json!("contract.pdf"));
1594 assert_eq!(
1595 sent.get("deliver_as"),
1596 None,
1597 "asking for nothing says nothing, so the default stays the engine's"
1598 );
1599 assert_eq!(sent.get("first_page"), None);
1600 assert_eq!(sent.get("last_page"), None);
1601 }
1602
1603 #[test]
1604 fn an_extraction_asks_the_primitive_and_answers_with_the_type_it_was_asked_for() {
1605 #[derive(Debug, Deserialize, PartialEq)]
1606 struct Invoice {
1607 number: String,
1608 total: f64,
1609 }
1610
1611 let session = testing::install(|name, params| {
1612 assert_eq!(name, ORCHESTRATOR);
1613 assert_eq!(params["operation"], json!("extract"));
1614 assert_eq!(params["prompt"], json!("Read it."));
1615 assert_eq!(params["input"], json!("INV-8, 240.00"));
1616 assert_eq!(params["schema"]["type"], json!("object"));
1617
1618 Ok(json!({
1619 "data": { "number": "INV-8", "total": 240.0 },
1620 "metadata": { "input_tokens": 11, "output_tokens": 3 }
1621 }))
1622 });
1623
1624 let read: Execution<Invoice> = extract(
1625 json!("INV-8, 240.00"),
1626 "Read it.",
1627 json!({ "type": "object" }),
1628 Options::default(),
1629 )
1630 .unwrap();
1631
1632 assert_eq!(
1633 read.data,
1634 Invoice {
1635 number: "INV-8".to_string(),
1636 total: 240.0
1637 }
1638 );
1639 assert_eq!(read.metadata.input_tokens, 11);
1640 assert_eq!(read.metadata.output_tokens, 3);
1641 assert_eq!(session.calls().len(), 1);
1642 }
1643
1644 #[test]
1645 fn a_default_call_reasons_does_not_regenerate_and_leaves_the_rest_to_the_platform() {
1646 let session = testing::install(|_name, _params| Ok(answered()));
1647
1648 let _: Execution<Value> = extract(
1649 json!("text"),
1650 "Read it.",
1651 json!({ "type": "object" }),
1652 Options::default(),
1653 )
1654 .unwrap();
1655
1656 let sent = session.calls()[0].params.clone();
1657
1658 assert_eq!(sent["options"], json!({ "reasoning": true }));
1659 assert_eq!(sent["regenerate"], json!(false));
1660 assert!(sent.get("model").is_none());
1661 assert!(sent.get("systemPrompt").is_none());
1662 assert!(sent.get("timeout").is_none());
1663 }
1664
1665 #[test]
1666 fn every_option_that_was_set_travels_with_the_operation() {
1667 let session = testing::install(|_name, _params| Ok(answered()));
1668
1669 let _: Execution<Value> = extract(
1670 json!("text"),
1671 "Read it.",
1672 json!({ "type": "object" }),
1673 Options {
1674 model: Some(Model::Xl),
1675 system_prompt: Some("You are an auditor.".to_string()),
1676 temperature: Some(0.25),
1677 reasoning: false,
1678 reasoning_budget: Some(2_048),
1679 regenerate: true,
1680 timeout: Some(Duration::from_secs(90)),
1681 },
1682 )
1683 .unwrap();
1684
1685 let sent = session.calls()[0].params.clone();
1686
1687 assert_eq!(sent["model"], json!("xl"));
1688 assert_eq!(sent["systemPrompt"], json!("You are an auditor."));
1689 assert_eq!(sent["regenerate"], json!(true));
1690 assert_eq!(sent["timeout"], json!(90_000));
1691 assert_eq!(
1692 sent["options"],
1693 json!({ "reasoning": false, "reasoning_budget": 2_048, "temperature": 0.25 })
1694 );
1695 }
1696
1697 #[test]
1698 fn a_summary_answers_with_the_prose_and_carries_no_schema() {
1699 let session = testing::install(|_name, params| {
1700 assert_eq!(params["operation"], json!("summarize"));
1701 assert!(params.get("schema").is_none());
1702
1703 Ok(json!({ "data": "A refund was agreed.", "metadata": { "output_tokens": 5 } }))
1704 });
1705
1706 let written = summarize(json!("A long thread."), "One sentence.", Options::default())
1707 .expect("a summary answers with prose");
1708
1709 assert_eq!(written.data, "A refund was agreed.");
1710 assert_eq!(written.metadata.output_tokens, 5);
1711 assert_eq!(session.calls().len(), 1);
1712 }
1713
1714 #[test]
1715 fn a_pending_document_is_uploaded_before_the_operation_reads_it() {
1716 let session = testing::install(|name, _params| {
1717 if name == UPLOAD_EPHEMERAL {
1718 return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
1719 }
1720
1721 Ok(answered())
1722 });
1723
1724 let _: Execution<Value> = extract(
1725 json!({ "file_hash": "abc", "pending": true }),
1726 "Read it.",
1727 json!({ "type": "object" }),
1728 Options::default(),
1729 )
1730 .unwrap();
1731
1732 let calls = session.calls();
1733
1734 assert_eq!(calls.len(), 2);
1735 assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
1736 assert_eq!(calls[1].name, ORCHESTRATOR);
1737 assert_eq!(
1738 calls[1].params["input"],
1739 json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }),
1740 "the operation reads the handle the upload answered with"
1741 );
1742 }
1743
1744 #[test]
1745 fn a_pending_document_is_read_the_way_the_caller_asked_for_it() {
1746 let session = testing::install(|name, _params| {
1747 if name == UPLOAD_EPHEMERAL {
1748 return Ok(json!({
1749 "file_hash": "ffce20f1",
1750 "filename": "contract.pdf",
1751 "mime_type": "application/pdf",
1752 "size": 1_234,
1753 "storage_path": "acme/ephemeral/ffce20f1"
1754 }));
1755 }
1756
1757 Ok(answered())
1758 });
1759
1760 let _: Execution<Value> = extract(
1761 json!({
1762 "file_hash": "staged",
1763 "first_page": 12,
1764 "last_page": 30,
1765 "pending": true,
1766 "deliver_as": "text",
1767 "storage_path": "acme/staged/staged"
1768 }),
1769 "Read it.",
1770 json!({ "type": "object" }),
1771 Options::default(),
1772 )
1773 .unwrap();
1774
1775 let calls = session.calls();
1776 let sent = calls[1].params["input"].clone();
1777
1778 assert_eq!(
1779 sent["deliver_as"],
1780 json!("text"),
1781 "the caller said how the file was to be sent"
1782 );
1783 assert_eq!(
1784 sent["first_page"],
1785 json!(12),
1786 "the caller asked for a range"
1787 );
1788 assert_eq!(sent["last_page"], json!(30), "the caller asked for a range");
1789 assert_eq!(
1790 sent["file_hash"],
1791 json!("ffce20f1"),
1792 "the file is the one the upload stored"
1793 );
1794 assert_eq!(
1795 sent["storage_path"],
1796 json!("acme/ephemeral/ffce20f1"),
1797 "the file is read from where the upload put it"
1798 );
1799 assert_eq!(sent["filename"], json!("contract.pdf"));
1800 assert_eq!(sent["mime_type"], json!("application/pdf"));
1801 assert_eq!(sent["size"], json!(1_234));
1802 assert!(
1803 sent.get("pending").is_none(),
1804 "the file is stored, so the handle may not still call itself pending"
1805 );
1806 }
1807
1808 #[test]
1809 fn a_document_that_is_already_stored_is_read_where_it_is() {
1810 let session = testing::install(|_name, _params| Ok(answered()));
1811
1812 let handle = json!({ "file_hash": "abc", "mime_type": "application/pdf" });
1813
1814 let _: Execution<Value> = extract(
1815 handle.clone(),
1816 "Read it.",
1817 json!({ "type": "object" }),
1818 Options::default(),
1819 )
1820 .unwrap();
1821
1822 let calls = session.calls();
1823
1824 assert_eq!(calls.len(), 1, "nothing was uploaded");
1825 assert_eq!(calls[0].params["input"], handle);
1826 }
1827
1828 #[test]
1829 fn a_list_of_documents_is_uploaded_item_by_item() {
1830 let session = testing::install(|name, params| {
1831 if name == UPLOAD_EPHEMERAL {
1832 let hash = params["file_hash"].as_str().unwrap_or_default();
1833
1834 return Ok(json!({
1835 "file_hash": hash,
1836 "storage_path": format!("ephemeral/{hash}")
1837 }));
1838 }
1839
1840 Ok(answered())
1841 });
1842
1843 let _: Execution<Value> = extract(
1844 json!([
1845 { "file_hash": "one", "pending": true },
1846 { "file_hash": "two", "mime_type": "image/png" },
1847 { "file_hash": "three", "pending": true }
1848 ]),
1849 "Read them.",
1850 json!({ "type": "object" }),
1851 Options::default(),
1852 )
1853 .unwrap();
1854
1855 let calls = session.calls();
1856
1857 assert_eq!(calls.len(), 3, "two uploads and the operation");
1858 assert_eq!(
1859 calls[2].params["input"],
1860 json!([
1861 { "file_hash": "one", "storage_path": "ephemeral/one" },
1862 { "file_hash": "two", "mime_type": "image/png" },
1863 { "file_hash": "three", "storage_path": "ephemeral/three" }
1864 ])
1865 );
1866 }
1867
1868 #[test]
1869 fn a_handle_is_pending_only_while_it_says_so_and_carries_a_hash_to_upload_by() {
1870 assert!(is_pending(&json!({ "file_hash": "abc", "pending": true })));
1871 assert!(!is_pending(&json!({ "file_hash": "abc" })));
1872 assert!(!is_pending(&json!({ "pending": true })));
1873 assert!(!is_pending(&json!({ "file_hash": "", "pending": true })));
1874 assert!(!is_pending(
1875 &json!({ "file_hash": "abc", "pending": "yes" })
1876 ));
1877 assert!(!is_pending(&json!("some words")));
1878 assert!(!is_pending(&json!([
1879 { "file_hash": "abc", "pending": true }
1880 ])));
1881 }
1882
1883 #[test]
1884 fn an_answer_that_reports_nothing_about_its_cost_is_still_an_answer() {
1885 let _session = testing::install(|_name, _params| Ok(json!({ "data": "done" })));
1886
1887 let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
1888
1889 assert_eq!(written.data, "done");
1890 assert_eq!(written.metadata, Metadata::default());
1891 }
1892
1893 #[test]
1894 fn reasoning_reaches_the_caller_when_the_run_reported_it() {
1895 let _session = testing::install(|_name, _params| {
1896 Ok(json!({
1897 "data": "done",
1898 "metadata": {
1899 "input_tokens": 9,
1900 "output_tokens": 4,
1901 "reasoning": "Read the total from the last line.",
1902 "reasoning_tokens": 120
1903 }
1904 }))
1905 });
1906
1907 let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
1908
1909 assert_eq!(written.metadata.reasoning_tokens, Some(120));
1910 assert_eq!(
1911 written.metadata.reasoning.as_deref(),
1912 Some("Read the total from the last line.")
1913 );
1914 }
1915
1916 #[test]
1917 fn a_run_reports_how_each_file_travelled_in_the_order_the_files_were_given() {
1918 let _session = testing::install(|_name, _params| {
1919 Ok(json!({
1920 "data": "done",
1921 "metadata": {
1922 "input_tokens": 9,
1923 "output_tokens": 4,
1924 "delivery": [
1925 {
1926 "filename": "contract.pdf",
1927 "delivered_as": "text",
1928 "first_page": 40,
1929 "last_page": 52,
1930 "transcribed_pages": [41, 44],
1931 "fallback": null
1932 },
1933 {
1934 "filename": "drawings.pdf",
1935 "delivered_as": "document",
1936 "first_page": null,
1937 "last_page": null,
1938 "transcribed_pages": [],
1939 "fallback": {
1940 "reason": "transcription_failed",
1941 "pages": [3, 7],
1942 "message": "page 3: timed out; page 7: blank answer"
1943 }
1944 },
1945 {
1946 "filename": "site.jpg",
1947 "delivered_as": "image",
1948 "first_page": null,
1949 "last_page": null,
1950 "transcribed_pages": [],
1951 "fallback": null
1952 }
1953 ]
1954 }
1955 }))
1956 });
1957
1958 let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
1959
1960 assert_eq!(
1961 written.metadata.delivery,
1962 vec![
1963 FileDelivery {
1964 filename: "contract.pdf".to_string(),
1965 delivered_as: DeliveredAs::Text,
1966 pages: Some(Pages::new(40, 52)),
1967 transcribed_pages: vec![41, 44],
1968 fallback: None,
1969 },
1970 FileDelivery {
1971 filename: "drawings.pdf".to_string(),
1972 delivered_as: DeliveredAs::Document,
1973 pages: None,
1974 transcribed_pages: Vec::new(),
1975 fallback: Some(DeliveryFallback {
1976 reason: "transcription_failed".to_string(),
1977 pages: vec![3, 7],
1978 message: "page 3: timed out; page 7: blank answer".to_string(),
1979 }),
1980 },
1981 FileDelivery {
1982 filename: "site.jpg".to_string(),
1983 delivered_as: DeliveredAs::Image,
1984 pages: None,
1985 transcribed_pages: Vec::new(),
1986 fallback: None,
1987 },
1988 ]
1989 );
1990 assert_eq!(
1991 written.metadata.input_tokens, 9,
1992 "the members a result already had read as they did"
1993 );
1994 }
1995
1996 #[test]
1997 fn an_answer_without_a_delivery_report_carries_none() {
1998 for metadata in [
1999 json!({ "input_tokens": 1 }),
2000 json!({ "delivery": null }),
2001 json!({ "delivery": "document" }),
2002 json!({ "delivery": { "filename": "contract.pdf", "delivered_as": "text" } }),
2003 ] {
2004 let _session = testing::install(move |_name, _params| {
2005 Ok(json!({ "data": "done", "metadata": metadata.clone() }))
2006 });
2007
2008 let written = summarize(json!("text"), "One sentence.", Options::default())
2009 .expect("a report that cannot be read never fails the run");
2010
2011 assert!(written.metadata.delivery.is_empty());
2012 }
2013 }
2014
2015 #[test]
2016 fn a_delivery_entry_that_cannot_be_read_is_left_out_and_the_rest_are_kept() {
2017 let delivery = delivery_of(Some(&json!([
2018 "contract.pdf",
2019 { "filename": "no-way.pdf" },
2020 { "filename": "audio.mp3", "delivered_as": "audio" },
2021 { "delivered_as": "text" },
2022 { "filename": 7, "delivered_as": "text" },
2023 {
2024 "filename": "kept.pdf",
2025 "delivered_as": "text",
2026 "first_page": 4,
2027 "transcribed_pages": ["5", -1, 0, 6, 4_294_967_296_u64, null]
2028 }
2029 ])));
2030
2031 assert_eq!(
2032 delivery,
2033 vec![FileDelivery {
2034 filename: "kept.pdf".to_string(),
2035 delivered_as: DeliveredAs::Text,
2036 pages: None,
2037 transcribed_pages: vec![6],
2038 fallback: None,
2039 }],
2040 "a range with one end is not a range, and only whole pages from 1 are pages"
2041 );
2042 }
2043
2044 #[test]
2045 fn a_fallback_that_is_reported_is_never_lost_to_a_missing_member() {
2046 let delivery = delivery_of(Some(&json!([
2047 {
2048 "filename": "contract.pdf",
2049 "delivered_as": "document",
2050 "fallback": { "reason": "transcription_failed" }
2051 },
2052 {
2053 "filename": "drawings.pdf",
2054 "delivered_as": "document",
2055 "fallback": "transcription_failed"
2056 }
2057 ])));
2058
2059 assert_eq!(
2060 delivery[0].fallback,
2061 Some(DeliveryFallback {
2062 reason: "transcription_failed".to_string(),
2063 pages: Vec::new(),
2064 message: String::new(),
2065 })
2066 );
2067 assert_eq!(
2068 delivery[1].fallback, None,
2069 "a fallback that is not an object says nothing that can be read"
2070 );
2071 assert!(delivery[0].transcribed_pages.is_empty());
2072 }
2073
2074 #[test]
2075 fn an_operation_with_nothing_to_do_is_refused_before_anything_is_sent() {
2076 let session = testing::install(|_name, _params| Ok(answered()));
2077
2078 let missing_input = extract::<Value>(
2079 json!(null),
2080 "Read it.",
2081 json!({ "type": "object" }),
2082 Options::default(),
2083 )
2084 .unwrap_err();
2085
2086 let missing_prompt = extract::<Value>(
2087 json!("text"),
2088 " ",
2089 json!({ "type": "object" }),
2090 Options::default(),
2091 )
2092 .unwrap_err();
2093
2094 let missing_schema =
2095 extract::<Value>(json!("text"), "Read it.", json!([]), Options::default()).unwrap_err();
2096
2097 let missing_summary_input =
2098 summarize(json!(""), "One sentence.", Options::default()).unwrap_err();
2099
2100 for refusal in [
2101 &missing_input,
2102 &missing_prompt,
2103 &missing_schema,
2104 &missing_summary_input,
2105 ] {
2106 assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
2107 }
2108
2109 assert!(session.calls().is_empty());
2110 }
2111
2112 #[test]
2113 fn a_transcription_writes_its_own_schema_and_prompt() {
2114 let session = testing::install(|_name, _params| {
2115 Ok(json!({
2116 "data": { "language": "en", "transcript": "Hello." },
2117 "metadata": { "input_tokens": 400, "output_tokens": 12 }
2118 }))
2119 });
2120
2121 let heard = transcribe(
2122 json!({ "file_hash": "abc", "mime_type": "AUDIO/MPEG" }),
2123 TranscribeOptions {
2124 include_transcript: true,
2125 ..Default::default()
2126 },
2127 Options::default(),
2128 )
2129 .expect("an uppercase mime type is the same mime type");
2130
2131 assert_eq!(heard.data.language, "en");
2132 assert_eq!(heard.data.transcript.as_deref(), Some("Hello."));
2133 assert_eq!(heard.data.summary, None);
2134 assert!(heard.data.participants.is_empty());
2135
2136 let sent = session.calls()[0].params.clone();
2137
2138 assert_eq!(sent["operation"], json!("extract"));
2139 assert_eq!(
2140 sent["schema"]["required"],
2141 json!(["language", "transcript"])
2142 );
2143 assert_eq!(sent["schema"]["properties"]["transcript"]["type"], "string");
2144 assert_eq!(
2145 sent["prompt"],
2146 json!(
2147 "Analyze this audio/video file and provide:\n\
2148 - A complete transcript of all spoken content\n\
2149 - The detected language code (ISO 639-1 format)\n"
2150 )
2151 );
2152 }
2153
2154 #[test]
2155 fn named_participants_reach_both_the_prompt_and_the_schema() {
2156 let session = testing::install(|_name, _params| {
2157 Ok(json!({ "data": { "language": "en", "participants": ["Customer", "Agent"] } }))
2158 });
2159
2160 let heard = transcribe(
2161 json!({ "file_hash": "abc", "mime_type": "video/mp4" }),
2162 TranscribeOptions {
2163 include_transcript: true,
2164 include_timestamps: true,
2165 summarize: true,
2166 participants: Participants::Named(vec![
2167 "Customer".to_string(),
2168 "Agent".to_string(),
2169 ]),
2170 },
2171 Options::default(),
2172 )
2173 .unwrap();
2174
2175 assert_eq!(heard.data.participants, ["Customer", "Agent"]);
2176
2177 let sent = session.calls()[0].params.clone();
2178 let prompt = sent["prompt"].as_str().unwrap_or_default().to_string();
2179
2180 assert_eq!(
2181 sent["schema"]["required"],
2182 json!(["language", "transcript", "summary", "participants"])
2183 );
2184 assert_eq!(
2185 sent["schema"]["properties"]["participants"]["items"]["type"],
2186 json!("string")
2187 );
2188 assert!(prompt.contains("identifying these participants: Customer, Agent. "));
2189 assert!(prompt.contains("Include timestamps in [MM:SS] format"));
2190 assert!(
2191 prompt.contains("- A concise summary highlighting key points from each participant\n")
2192 );
2193 assert!(prompt
2194 .contains("- Identify and distinguish between these participants: Customer, Agent\n"));
2195 }
2196
2197 #[test]
2198 fn detected_participants_are_labelled_rather_than_named() {
2199 let session =
2200 testing::install(|_name, _params| Ok(json!({ "data": { "language": "en" } })));
2201
2202 let _ = transcribe(
2203 json!({ "file_hash": "abc", "mime_type": "audio/wav" }),
2204 TranscribeOptions {
2205 include_transcript: true,
2206 participants: Participants::Detect,
2207 ..Default::default()
2208 },
2209 Options::default(),
2210 )
2211 .unwrap();
2212
2213 let prompt = session.calls()[0].params["prompt"]
2214 .as_str()
2215 .unwrap_or_default()
2216 .to_string();
2217
2218 assert!(prompt.contains("label participants as Participant 1, Participant 2, etc."));
2219 assert!(prompt.contains("Format each line as \"Participant Name: text\".\n"));
2220 assert!(prompt.contains("- Identify and list all distinct participants in the audio\n"));
2221 }
2222
2223 #[test]
2224 fn naming_nobody_asks_for_the_same_thing_as_detecting() {
2225 let wanted = |participants| TranscribeOptions {
2226 include_transcript: true,
2227 participants,
2228 ..Default::default()
2229 };
2230
2231 assert_eq!(
2232 transcribe_prompt(&wanted(Participants::Named(Vec::new()))),
2233 transcribe_prompt(&wanted(Participants::Detect))
2234 );
2235 assert_eq!(
2236 transcribe_schema(&wanted(Participants::Named(Vec::new()))),
2237 transcribe_schema(&wanted(Participants::Detect))
2238 );
2239 }
2240
2241 #[test]
2242 fn a_transcription_that_cannot_run_is_refused_before_anything_is_sent() {
2243 let session = testing::install(|_name, _params| Ok(answered()));
2244
2245 let audio = json!({ "file_hash": "abc", "mime_type": "audio/mpeg" });
2246
2247 let nothing_wanted = transcribe(
2248 audio.clone(),
2249 TranscribeOptions::default(),
2250 Options::default(),
2251 )
2252 .unwrap_err();
2253
2254 let not_media = transcribe(
2255 json!({ "file_hash": "abc", "mime_type": "application/pdf" }),
2256 TranscribeOptions {
2257 include_transcript: true,
2258 ..Default::default()
2259 },
2260 Options::default(),
2261 )
2262 .unwrap_err();
2263
2264 let not_a_handle = transcribe(
2265 json!("some words"),
2266 TranscribeOptions {
2267 summarize: true,
2268 ..Default::default()
2269 },
2270 Options::default(),
2271 )
2272 .unwrap_err();
2273
2274 for refusal in [¬hing_wanted, ¬_media, ¬_a_handle] {
2275 assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
2276 }
2277
2278 assert!(session.calls().is_empty());
2279 }
2280
2281 #[test]
2282 fn a_page_transcription_asks_for_the_transcribe_operation_with_the_range_and_no_prompt() {
2283 let session = testing::install(|_name, _params| {
2284 Ok(json!({
2285 "data": {
2286 "pages": [
2287 { "page": 41, "text": "Scope of Work" },
2288 { "page": 42, "error": "the answer carries no pages" }
2289 ]
2290 },
2291 "metadata": {
2292 "delivery": null,
2293 "input_tokens": 0,
2294 "output_tokens": 0,
2295 "reasoning_tokens": 0
2296 }
2297 }))
2298 });
2299
2300 let read = transcribe_pages(
2301 &stored(),
2302 Some(Pages::new(40, 52)),
2303 TranscribePagesOptions::default(),
2304 )
2305 .unwrap();
2306
2307 let calls = session.calls();
2308
2309 assert_eq!(calls.len(), 1);
2310 assert_eq!(calls[0].name, ORCHESTRATOR);
2311 assert_eq!(
2312 calls[0].params,
2313 json!({
2314 "operation": "transcribe",
2315 "input": {
2316 "file_hash": "ffce20f1",
2317 "filename": "contract.pdf",
2318 "mime_type": "application/pdf",
2319 "size": 1_234,
2320 "storage_path": "acme/documents/ffce20f1",
2321 "first_page": 40,
2322 "last_page": 52
2323 },
2324 "options": { "reasoning": true },
2325 "regenerate": false
2326 }),
2327 "no prompt, schema, model or delivery: the instructions are the platform's"
2328 );
2329
2330 assert_eq!(
2331 read.data,
2332 vec![
2333 PageTranscription::Read {
2334 page: 41,
2335 text: "Scope of Work".to_string()
2336 },
2337 PageTranscription::Unread {
2338 page: 42,
2339 error: "the answer carries no pages".to_string()
2340 },
2341 ]
2342 );
2343 assert_eq!(read.metadata.input_tokens, 0);
2344 assert!(read.metadata.delivery.is_empty());
2345 }
2346
2347 #[test]
2348 fn a_page_transcription_carries_only_the_whole_file_and_the_options_it_was_given() {
2349 let session = testing::install(|_name, _params| Ok(json!({ "data": { "pages": [] } })));
2350
2351 let read = transcribe_pages(
2352 &stored(),
2353 None,
2354 TranscribePagesOptions {
2355 regenerate: true,
2356 timeout: Some(Duration::from_secs(90)),
2357 },
2358 )
2359 .unwrap();
2360
2361 let sent = session.calls()[0].params.clone();
2362
2363 assert!(read.data.is_empty());
2364 assert!(sent["input"].get("first_page").is_none());
2365 assert!(sent["input"].get("last_page").is_none());
2366 assert_eq!(sent["regenerate"], json!(true));
2367 assert_eq!(sent["timeout"], json!(90_000));
2368 assert_eq!(sent["options"], json!({ "reasoning": true }));
2369 }
2370
2371 #[test]
2372 fn a_page_with_no_text_is_answered_as_unread_never_as_text_that_is_not_there() {
2373 let _session = testing::install(|_name, _params| {
2374 Ok(json!({
2375 "data": {
2376 "pages": [
2377 { "page": 7, "text": "" },
2378 { "page": 8, "error": "the model timed out", "text": "Scope of" },
2379 { "page": 9 },
2380 { "page": 10, "transcriptions": ["Scope of Work", "Scope of Work"] },
2381 { "page": 11, "error": null, "text": "Clause 4" },
2382 { "page": 12, "error": 500, "text": "Clause 5" },
2383 { "page": 13, "text": null },
2384 { "text": "a page with no number" },
2385 { "page": "14", "text": "a number that is a string" },
2386 "page 15"
2387 ]
2388 }
2389 }))
2390 });
2391
2392 let read = transcribe_pages(&stored(), None, TranscribePagesOptions::default()).unwrap();
2393
2394 let unread = |page: u32, error: &str| PageTranscription::Unread {
2395 page,
2396 error: error.to_string(),
2397 };
2398 let read_as = |page: u32, text: &str| PageTranscription::Read {
2399 page,
2400 text: text.to_string(),
2401 };
2402
2403 assert_eq!(
2404 read.data,
2405 vec![
2406 read_as(7, ""),
2407 unread(8, "the model timed out"),
2408 unread(9, NO_TRANSCRIPTION),
2409 unread(10, NO_TRANSCRIPTION),
2410 read_as(11, "Clause 4"),
2411 read_as(12, "Clause 5"),
2412 unread(13, NO_TRANSCRIPTION),
2413 ]
2414 );
2415 assert_eq!(read.data[1].text(), None, "an error wins over partial text");
2416 assert_eq!(read.data[0].text(), Some(""), "a blank page is a read");
2417 assert_eq!(read.data[2].page(), 9);
2418 }
2419
2420 #[test]
2421 fn an_answer_without_a_list_of_pages_has_no_pages() {
2422 for data in [
2423 json!(null),
2424 json!({}),
2425 json!({ "pages": "none" }),
2426 json!([]),
2427 ] {
2428 let _session =
2429 testing::install(move |_name, _params| Ok(json!({ "data": data.clone() })));
2430
2431 let read =
2432 transcribe_pages(&stored(), None, TranscribePagesOptions::default()).unwrap();
2433
2434 assert!(read.data.is_empty());
2435 }
2436 }
2437
2438 #[test]
2439 fn a_page_transcription_of_anything_but_a_pdf_is_refused_before_the_host_is_asked() {
2440 let session = testing::install(|_name, _params| Ok(json!({ "data": { "pages": [] } })));
2441
2442 let spreadsheet = transcribe_pages(
2443 &DocumentHandle {
2444 filename: "rates.csv".to_string(),
2445 mime_type: "text/csv".to_string(),
2446 ..stored()
2447 },
2448 None,
2449 TranscribePagesOptions::default(),
2450 )
2451 .unwrap_err();
2452
2453 let unstored = transcribe_pages(
2454 &DocumentHandle {
2455 file_hash: String::new(),
2456 ..stored()
2457 },
2458 None,
2459 TranscribePagesOptions::default(),
2460 )
2461 .unwrap_err();
2462
2463 for refusal in [&spreadsheet, &unstored] {
2464 assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
2465 }
2466
2467 assert!(spreadsheet.message().contains("reads the pages of a PDF"));
2468 assert!(session.calls().is_empty());
2469
2470 transcribe_pages(
2471 &DocumentHandle {
2472 mime_type: "Application/PDF; version=1.7".to_string(),
2473 ..stored()
2474 },
2475 None,
2476 TranscribePagesOptions::default(),
2477 )
2478 .expect("a PDF type with parameters or in capitals is still a PDF");
2479
2480 assert_eq!(session.calls().len(), 1);
2481 }
2482
2483 #[test]
2484 fn an_enrolment_answers_with_the_id_the_face_was_filed_under() {
2485 let session = testing::install(|name, params| {
2486 assert_eq!(name, FACE_ENROLL);
2487 assert_eq!(params["subject_id"], json!("EMP-42"));
2488 assert_eq!(params["image"], json!("iVBORw0KGgo"));
2489
2490 Ok(json!({ "face_id": "FACE-1" }))
2491 });
2492
2493 assert_eq!(
2494 enroll_face("EMP-42", json!("iVBORw0KGgo")).unwrap(),
2495 "FACE-1"
2496 );
2497 assert_eq!(session.calls().len(), 1);
2498 }
2499
2500 #[test]
2501 fn an_enrolment_uploads_a_pending_image_first() {
2502 let session = testing::install(|name, _params| {
2503 if name == UPLOAD_EPHEMERAL {
2504 return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
2505 }
2506
2507 Ok(json!({ "face_id": "FACE-1" }))
2508 });
2509
2510 enroll_face("EMP-42", json!({ "file_hash": "abc", "pending": true })).unwrap();
2511
2512 let calls = session.calls();
2513
2514 assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
2515 assert_eq!(
2516 calls[1].params["image"],
2517 json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" })
2518 );
2519 }
2520
2521 #[test]
2522 fn an_enrolment_without_a_subject_or_an_image_is_refused() {
2523 let session = testing::install(|_name, _params| Ok(json!({ "face_id": "FACE-1" })));
2524
2525 assert_eq!(
2526 enroll_face(" ", json!("image"))
2527 .unwrap_err()
2528 .code()
2529 .as_str(),
2530 "INVALID_TOOL_INPUT"
2531 );
2532 assert_eq!(
2533 enroll_face("EMP-42", json!(null))
2534 .unwrap_err()
2535 .code()
2536 .as_str(),
2537 "INVALID_TOOL_INPUT"
2538 );
2539 assert!(session.calls().is_empty());
2540 }
2541
2542 #[test]
2543 fn an_enrolment_that_answers_without_an_id_is_reported_rather_than_guessed_at() {
2544 let _session = testing::install(|_name, _params| Ok(json!({ "enrolled": true })));
2545
2546 let error = enroll_face("EMP-42", json!("image")).unwrap_err();
2547
2548 assert!(matches!(error, Error::Json(_)));
2549 assert_eq!(error.code().as_str(), "ACTION_FAILED");
2550 }
2551
2552 #[test]
2553 fn a_search_carries_only_the_narrowing_it_was_given() {
2554 let session = testing::install(|name, params| {
2555 assert_eq!(name, FACE_SEARCH);
2556
2557 Ok(json!({ "matches": params["options"].clone() }))
2558 });
2559
2560 let wide: Value = search_face(json!("image"), FaceSearch::default()).unwrap();
2561
2562 let narrow: Value = search_face(
2563 json!("image"),
2564 FaceSearch {
2565 max_faces: Some(3),
2566 similarity_threshold: Some(92.5),
2567 },
2568 )
2569 .unwrap();
2570
2571 assert_eq!(wide["matches"], json!({}), "the platform's own defaults");
2572 assert_eq!(
2573 narrow["matches"],
2574 json!({ "max_faces": 3, "similarity_threshold": 92.5 })
2575 );
2576 assert_eq!(session.calls().len(), 2);
2577 }
2578
2579 #[test]
2580 fn a_search_answers_with_the_type_the_call_asked_for() {
2581 #[derive(Debug, Deserialize, PartialEq)]
2582 struct Match {
2583 similarity: f64,
2584 subject_id: String,
2585 }
2586
2587 let _session = testing::install(|_name, _params| {
2588 Ok(json!([{ "similarity": 99.1, "subject_id": "EMP-42" }]))
2589 });
2590
2591 let found: Vec<Match> = search_face(json!("image"), FaceSearch::default()).unwrap();
2592
2593 assert_eq!(
2594 found,
2595 vec![Match {
2596 similarity: 99.1,
2597 subject_id: "EMP-42".to_string()
2598 }]
2599 );
2600 }
2601
2602 #[test]
2603 fn a_search_with_no_image_is_refused_before_anything_is_sent() {
2604 let session = testing::install(|_name, _params| Ok(json!([])));
2605
2606 let error = search_face::<Value>(json!(null), FaceSearch::default()).unwrap_err();
2607
2608 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
2609 assert!(session.calls().is_empty());
2610 }
2611
2612 #[test]
2613 fn a_removal_reports_the_ids_the_platform_says_it_removed() {
2614 let session = testing::install(|name, params| {
2615 assert_eq!(name, FACE_DELETE);
2616 assert_eq!(params["face_ids"], json!(["FACE-1", "FACE-2"]));
2617
2618 Ok(json!({ "deleted": ["FACE-1"] }))
2619 });
2620
2621 let removed = delete_face(&["FACE-1".to_string(), "FACE-2".to_string()]).unwrap();
2622
2623 assert_eq!(removed, ["FACE-1"]);
2624 assert_eq!(session.calls().len(), 1);
2625 }
2626
2627 #[test]
2628 fn a_removal_reads_a_bare_list_of_ids_as_well() {
2629 let _session = testing::install(|_name, _params| Ok(json!(["FACE-1", "FACE-2"])));
2630
2631 assert_eq!(
2632 delete_face(&["FACE-1".to_string()]).unwrap(),
2633 ["FACE-1", "FACE-2"]
2634 );
2635 }
2636
2637 #[test]
2638 fn a_removal_that_names_nothing_removed_answers_with_nothing() {
2639 let _session = testing::install(|_name, _params| Ok(json!({ "ok": true })));
2640
2641 assert!(delete_face(&["FACE-1".to_string()]).unwrap().is_empty());
2642 }
2643
2644 #[test]
2645 fn a_removal_with_no_ids_is_refused_before_anything_is_sent() {
2646 let session = testing::install(|_name, _params| Ok(json!([])));
2647
2648 let error = delete_face(&[]).unwrap_err();
2649
2650 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
2651 assert!(session.calls().is_empty());
2652 }
2653
2654 #[test]
2655 fn what_the_host_said_survives_into_every_failure() {
2656 let _session = testing::install(|_name, _params| Err(Error::failed("the engine is busy")));
2657
2658 let operation = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
2659 let enrolment = enroll_face("EMP-42", json!("image")).unwrap_err();
2660 let search = search_face::<Value>(json!("image"), FaceSearch::default()).unwrap_err();
2661 let removal = delete_face(&["FACE-1".to_string()]).unwrap_err();
2662
2663 for failure in [&operation, &enrolment, &search, &removal] {
2664 assert!(failure.message().contains("the engine is busy"));
2665 assert!(!failure.fault().hint().is_empty(), "and says what to do");
2666 }
2667 }
2668
2669 #[test]
2670 fn an_answer_that_does_not_fit_the_type_is_reported_as_having_run() {
2671 let _session = testing::install(|_name, _params| Ok(json!({ "data": { "total": 240.0 } })));
2672
2673 let error = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
2674
2675 assert!(matches!(error, Error::Json(_)));
2676 assert_eq!(error.code().as_str(), "ACTION_FAILED");
2677 assert!(error
2678 .fault()
2679 .hint()
2680 .contains("rather than running it again"));
2681 }
2682
2683 #[test]
2684 fn a_timeout_travels_as_the_milliseconds_the_wire_carries() {
2685 assert_eq!(milliseconds(Duration::from_secs(30)), 30_000);
2686 assert_eq!(milliseconds(Duration::from_millis(1)), 1);
2687 assert_eq!(milliseconds(Duration::MAX), u64::MAX);
2688 }
2689
2690 #[test]
2691 fn every_model_names_itself_as_the_wire_spells_it() {
2692 assert_eq!(Model::Lite.to_string(), "lite");
2693 assert_eq!(Model::Medium.to_string(), "medium");
2694 assert_eq!(Model::Large.to_string(), "large");
2695 assert_eq!(Model::Xl.to_string(), "xl");
2696 }
2697}