1use std::fmt;
94use std::time::Duration;
95
96use serde::de::DeserializeOwned;
97use serde::{Deserialize, Serialize};
98use serde_json::{json, Map, Value};
99
100use crate::codes::Code;
101use crate::error::{Error, Fault};
102use crate::host;
103use crate::storage::DocumentHandle;
104
105const ORCHESTRATOR: &str = "logic:dev.simple.system/ai-orchestrator";
107
108const UPLOAD_EPHEMERAL: &str = "action:documents/upload-ephemeral";
110
111const FACE_ENROLL: &str = "action:ai/face/enroll";
113
114const FACE_SEARCH: &str = "action:ai/face/search";
116
117const FACE_DELETE: &str = "action:ai/face/delete";
119
120#[non_exhaustive]
125#[derive(Clone, Copy, Debug, PartialEq, Eq)]
126pub enum Model {
127 Lite,
129 Medium,
131 Large,
133 Xl,
135}
136
137impl Model {
138 pub fn as_str(&self) -> &str {
140 match self {
141 Model::Lite => "lite",
142 Model::Medium => "medium",
143 Model::Large => "large",
144 Model::Xl => "xl",
145 }
146 }
147}
148
149impl fmt::Display for Model {
150 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
151 formatter.write_str(self.as_str())
152 }
153}
154
155#[non_exhaustive]
163#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]
164#[serde(rename_all = "lowercase")]
165pub enum Delivery {
166 Document,
169 Text,
171}
172
173#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]
182pub struct Pages {
183 pub first_page: u32,
185 pub last_page: u32,
187}
188
189impl Pages {
190 pub fn new(first: u32, last: u32) -> Pages {
192 Pages {
193 first_page: first,
194 last_page: last,
195 }
196 }
197}
198
199#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
253pub struct DocumentInput {
254 #[serde(flatten)]
257 pub file: DocumentHandle,
258
259 #[serde(default, flatten)]
261 pub pages: Option<Pages>,
262
263 #[serde(default, skip_serializing_if = "Option::is_none")]
267 pub deliver_as: Option<Delivery>,
268}
269
270#[derive(Clone, Debug)]
284pub struct Options {
285 pub model: Option<Model>,
287
288 pub system_prompt: Option<String>,
291
292 pub temperature: Option<f64>,
295
296 pub reasoning: bool,
299
300 pub reasoning_budget: Option<u32>,
303
304 pub regenerate: bool,
307
308 pub timeout: Option<Duration>,
310}
311
312impl Default for Options {
313 fn default() -> Options {
315 Options {
316 model: None,
317 system_prompt: None,
318 temperature: None,
319 reasoning: true,
320 reasoning_budget: None,
321 regenerate: false,
322 timeout: None,
323 }
324 }
325}
326
327#[derive(Clone, Debug, Default, PartialEq, Eq)]
329pub enum Participants {
330 #[default]
332 Ignore,
333
334 Detect,
337
338 Named(Vec<String>),
341}
342
343impl Participants {
344 fn wanted(&self) -> bool {
346 !matches!(self, Participants::Ignore)
347 }
348
349 fn names(&self) -> Option<String> {
351 match self {
352 Participants::Named(names) if !names.is_empty() => Some(names.join(", ")),
353 _ => None,
354 }
355 }
356}
357
358#[derive(Clone, Debug, Default)]
363pub struct TranscribeOptions {
364 pub include_transcript: bool,
366
367 pub include_timestamps: bool,
370
371 pub summarize: bool,
373
374 pub participants: Participants,
376}
377
378#[derive(Clone, Debug, Default, Deserialize)]
383#[serde(default)]
384pub struct Transcript {
385 pub language: String,
387
388 pub transcript: Option<String>,
390
391 pub summary: Option<String>,
393
394 pub participants: Vec<String>,
396}
397
398#[derive(Clone, Debug)]
400pub struct Execution<T> {
401 pub data: T,
403
404 pub metadata: Metadata,
406}
407
408#[derive(Clone, Debug, Default, PartialEq, Eq)]
410pub struct Metadata {
411 pub input_tokens: u64,
413
414 pub output_tokens: u64,
416
417 pub reasoning_tokens: Option<u64>,
419
420 pub reasoning: Option<String>,
422}
423
424#[derive(Clone, Debug, Default)]
426pub struct FaceSearch {
427 pub max_faces: Option<u32>,
429
430 pub similarity_threshold: Option<f64>,
433}
434
435pub fn extract<T: DeserializeOwned>(
470 input: Value,
471 prompt: &str,
472 schema: Value,
473 options: Options,
474) -> Result<Execution<T>, Error> {
475 refuse_empty(
476 &input,
477 "extract needs something to read.",
478 "Pass the text, the document handle, or the object the extraction is to read.",
479 )?;
480 refuse_empty_prompt(prompt, "extract")?;
481
482 if !schema.is_object() {
483 return Err(
484 Error::invalid("extract needs a JSON Schema object describing the answer.").hint(
485 "Pass a schema object naming the type and the properties the answer is to have.",
486 ),
487 );
488 }
489
490 run("extract", input, prompt, Some(schema), &options)
491}
492
493pub fn summarize(input: Value, prompt: &str, options: Options) -> Result<Execution<String>, Error> {
512 refuse_empty(
513 &input,
514 "summarize needs something to read.",
515 "Pass the text, the document handle, or the object the summary is to be written from.",
516 )?;
517 refuse_empty_prompt(prompt, "summarize")?;
518
519 run("summarize", input, prompt, None, &options)
520}
521
522pub fn transcribe(
557 document: Value,
558 wanted: TranscribeOptions,
559 options: Options,
560) -> Result<Execution<Transcript>, Error> {
561 refuse_unless_media(&document)?;
562
563 if !wanted.include_transcript && !wanted.summarize {
564 return Err(
565 Error::invalid("transcribe needs to be told what to produce.")
566 .hint("Set include_transcript, summarize, or both."),
567 );
568 }
569
570 let prompt = transcribe_prompt(&wanted);
571
572 run(
573 "extract",
574 document,
575 &prompt,
576 Some(transcribe_schema(&wanted)),
577 &options,
578 )
579}
580
581pub fn enroll_face(subject_id: &str, image: Value) -> Result<String, Error> {
596 if subject_id.trim().is_empty() {
597 return Err(
598 Error::invalid("enroll_face needs the subject the face belongs to.")
599 .hint("Pass the id the face is to be found under, such as an employee or user id."),
600 );
601 }
602
603 refuse_empty(
604 &image,
605 "enroll_face needs an image of the face.",
606 "Pass a base64 image, or the handle of an uploaded one.",
607 )?;
608
609 let image = upload_pending(image)?;
610
611 let enrolled = host::transport()?
612 .call(
613 FACE_ENROLL.to_string(),
614 json!({ "image": image, "subject_id": subject_id }),
615 )
616 .map_err(|cause| {
617 cause.hint(
618 "Search the subject before enrolling the same face again, and report the failure.",
619 )
620 })?;
621
622 enrolled
623 .get("face_id")
624 .and_then(Value::as_str)
625 .map(str::to_string)
626 .ok_or_else(|| {
627 Error::Json(Fault::new(
628 Code::unspecified(),
629 "The enrolment answered without the id of the face it enrolled.",
630 ))
631 .hint("Search the subject to establish what was enrolled before enrolling again.")
632 })
633}
634
635pub fn search_face<T: DeserializeOwned>(image: Value, options: FaceSearch) -> Result<T, Error> {
658 refuse_empty(
659 &image,
660 "search_face needs an image to search with.",
661 "Pass a base64 image, or the handle of an uploaded one.",
662 )?;
663
664 let image = upload_pending(image)?;
665
666 let mut narrowing = Map::new();
667
668 if let Some(max_faces) = options.max_faces {
669 narrowing.insert("max_faces".to_string(), Value::from(max_faces));
670 }
671
672 if let Some(threshold) = options
673 .similarity_threshold
674 .filter(|value| value.is_finite())
675 {
676 narrowing.insert("similarity_threshold".to_string(), Value::from(threshold));
677 }
678
679 let found = host::transport()?
680 .call(
681 FACE_SEARCH.to_string(),
682 json!({ "image": image, "options": narrowing }),
683 )
684 .map_err(|cause| {
685 cause.hint("Nothing in the collection was changed. Report the search failure.")
686 })?;
687
688 serde_json::from_value(found).map_err(|cause| {
689 Error::Json(Fault::new(
690 Code::unspecified(),
691 format!("The matches could not be read into the type this action asked for: {cause}"),
692 ))
693 .hint("Read the matches as a Value, or name a type that matches what the search answers.")
694 })
695}
696
697pub fn delete_face(face_ids: &[String]) -> Result<Vec<String>, Error> {
712 if face_ids.is_empty() {
713 return Err(Error::invalid("delete_face needs at least one face id.")
714 .hint("Pass the ids enroll_face answered with."));
715 }
716
717 let removed = host::transport()?
718 .call(FACE_DELETE.to_string(), json!({ "face_ids": face_ids }))
719 .map_err(|cause| {
720 cause.hint(
721 "Treat the removal as unfinished: search the collection to establish what is \
722 still in it before deleting again.",
723 )
724 })?;
725
726 let listed = match &removed {
727 Value::Array(ids) => Some(ids),
728 other => other.get("deleted").and_then(Value::as_array),
729 };
730
731 Ok(listed
732 .map(|ids| {
733 ids.iter()
734 .filter_map(Value::as_str)
735 .map(str::to_string)
736 .collect()
737 })
738 .unwrap_or_default())
739}
740
741fn run<T: DeserializeOwned>(
743 operation: &str,
744 input: Value,
745 prompt: &str,
746 schema: Option<Value>,
747 options: &Options,
748) -> Result<Execution<T>, Error> {
749 let input = upload_pending(input)?;
750
751 let answered = host::transport()?
752 .call(
753 ORCHESTRATOR.to_string(),
754 payload(operation, input, prompt, schema, options),
755 )
756 .map_err(|cause| {
757 cause.hint(
758 "No tenant record was changed. Review the input, the prompt and the schema, \
759 and report the failure.",
760 )
761 })?;
762
763 let metadata = metadata_of(answered.get("metadata"));
766 let data = answered.get("data").cloned().unwrap_or(Value::Null);
767
768 let data = serde_json::from_value(data).map_err(|cause| {
769 Error::Json(Fault::new(
770 Code::unspecified(),
771 format!("The {operation} answer could not be read into the type this action asked for: {cause}"),
772 ))
773 .hint(
774 "The operation ran. Read the answer as a Value, or name a type that matches the \
775 schema, rather than running it again.",
776 )
777 })?;
778
779 Ok(Execution { data, metadata })
780}
781
782fn payload(
787 operation: &str,
788 input: Value,
789 prompt: &str,
790 schema: Option<Value>,
791 options: &Options,
792) -> Value {
793 let mut universal = Map::new();
796
797 universal.insert("reasoning".to_string(), Value::Bool(options.reasoning));
798
799 if let Some(budget) = options.reasoning_budget {
800 universal.insert("reasoning_budget".to_string(), Value::from(budget));
801 }
802
803 if let Some(temperature) = options.temperature.filter(|value| value.is_finite()) {
804 universal.insert("temperature".to_string(), Value::from(temperature));
805 }
806
807 let mut payload = Map::new();
808
809 payload.insert("operation".to_string(), Value::from(operation));
810 payload.insert("input".to_string(), input);
811 payload.insert("prompt".to_string(), Value::from(prompt));
812 payload.insert("options".to_string(), Value::Object(universal));
813 payload.insert("regenerate".to_string(), Value::Bool(options.regenerate));
814
815 if let Some(schema) = schema {
816 payload.insert("schema".to_string(), schema);
817 }
818
819 if let Some(model) = options.model {
820 payload.insert("model".to_string(), Value::from(model.as_str()));
821 }
822
823 if let Some(system_prompt) = &options.system_prompt {
824 payload.insert(
825 "systemPrompt".to_string(),
826 Value::from(system_prompt.as_str()),
827 );
828 }
829
830 if let Some(timeout) = options.timeout {
831 payload.insert("timeout".to_string(), Value::from(milliseconds(timeout)));
832 }
833
834 Value::Object(payload)
835}
836
837fn milliseconds(timeout: Duration) -> u64 {
839 u64::try_from(timeout.as_millis()).unwrap_or(u64::MAX)
840}
841
842fn metadata_of(metadata: Option<&Value>) -> Metadata {
844 let Some(metadata) = metadata else {
845 return Metadata::default();
846 };
847
848 Metadata {
849 input_tokens: count(metadata, "input_tokens").unwrap_or(0),
850 output_tokens: count(metadata, "output_tokens").unwrap_or(0),
851 reasoning_tokens: count(metadata, "reasoning_tokens"),
852 reasoning: metadata
853 .get("reasoning")
854 .and_then(Value::as_str)
855 .map(str::to_string),
856 }
857}
858
859fn count(metadata: &Value, key: &str) -> Option<u64> {
861 metadata.get(key).and_then(Value::as_u64)
862}
863
864fn upload_pending(value: Value) -> Result<Value, Error> {
870 if is_pending(&value) {
871 let stored = host::transport()?
872 .call(UPLOAD_EPHEMERAL.to_string(), value.clone())
873 .map_err(|cause| {
874 cause.hint(
875 "The file was not uploaded and the operation did not run. Upload the file, \
876 then pass the handle that upload answered with.",
877 )
878 })?;
879
880 return Ok(stored_handle(value, stored));
881 }
882
883 if let Value::Array(items) = value {
884 let mut uploaded = Vec::with_capacity(items.len());
885
886 for item in items {
887 uploaded.push(upload_pending(item)?);
888 }
889
890 return Ok(Value::Array(uploaded));
891 }
892
893 Ok(value)
894}
895
896fn stored_handle(handle: Value, stored: Value) -> Value {
914 match (handle, stored) {
915 (Value::Object(mut handle), Value::Object(stored)) => {
916 handle.remove("pending");
917 handle.extend(stored);
918
919 Value::Object(handle)
920 }
921 (_, stored) => stored,
922 }
923}
924
925fn is_pending(value: &Value) -> bool {
930 value.get("pending").and_then(Value::as_bool) == Some(true) && has_file_hash(value)
931}
932
933fn has_file_hash(value: &Value) -> bool {
935 value
936 .get("file_hash")
937 .and_then(Value::as_str)
938 .is_some_and(|hash| !hash.is_empty())
939}
940
941fn refuse_empty(value: &Value, message: &str, hint: &str) -> Result<(), Error> {
943 let empty = match value {
944 Value::Null => true,
945 Value::String(text) => text.is_empty(),
946 _ => false,
947 };
948
949 if empty {
950 return Err(Error::invalid(message).hint(hint));
951 }
952
953 Ok(())
954}
955
956fn refuse_empty_prompt(prompt: &str, operation: &str) -> Result<(), Error> {
958 if prompt.trim().is_empty() {
959 return Err(Error::invalid(format!("{operation} needs a prompt."))
960 .hint("Say what the operation is to produce, in a sentence the model can act on."));
961 }
962
963 Ok(())
964}
965
966fn refuse_unless_media(document: &Value) -> Result<(), Error> {
968 if !has_file_hash(document) {
969 return Err(
970 Error::invalid("transcribe needs a document handle to work on.").hint(
971 "Pass the handle of the uploaded file, the one carrying file_hash and mime_type.",
972 ),
973 );
974 }
975
976 let media = document
977 .get("mime_type")
978 .and_then(Value::as_str)
979 .map(str::to_lowercase)
980 .is_some_and(|mime| mime.starts_with("audio/") || mime.starts_with("video/"));
981
982 if !media {
983 return Err(Error::invalid("transcribe works on audio and video.")
984 .hint("Pass a handle whose mime_type begins audio/ or video/."));
985 }
986
987 Ok(())
988}
989
990fn transcribe_schema(wanted: &TranscribeOptions) -> Value {
992 let identify = wanted.participants.wanted();
993
994 let mut properties = Map::new();
995 let mut required = vec![Value::from("language")];
996
997 properties.insert(
998 "language".to_string(),
999 json!({
1000 "description": "The detected language of the audio (ISO 639-1 code, e.g., \"en\", \"es\")",
1001 "type": "string"
1002 }),
1003 );
1004
1005 if wanted.include_transcript {
1006 let description = match (identify, wanted.include_timestamps) {
1007 (true, true) => {
1008 "The full transcript with participant labels and timestamps. \
1009 Format: [MM:SS] Participant Name: text"
1010 }
1011 (true, false) => {
1012 "The full transcript with participant labels. Format: Participant Name: text"
1013 }
1014 (false, true) => "The full transcript with timestamps. Format: [MM:SS] text",
1015 (false, false) => "The full transcript of the audio",
1016 };
1017
1018 properties.insert(
1019 "transcript".to_string(),
1020 json!({ "description": description, "type": "string" }),
1021 );
1022 required.push(Value::from("transcript"));
1023 }
1024
1025 if wanted.summarize {
1026 let description = if identify {
1027 "A concise summary of the audio content, including key points from each participant"
1028 } else {
1029 "A concise summary of the audio content"
1030 };
1031
1032 properties.insert(
1033 "summary".to_string(),
1034 json!({ "description": description, "type": "string" }),
1035 );
1036 required.push(Value::from("summary"));
1037 }
1038
1039 if identify {
1040 properties.insert(
1041 "participants".to_string(),
1042 json!({
1043 "description": "List of identified participants in the audio",
1044 "items": { "type": "string" },
1045 "type": "array"
1046 }),
1047 );
1048 required.push(Value::from("participants"));
1049 }
1050
1051 json!({ "properties": properties, "required": required, "type": "object" })
1052}
1053
1054fn transcribe_prompt(wanted: &TranscribeOptions) -> String {
1056 let identify = wanted.participants.wanted();
1057 let names = wanted.participants.names();
1058
1059 let mut prompt = String::from("Analyze this audio/video file and provide:\n");
1060
1061 if wanted.include_transcript {
1062 if identify {
1063 match &names {
1064 Some(names) => {
1065 prompt.push_str("- A complete transcript identifying these participants: ");
1066 prompt.push_str(names);
1067 prompt.push_str(". ");
1068 }
1069 None => prompt.push_str(
1070 "- A complete transcript with participant identification \
1071 (label participants as Participant 1, Participant 2, etc.). ",
1072 ),
1073 }
1074
1075 if wanted.include_timestamps {
1076 prompt.push_str(
1077 "Include timestamps in [MM:SS] format before each participant segment.\n",
1078 );
1079 } else {
1080 prompt.push_str("Format each line as \"Participant Name: text\".\n");
1081 }
1082 } else if wanted.include_timestamps {
1083 prompt.push_str(
1084 "- A complete transcript with timestamps in [MM:SS] format before each segment\n",
1085 );
1086 } else {
1087 prompt.push_str("- A complete transcript of all spoken content\n");
1088 }
1089 }
1090
1091 if wanted.summarize {
1092 if identify {
1093 prompt.push_str("- A concise summary highlighting key points from each participant\n");
1094 } else {
1095 prompt.push_str("- A concise summary of the main points and key information\n");
1096 }
1097 }
1098
1099 if identify {
1100 match &names {
1101 Some(names) => {
1102 prompt.push_str("- Identify and distinguish between these participants: ");
1103 prompt.push_str(names);
1104 prompt.push('\n');
1105 }
1106 None => prompt.push_str("- Identify and list all distinct participants in the audio\n"),
1107 }
1108 }
1109
1110 prompt.push_str("- The detected language code (ISO 639-1 format)\n");
1111
1112 prompt
1113}
1114
1115#[cfg(test)]
1116mod tests {
1117 use serde_json::json;
1118
1119 use super::*;
1120 use crate::testing;
1121
1122 fn answered() -> Value {
1124 json!({ "data": { "ok": true }, "metadata": { "input_tokens": 1, "output_tokens": 2 } })
1125 }
1126
1127 fn stored() -> DocumentHandle {
1129 DocumentHandle {
1130 file_hash: "ffce20f1".to_string(),
1131 filename: "contract.pdf".to_string(),
1132 mime_type: "application/pdf".to_string(),
1133 size: 1_234,
1134 storage_path: "acme/documents/ffce20f1".to_string(),
1135 }
1136 }
1137
1138 #[test]
1139 fn a_document_input_travels_as_the_handle_with_the_keys_the_engine_reads() {
1140 let sent = json!(DocumentInput {
1141 file: stored(),
1142 pages: Some(Pages::new(12, 30)),
1143 deliver_as: Some(Delivery::Text),
1144 });
1145
1146 assert_eq!(sent["storage_path"], json!("acme/documents/ffce20f1"));
1147 assert_eq!(sent["file_hash"], json!("ffce20f1"));
1148 assert_eq!(sent["mime_type"], json!("application/pdf"));
1149 assert_eq!(
1150 sent["first_page"],
1151 json!(12),
1152 "a range travels as the two keys the engine reads, not as a nested one"
1153 );
1154 assert_eq!(sent["last_page"], json!(30));
1155 assert_eq!(sent["deliver_as"], json!("text"));
1156 }
1157
1158 #[test]
1159 fn a_document_input_that_asks_for_nothing_carries_neither_key() {
1160 let sent = json!(DocumentInput {
1161 file: stored(),
1162 ..Default::default()
1163 });
1164
1165 assert_eq!(sent["filename"], json!("contract.pdf"));
1166 assert_eq!(
1167 sent.get("deliver_as"),
1168 None,
1169 "asking for nothing says nothing, so the default stays the engine's"
1170 );
1171 assert_eq!(sent.get("first_page"), None);
1172 assert_eq!(sent.get("last_page"), None);
1173 }
1174
1175 #[test]
1176 fn an_extraction_asks_the_primitive_and_answers_with_the_type_it_was_asked_for() {
1177 #[derive(Debug, Deserialize, PartialEq)]
1178 struct Invoice {
1179 number: String,
1180 total: f64,
1181 }
1182
1183 let session = testing::install(|name, params| {
1184 assert_eq!(name, ORCHESTRATOR);
1185 assert_eq!(params["operation"], json!("extract"));
1186 assert_eq!(params["prompt"], json!("Read it."));
1187 assert_eq!(params["input"], json!("INV-8, 240.00"));
1188 assert_eq!(params["schema"]["type"], json!("object"));
1189
1190 Ok(json!({
1191 "data": { "number": "INV-8", "total": 240.0 },
1192 "metadata": { "input_tokens": 11, "output_tokens": 3 }
1193 }))
1194 });
1195
1196 let read: Execution<Invoice> = extract(
1197 json!("INV-8, 240.00"),
1198 "Read it.",
1199 json!({ "type": "object" }),
1200 Options::default(),
1201 )
1202 .unwrap();
1203
1204 assert_eq!(
1205 read.data,
1206 Invoice {
1207 number: "INV-8".to_string(),
1208 total: 240.0
1209 }
1210 );
1211 assert_eq!(read.metadata.input_tokens, 11);
1212 assert_eq!(read.metadata.output_tokens, 3);
1213 assert_eq!(session.calls().len(), 1);
1214 }
1215
1216 #[test]
1217 fn a_default_call_reasons_does_not_regenerate_and_leaves_the_rest_to_the_platform() {
1218 let session = testing::install(|_name, _params| Ok(answered()));
1219
1220 let _: Execution<Value> = extract(
1221 json!("text"),
1222 "Read it.",
1223 json!({ "type": "object" }),
1224 Options::default(),
1225 )
1226 .unwrap();
1227
1228 let sent = session.calls()[0].params.clone();
1229
1230 assert_eq!(sent["options"], json!({ "reasoning": true }));
1231 assert_eq!(sent["regenerate"], json!(false));
1232 assert!(sent.get("model").is_none());
1233 assert!(sent.get("systemPrompt").is_none());
1234 assert!(sent.get("timeout").is_none());
1235 }
1236
1237 #[test]
1238 fn every_option_that_was_set_travels_with_the_operation() {
1239 let session = testing::install(|_name, _params| Ok(answered()));
1240
1241 let _: Execution<Value> = extract(
1242 json!("text"),
1243 "Read it.",
1244 json!({ "type": "object" }),
1245 Options {
1246 model: Some(Model::Xl),
1247 system_prompt: Some("You are an auditor.".to_string()),
1248 temperature: Some(0.25),
1249 reasoning: false,
1250 reasoning_budget: Some(2_048),
1251 regenerate: true,
1252 timeout: Some(Duration::from_secs(90)),
1253 },
1254 )
1255 .unwrap();
1256
1257 let sent = session.calls()[0].params.clone();
1258
1259 assert_eq!(sent["model"], json!("xl"));
1260 assert_eq!(sent["systemPrompt"], json!("You are an auditor."));
1261 assert_eq!(sent["regenerate"], json!(true));
1262 assert_eq!(sent["timeout"], json!(90_000));
1263 assert_eq!(
1264 sent["options"],
1265 json!({ "reasoning": false, "reasoning_budget": 2_048, "temperature": 0.25 })
1266 );
1267 }
1268
1269 #[test]
1270 fn a_summary_answers_with_the_prose_and_carries_no_schema() {
1271 let session = testing::install(|_name, params| {
1272 assert_eq!(params["operation"], json!("summarize"));
1273 assert!(params.get("schema").is_none());
1274
1275 Ok(json!({ "data": "A refund was agreed.", "metadata": { "output_tokens": 5 } }))
1276 });
1277
1278 let written = summarize(json!("A long thread."), "One sentence.", Options::default())
1279 .expect("a summary answers with prose");
1280
1281 assert_eq!(written.data, "A refund was agreed.");
1282 assert_eq!(written.metadata.output_tokens, 5);
1283 assert_eq!(session.calls().len(), 1);
1284 }
1285
1286 #[test]
1287 fn a_pending_document_is_uploaded_before_the_operation_reads_it() {
1288 let session = testing::install(|name, _params| {
1289 if name == UPLOAD_EPHEMERAL {
1290 return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
1291 }
1292
1293 Ok(answered())
1294 });
1295
1296 let _: Execution<Value> = extract(
1297 json!({ "file_hash": "abc", "pending": true }),
1298 "Read it.",
1299 json!({ "type": "object" }),
1300 Options::default(),
1301 )
1302 .unwrap();
1303
1304 let calls = session.calls();
1305
1306 assert_eq!(calls.len(), 2);
1307 assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
1308 assert_eq!(calls[1].name, ORCHESTRATOR);
1309 assert_eq!(
1310 calls[1].params["input"],
1311 json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }),
1312 "the operation reads the handle the upload answered with"
1313 );
1314 }
1315
1316 #[test]
1317 fn a_pending_document_is_read_the_way_the_caller_asked_for_it() {
1318 let session = testing::install(|name, _params| {
1319 if name == UPLOAD_EPHEMERAL {
1320 return Ok(json!({
1321 "file_hash": "ffce20f1",
1322 "filename": "contract.pdf",
1323 "mime_type": "application/pdf",
1324 "size": 1_234,
1325 "storage_path": "acme/ephemeral/ffce20f1"
1326 }));
1327 }
1328
1329 Ok(answered())
1330 });
1331
1332 let _: Execution<Value> = extract(
1333 json!({
1334 "file_hash": "staged",
1335 "first_page": 12,
1336 "last_page": 30,
1337 "pending": true,
1338 "deliver_as": "text",
1339 "storage_path": "acme/staged/staged"
1340 }),
1341 "Read it.",
1342 json!({ "type": "object" }),
1343 Options::default(),
1344 )
1345 .unwrap();
1346
1347 let calls = session.calls();
1348 let sent = calls[1].params["input"].clone();
1349
1350 assert_eq!(
1351 sent["deliver_as"],
1352 json!("text"),
1353 "the caller said how the file was to be sent"
1354 );
1355 assert_eq!(
1356 sent["first_page"],
1357 json!(12),
1358 "the caller asked for a range"
1359 );
1360 assert_eq!(sent["last_page"], json!(30), "the caller asked for a range");
1361 assert_eq!(
1362 sent["file_hash"],
1363 json!("ffce20f1"),
1364 "the file is the one the upload stored"
1365 );
1366 assert_eq!(
1367 sent["storage_path"],
1368 json!("acme/ephemeral/ffce20f1"),
1369 "the file is read from where the upload put it"
1370 );
1371 assert_eq!(sent["filename"], json!("contract.pdf"));
1372 assert_eq!(sent["mime_type"], json!("application/pdf"));
1373 assert_eq!(sent["size"], json!(1_234));
1374 assert!(
1375 sent.get("pending").is_none(),
1376 "the file is stored, so the handle may not still call itself pending"
1377 );
1378 }
1379
1380 #[test]
1381 fn a_document_that_is_already_stored_is_read_where_it_is() {
1382 let session = testing::install(|_name, _params| Ok(answered()));
1383
1384 let handle = json!({ "file_hash": "abc", "mime_type": "application/pdf" });
1385
1386 let _: Execution<Value> = extract(
1387 handle.clone(),
1388 "Read it.",
1389 json!({ "type": "object" }),
1390 Options::default(),
1391 )
1392 .unwrap();
1393
1394 let calls = session.calls();
1395
1396 assert_eq!(calls.len(), 1, "nothing was uploaded");
1397 assert_eq!(calls[0].params["input"], handle);
1398 }
1399
1400 #[test]
1401 fn a_list_of_documents_is_uploaded_item_by_item() {
1402 let session = testing::install(|name, params| {
1403 if name == UPLOAD_EPHEMERAL {
1404 let hash = params["file_hash"].as_str().unwrap_or_default();
1405
1406 return Ok(json!({
1407 "file_hash": hash,
1408 "storage_path": format!("ephemeral/{hash}")
1409 }));
1410 }
1411
1412 Ok(answered())
1413 });
1414
1415 let _: Execution<Value> = extract(
1416 json!([
1417 { "file_hash": "one", "pending": true },
1418 { "file_hash": "two", "mime_type": "image/png" },
1419 { "file_hash": "three", "pending": true }
1420 ]),
1421 "Read them.",
1422 json!({ "type": "object" }),
1423 Options::default(),
1424 )
1425 .unwrap();
1426
1427 let calls = session.calls();
1428
1429 assert_eq!(calls.len(), 3, "two uploads and the operation");
1430 assert_eq!(
1431 calls[2].params["input"],
1432 json!([
1433 { "file_hash": "one", "storage_path": "ephemeral/one" },
1434 { "file_hash": "two", "mime_type": "image/png" },
1435 { "file_hash": "three", "storage_path": "ephemeral/three" }
1436 ])
1437 );
1438 }
1439
1440 #[test]
1441 fn a_handle_is_pending_only_while_it_says_so_and_carries_a_hash_to_upload_by() {
1442 assert!(is_pending(&json!({ "file_hash": "abc", "pending": true })));
1443 assert!(!is_pending(&json!({ "file_hash": "abc" })));
1444 assert!(!is_pending(&json!({ "pending": true })));
1445 assert!(!is_pending(&json!({ "file_hash": "", "pending": true })));
1446 assert!(!is_pending(
1447 &json!({ "file_hash": "abc", "pending": "yes" })
1448 ));
1449 assert!(!is_pending(&json!("some words")));
1450 assert!(!is_pending(&json!([
1451 { "file_hash": "abc", "pending": true }
1452 ])));
1453 }
1454
1455 #[test]
1456 fn an_answer_that_reports_nothing_about_its_cost_is_still_an_answer() {
1457 let _session = testing::install(|_name, _params| Ok(json!({ "data": "done" })));
1458
1459 let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
1460
1461 assert_eq!(written.data, "done");
1462 assert_eq!(written.metadata, Metadata::default());
1463 }
1464
1465 #[test]
1466 fn reasoning_reaches_the_caller_when_the_run_reported_it() {
1467 let _session = testing::install(|_name, _params| {
1468 Ok(json!({
1469 "data": "done",
1470 "metadata": {
1471 "input_tokens": 9,
1472 "output_tokens": 4,
1473 "reasoning": "Read the total from the last line.",
1474 "reasoning_tokens": 120
1475 }
1476 }))
1477 });
1478
1479 let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
1480
1481 assert_eq!(written.metadata.reasoning_tokens, Some(120));
1482 assert_eq!(
1483 written.metadata.reasoning.as_deref(),
1484 Some("Read the total from the last line.")
1485 );
1486 }
1487
1488 #[test]
1489 fn an_operation_with_nothing_to_do_is_refused_before_anything_is_sent() {
1490 let session = testing::install(|_name, _params| Ok(answered()));
1491
1492 let missing_input = extract::<Value>(
1493 json!(null),
1494 "Read it.",
1495 json!({ "type": "object" }),
1496 Options::default(),
1497 )
1498 .unwrap_err();
1499
1500 let missing_prompt = extract::<Value>(
1501 json!("text"),
1502 " ",
1503 json!({ "type": "object" }),
1504 Options::default(),
1505 )
1506 .unwrap_err();
1507
1508 let missing_schema =
1509 extract::<Value>(json!("text"), "Read it.", json!([]), Options::default()).unwrap_err();
1510
1511 let missing_summary_input =
1512 summarize(json!(""), "One sentence.", Options::default()).unwrap_err();
1513
1514 for refusal in [
1515 &missing_input,
1516 &missing_prompt,
1517 &missing_schema,
1518 &missing_summary_input,
1519 ] {
1520 assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
1521 }
1522
1523 assert!(session.calls().is_empty());
1524 }
1525
1526 #[test]
1527 fn a_transcription_writes_its_own_schema_and_prompt() {
1528 let session = testing::install(|_name, _params| {
1529 Ok(json!({
1530 "data": { "language": "en", "transcript": "Hello." },
1531 "metadata": { "input_tokens": 400, "output_tokens": 12 }
1532 }))
1533 });
1534
1535 let heard = transcribe(
1536 json!({ "file_hash": "abc", "mime_type": "AUDIO/MPEG" }),
1537 TranscribeOptions {
1538 include_transcript: true,
1539 ..Default::default()
1540 },
1541 Options::default(),
1542 )
1543 .expect("an uppercase mime type is the same mime type");
1544
1545 assert_eq!(heard.data.language, "en");
1546 assert_eq!(heard.data.transcript.as_deref(), Some("Hello."));
1547 assert_eq!(heard.data.summary, None);
1548 assert!(heard.data.participants.is_empty());
1549
1550 let sent = session.calls()[0].params.clone();
1551
1552 assert_eq!(sent["operation"], json!("extract"));
1553 assert_eq!(
1554 sent["schema"]["required"],
1555 json!(["language", "transcript"])
1556 );
1557 assert_eq!(sent["schema"]["properties"]["transcript"]["type"], "string");
1558 assert_eq!(
1559 sent["prompt"],
1560 json!(
1561 "Analyze this audio/video file and provide:\n\
1562 - A complete transcript of all spoken content\n\
1563 - The detected language code (ISO 639-1 format)\n"
1564 )
1565 );
1566 }
1567
1568 #[test]
1569 fn named_participants_reach_both_the_prompt_and_the_schema() {
1570 let session = testing::install(|_name, _params| {
1571 Ok(json!({ "data": { "language": "en", "participants": ["Customer", "Agent"] } }))
1572 });
1573
1574 let heard = transcribe(
1575 json!({ "file_hash": "abc", "mime_type": "video/mp4" }),
1576 TranscribeOptions {
1577 include_transcript: true,
1578 include_timestamps: true,
1579 summarize: true,
1580 participants: Participants::Named(vec![
1581 "Customer".to_string(),
1582 "Agent".to_string(),
1583 ]),
1584 },
1585 Options::default(),
1586 )
1587 .unwrap();
1588
1589 assert_eq!(heard.data.participants, ["Customer", "Agent"]);
1590
1591 let sent = session.calls()[0].params.clone();
1592 let prompt = sent["prompt"].as_str().unwrap_or_default().to_string();
1593
1594 assert_eq!(
1595 sent["schema"]["required"],
1596 json!(["language", "transcript", "summary", "participants"])
1597 );
1598 assert_eq!(
1599 sent["schema"]["properties"]["participants"]["items"]["type"],
1600 json!("string")
1601 );
1602 assert!(prompt.contains("identifying these participants: Customer, Agent. "));
1603 assert!(prompt.contains("Include timestamps in [MM:SS] format"));
1604 assert!(
1605 prompt.contains("- A concise summary highlighting key points from each participant\n")
1606 );
1607 assert!(prompt
1608 .contains("- Identify and distinguish between these participants: Customer, Agent\n"));
1609 }
1610
1611 #[test]
1612 fn detected_participants_are_labelled_rather_than_named() {
1613 let session =
1614 testing::install(|_name, _params| Ok(json!({ "data": { "language": "en" } })));
1615
1616 let _ = transcribe(
1617 json!({ "file_hash": "abc", "mime_type": "audio/wav" }),
1618 TranscribeOptions {
1619 include_transcript: true,
1620 participants: Participants::Detect,
1621 ..Default::default()
1622 },
1623 Options::default(),
1624 )
1625 .unwrap();
1626
1627 let prompt = session.calls()[0].params["prompt"]
1628 .as_str()
1629 .unwrap_or_default()
1630 .to_string();
1631
1632 assert!(prompt.contains("label participants as Participant 1, Participant 2, etc."));
1633 assert!(prompt.contains("Format each line as \"Participant Name: text\".\n"));
1634 assert!(prompt.contains("- Identify and list all distinct participants in the audio\n"));
1635 }
1636
1637 #[test]
1638 fn naming_nobody_asks_for_the_same_thing_as_detecting() {
1639 let wanted = |participants| TranscribeOptions {
1640 include_transcript: true,
1641 participants,
1642 ..Default::default()
1643 };
1644
1645 assert_eq!(
1646 transcribe_prompt(&wanted(Participants::Named(Vec::new()))),
1647 transcribe_prompt(&wanted(Participants::Detect))
1648 );
1649 assert_eq!(
1650 transcribe_schema(&wanted(Participants::Named(Vec::new()))),
1651 transcribe_schema(&wanted(Participants::Detect))
1652 );
1653 }
1654
1655 #[test]
1656 fn a_transcription_that_cannot_run_is_refused_before_anything_is_sent() {
1657 let session = testing::install(|_name, _params| Ok(answered()));
1658
1659 let audio = json!({ "file_hash": "abc", "mime_type": "audio/mpeg" });
1660
1661 let nothing_wanted = transcribe(
1662 audio.clone(),
1663 TranscribeOptions::default(),
1664 Options::default(),
1665 )
1666 .unwrap_err();
1667
1668 let not_media = transcribe(
1669 json!({ "file_hash": "abc", "mime_type": "application/pdf" }),
1670 TranscribeOptions {
1671 include_transcript: true,
1672 ..Default::default()
1673 },
1674 Options::default(),
1675 )
1676 .unwrap_err();
1677
1678 let not_a_handle = transcribe(
1679 json!("some words"),
1680 TranscribeOptions {
1681 summarize: true,
1682 ..Default::default()
1683 },
1684 Options::default(),
1685 )
1686 .unwrap_err();
1687
1688 for refusal in [¬hing_wanted, ¬_media, ¬_a_handle] {
1689 assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
1690 }
1691
1692 assert!(session.calls().is_empty());
1693 }
1694
1695 #[test]
1696 fn an_enrolment_answers_with_the_id_the_face_was_filed_under() {
1697 let session = testing::install(|name, params| {
1698 assert_eq!(name, FACE_ENROLL);
1699 assert_eq!(params["subject_id"], json!("EMP-42"));
1700 assert_eq!(params["image"], json!("iVBORw0KGgo"));
1701
1702 Ok(json!({ "face_id": "FACE-1" }))
1703 });
1704
1705 assert_eq!(
1706 enroll_face("EMP-42", json!("iVBORw0KGgo")).unwrap(),
1707 "FACE-1"
1708 );
1709 assert_eq!(session.calls().len(), 1);
1710 }
1711
1712 #[test]
1713 fn an_enrolment_uploads_a_pending_image_first() {
1714 let session = testing::install(|name, _params| {
1715 if name == UPLOAD_EPHEMERAL {
1716 return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
1717 }
1718
1719 Ok(json!({ "face_id": "FACE-1" }))
1720 });
1721
1722 enroll_face("EMP-42", json!({ "file_hash": "abc", "pending": true })).unwrap();
1723
1724 let calls = session.calls();
1725
1726 assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
1727 assert_eq!(
1728 calls[1].params["image"],
1729 json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" })
1730 );
1731 }
1732
1733 #[test]
1734 fn an_enrolment_without_a_subject_or_an_image_is_refused() {
1735 let session = testing::install(|_name, _params| Ok(json!({ "face_id": "FACE-1" })));
1736
1737 assert_eq!(
1738 enroll_face(" ", json!("image"))
1739 .unwrap_err()
1740 .code()
1741 .as_str(),
1742 "INVALID_TOOL_INPUT"
1743 );
1744 assert_eq!(
1745 enroll_face("EMP-42", json!(null))
1746 .unwrap_err()
1747 .code()
1748 .as_str(),
1749 "INVALID_TOOL_INPUT"
1750 );
1751 assert!(session.calls().is_empty());
1752 }
1753
1754 #[test]
1755 fn an_enrolment_that_answers_without_an_id_is_reported_rather_than_guessed_at() {
1756 let _session = testing::install(|_name, _params| Ok(json!({ "enrolled": true })));
1757
1758 let error = enroll_face("EMP-42", json!("image")).unwrap_err();
1759
1760 assert!(matches!(error, Error::Json(_)));
1761 assert_eq!(error.code().as_str(), "ACTION_FAILED");
1762 }
1763
1764 #[test]
1765 fn a_search_carries_only_the_narrowing_it_was_given() {
1766 let session = testing::install(|name, params| {
1767 assert_eq!(name, FACE_SEARCH);
1768
1769 Ok(json!({ "matches": params["options"].clone() }))
1770 });
1771
1772 let wide: Value = search_face(json!("image"), FaceSearch::default()).unwrap();
1773
1774 let narrow: Value = search_face(
1775 json!("image"),
1776 FaceSearch {
1777 max_faces: Some(3),
1778 similarity_threshold: Some(92.5),
1779 },
1780 )
1781 .unwrap();
1782
1783 assert_eq!(wide["matches"], json!({}), "the platform's own defaults");
1784 assert_eq!(
1785 narrow["matches"],
1786 json!({ "max_faces": 3, "similarity_threshold": 92.5 })
1787 );
1788 assert_eq!(session.calls().len(), 2);
1789 }
1790
1791 #[test]
1792 fn a_search_answers_with_the_type_the_call_asked_for() {
1793 #[derive(Debug, Deserialize, PartialEq)]
1794 struct Match {
1795 similarity: f64,
1796 subject_id: String,
1797 }
1798
1799 let _session = testing::install(|_name, _params| {
1800 Ok(json!([{ "similarity": 99.1, "subject_id": "EMP-42" }]))
1801 });
1802
1803 let found: Vec<Match> = search_face(json!("image"), FaceSearch::default()).unwrap();
1804
1805 assert_eq!(
1806 found,
1807 vec![Match {
1808 similarity: 99.1,
1809 subject_id: "EMP-42".to_string()
1810 }]
1811 );
1812 }
1813
1814 #[test]
1815 fn a_search_with_no_image_is_refused_before_anything_is_sent() {
1816 let session = testing::install(|_name, _params| Ok(json!([])));
1817
1818 let error = search_face::<Value>(json!(null), FaceSearch::default()).unwrap_err();
1819
1820 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
1821 assert!(session.calls().is_empty());
1822 }
1823
1824 #[test]
1825 fn a_removal_reports_the_ids_the_platform_says_it_removed() {
1826 let session = testing::install(|name, params| {
1827 assert_eq!(name, FACE_DELETE);
1828 assert_eq!(params["face_ids"], json!(["FACE-1", "FACE-2"]));
1829
1830 Ok(json!({ "deleted": ["FACE-1"] }))
1831 });
1832
1833 let removed = delete_face(&["FACE-1".to_string(), "FACE-2".to_string()]).unwrap();
1834
1835 assert_eq!(removed, ["FACE-1"]);
1836 assert_eq!(session.calls().len(), 1);
1837 }
1838
1839 #[test]
1840 fn a_removal_reads_a_bare_list_of_ids_as_well() {
1841 let _session = testing::install(|_name, _params| Ok(json!(["FACE-1", "FACE-2"])));
1842
1843 assert_eq!(
1844 delete_face(&["FACE-1".to_string()]).unwrap(),
1845 ["FACE-1", "FACE-2"]
1846 );
1847 }
1848
1849 #[test]
1850 fn a_removal_that_names_nothing_removed_answers_with_nothing() {
1851 let _session = testing::install(|_name, _params| Ok(json!({ "ok": true })));
1852
1853 assert!(delete_face(&["FACE-1".to_string()]).unwrap().is_empty());
1854 }
1855
1856 #[test]
1857 fn a_removal_with_no_ids_is_refused_before_anything_is_sent() {
1858 let session = testing::install(|_name, _params| Ok(json!([])));
1859
1860 let error = delete_face(&[]).unwrap_err();
1861
1862 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
1863 assert!(session.calls().is_empty());
1864 }
1865
1866 #[test]
1867 fn what_the_host_said_survives_into_every_failure() {
1868 let _session = testing::install(|_name, _params| Err(Error::failed("the engine is busy")));
1869
1870 let operation = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
1871 let enrolment = enroll_face("EMP-42", json!("image")).unwrap_err();
1872 let search = search_face::<Value>(json!("image"), FaceSearch::default()).unwrap_err();
1873 let removal = delete_face(&["FACE-1".to_string()]).unwrap_err();
1874
1875 for failure in [&operation, &enrolment, &search, &removal] {
1876 assert!(failure.message().contains("the engine is busy"));
1877 assert!(!failure.fault().hint().is_empty(), "and says what to do");
1878 }
1879 }
1880
1881 #[test]
1882 fn an_answer_that_does_not_fit_the_type_is_reported_as_having_run() {
1883 let _session = testing::install(|_name, _params| Ok(json!({ "data": { "total": 240.0 } })));
1884
1885 let error = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
1886
1887 assert!(matches!(error, Error::Json(_)));
1888 assert_eq!(error.code().as_str(), "ACTION_FAILED");
1889 assert!(error
1890 .fault()
1891 .hint()
1892 .contains("rather than running it again"));
1893 }
1894
1895 #[test]
1896 fn a_timeout_travels_as_the_milliseconds_the_wire_carries() {
1897 assert_eq!(milliseconds(Duration::from_secs(30)), 30_000);
1898 assert_eq!(milliseconds(Duration::from_millis(1)), 1);
1899 assert_eq!(milliseconds(Duration::MAX), u64::MAX);
1900 }
1901
1902 #[test]
1903 fn every_model_names_itself_as_the_wire_spells_it() {
1904 assert_eq!(Model::Lite.to_string(), "lite");
1905 assert_eq!(Model::Medium.to_string(), "medium");
1906 assert_eq!(Model::Large.to_string(), "large");
1907 assert_eq!(Model::Xl.to_string(), "xl");
1908 }
1909}