1use std::fmt;
87use std::time::Duration;
88
89use serde::de::DeserializeOwned;
90use serde::Deserialize;
91use serde_json::{json, Map, Value};
92
93use crate::codes::Code;
94use crate::error::{Error, Fault};
95use crate::host;
96
97const ORCHESTRATOR: &str = "logic:dev.simple.system/ai-orchestrator";
99
100const UPLOAD_EPHEMERAL: &str = "action:documents/upload-ephemeral";
102
103const FACE_ENROLL: &str = "action:ai/face/enroll";
105
106const FACE_SEARCH: &str = "action:ai/face/search";
108
109const FACE_DELETE: &str = "action:ai/face/delete";
111
112#[non_exhaustive]
117#[derive(Clone, Copy, Debug, PartialEq, Eq)]
118pub enum Model {
119 Lite,
121 Medium,
123 Large,
125 Xl,
127}
128
129impl Model {
130 pub fn as_str(&self) -> &str {
132 match self {
133 Model::Lite => "lite",
134 Model::Medium => "medium",
135 Model::Large => "large",
136 Model::Xl => "xl",
137 }
138 }
139}
140
141impl fmt::Display for Model {
142 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
143 formatter.write_str(self.as_str())
144 }
145}
146
147#[derive(Clone, Debug)]
161pub struct Options {
162 pub model: Option<Model>,
164
165 pub system_prompt: Option<String>,
168
169 pub temperature: Option<f64>,
172
173 pub reasoning: bool,
176
177 pub reasoning_budget: Option<u32>,
180
181 pub regenerate: bool,
184
185 pub timeout: Option<Duration>,
187}
188
189impl Default for Options {
190 fn default() -> Options {
192 Options {
193 model: None,
194 system_prompt: None,
195 temperature: None,
196 reasoning: true,
197 reasoning_budget: None,
198 regenerate: false,
199 timeout: None,
200 }
201 }
202}
203
204#[derive(Clone, Debug, Default, PartialEq, Eq)]
206pub enum Participants {
207 #[default]
209 Ignore,
210
211 Detect,
214
215 Named(Vec<String>),
218}
219
220impl Participants {
221 fn wanted(&self) -> bool {
223 !matches!(self, Participants::Ignore)
224 }
225
226 fn names(&self) -> Option<String> {
228 match self {
229 Participants::Named(names) if !names.is_empty() => Some(names.join(", ")),
230 _ => None,
231 }
232 }
233}
234
235#[derive(Clone, Debug, Default)]
240pub struct TranscribeOptions {
241 pub include_transcript: bool,
243
244 pub include_timestamps: bool,
247
248 pub summarize: bool,
250
251 pub participants: Participants,
253}
254
255#[derive(Clone, Debug, Default, Deserialize)]
260#[serde(default)]
261pub struct Transcript {
262 pub language: String,
264
265 pub transcript: Option<String>,
267
268 pub summary: Option<String>,
270
271 pub participants: Vec<String>,
273}
274
275#[derive(Clone, Debug)]
277pub struct Execution<T> {
278 pub data: T,
280
281 pub metadata: Metadata,
283}
284
285#[derive(Clone, Debug, Default, PartialEq, Eq)]
287pub struct Metadata {
288 pub input_tokens: u64,
290
291 pub output_tokens: u64,
293
294 pub reasoning_tokens: Option<u64>,
296
297 pub reasoning: Option<String>,
299}
300
301#[derive(Clone, Debug, Default)]
303pub struct FaceSearch {
304 pub max_faces: Option<u32>,
306
307 pub similarity_threshold: Option<f64>,
310}
311
312pub fn extract<T: DeserializeOwned>(
347 input: Value,
348 prompt: &str,
349 schema: Value,
350 options: Options,
351) -> Result<Execution<T>, Error> {
352 refuse_empty(
353 &input,
354 "extract needs something to read.",
355 "Pass the text, the document handle, or the object the extraction is to read.",
356 )?;
357 refuse_empty_prompt(prompt, "extract")?;
358
359 if !schema.is_object() {
360 return Err(
361 Error::invalid("extract needs a JSON Schema object describing the answer.").hint(
362 "Pass a schema object naming the type and the properties the answer is to have.",
363 ),
364 );
365 }
366
367 run("extract", input, prompt, Some(schema), &options)
368}
369
370pub fn summarize(input: Value, prompt: &str, options: Options) -> Result<Execution<String>, Error> {
389 refuse_empty(
390 &input,
391 "summarize needs something to read.",
392 "Pass the text, the document handle, or the object the summary is to be written from.",
393 )?;
394 refuse_empty_prompt(prompt, "summarize")?;
395
396 run("summarize", input, prompt, None, &options)
397}
398
399pub fn transcribe(
434 document: Value,
435 wanted: TranscribeOptions,
436 options: Options,
437) -> Result<Execution<Transcript>, Error> {
438 refuse_unless_media(&document)?;
439
440 if !wanted.include_transcript && !wanted.summarize {
441 return Err(
442 Error::invalid("transcribe needs to be told what to produce.")
443 .hint("Set include_transcript, summarize, or both."),
444 );
445 }
446
447 let prompt = transcribe_prompt(&wanted);
448
449 run(
450 "extract",
451 document,
452 &prompt,
453 Some(transcribe_schema(&wanted)),
454 &options,
455 )
456}
457
458pub fn enroll_face(subject_id: &str, image: Value) -> Result<String, Error> {
473 if subject_id.trim().is_empty() {
474 return Err(
475 Error::invalid("enroll_face needs the subject the face belongs to.")
476 .hint("Pass the id the face is to be found under, such as an employee or user id."),
477 );
478 }
479
480 refuse_empty(
481 &image,
482 "enroll_face needs an image of the face.",
483 "Pass a base64 image, or the handle of an uploaded one.",
484 )?;
485
486 let image = upload_pending(image)?;
487
488 let enrolled = host::transport()?
489 .call(
490 FACE_ENROLL.to_string(),
491 json!({ "image": image, "subject_id": subject_id }),
492 )
493 .map_err(|cause| {
494 cause.hint(
495 "Search the subject before enrolling the same face again, and report the failure.",
496 )
497 })?;
498
499 enrolled
500 .get("face_id")
501 .and_then(Value::as_str)
502 .map(str::to_string)
503 .ok_or_else(|| {
504 Error::Json(Fault::new(
505 Code::unspecified(),
506 "The enrolment answered without the id of the face it enrolled.",
507 ))
508 .hint("Search the subject to establish what was enrolled before enrolling again.")
509 })
510}
511
512pub fn search_face<T: DeserializeOwned>(image: Value, options: FaceSearch) -> Result<T, Error> {
535 refuse_empty(
536 &image,
537 "search_face needs an image to search with.",
538 "Pass a base64 image, or the handle of an uploaded one.",
539 )?;
540
541 let image = upload_pending(image)?;
542
543 let mut narrowing = Map::new();
544
545 if let Some(max_faces) = options.max_faces {
546 narrowing.insert("max_faces".to_string(), Value::from(max_faces));
547 }
548
549 if let Some(threshold) = options
550 .similarity_threshold
551 .filter(|value| value.is_finite())
552 {
553 narrowing.insert("similarity_threshold".to_string(), Value::from(threshold));
554 }
555
556 let found = host::transport()?
557 .call(
558 FACE_SEARCH.to_string(),
559 json!({ "image": image, "options": narrowing }),
560 )
561 .map_err(|cause| {
562 cause.hint("Nothing in the collection was changed. Report the search failure.")
563 })?;
564
565 serde_json::from_value(found).map_err(|cause| {
566 Error::Json(Fault::new(
567 Code::unspecified(),
568 format!("The matches could not be read into the type this action asked for: {cause}"),
569 ))
570 .hint("Read the matches as a Value, or name a type that matches what the search answers.")
571 })
572}
573
574pub fn delete_face(face_ids: &[String]) -> Result<Vec<String>, Error> {
589 if face_ids.is_empty() {
590 return Err(Error::invalid("delete_face needs at least one face id.")
591 .hint("Pass the ids enroll_face answered with."));
592 }
593
594 let removed = host::transport()?
595 .call(FACE_DELETE.to_string(), json!({ "face_ids": face_ids }))
596 .map_err(|cause| {
597 cause.hint(
598 "Treat the removal as unfinished: search the collection to establish what is \
599 still in it before deleting again.",
600 )
601 })?;
602
603 let listed = match &removed {
604 Value::Array(ids) => Some(ids),
605 other => other.get("deleted").and_then(Value::as_array),
606 };
607
608 Ok(listed
609 .map(|ids| {
610 ids.iter()
611 .filter_map(Value::as_str)
612 .map(str::to_string)
613 .collect()
614 })
615 .unwrap_or_default())
616}
617
618fn run<T: DeserializeOwned>(
620 operation: &str,
621 input: Value,
622 prompt: &str,
623 schema: Option<Value>,
624 options: &Options,
625) -> Result<Execution<T>, Error> {
626 let input = upload_pending(input)?;
627
628 let answered = host::transport()?
629 .call(
630 ORCHESTRATOR.to_string(),
631 payload(operation, input, prompt, schema, options),
632 )
633 .map_err(|cause| {
634 cause.hint(
635 "No tenant record was changed. Review the input, the prompt and the schema, \
636 and report the failure.",
637 )
638 })?;
639
640 let metadata = metadata_of(answered.get("metadata"));
643 let data = answered.get("data").cloned().unwrap_or(Value::Null);
644
645 let data = serde_json::from_value(data).map_err(|cause| {
646 Error::Json(Fault::new(
647 Code::unspecified(),
648 format!("The {operation} answer could not be read into the type this action asked for: {cause}"),
649 ))
650 .hint(
651 "The operation ran. Read the answer as a Value, or name a type that matches the \
652 schema, rather than running it again.",
653 )
654 })?;
655
656 Ok(Execution { data, metadata })
657}
658
659fn payload(
664 operation: &str,
665 input: Value,
666 prompt: &str,
667 schema: Option<Value>,
668 options: &Options,
669) -> Value {
670 let mut universal = Map::new();
673
674 universal.insert("reasoning".to_string(), Value::Bool(options.reasoning));
675
676 if let Some(budget) = options.reasoning_budget {
677 universal.insert("reasoning_budget".to_string(), Value::from(budget));
678 }
679
680 if let Some(temperature) = options.temperature.filter(|value| value.is_finite()) {
681 universal.insert("temperature".to_string(), Value::from(temperature));
682 }
683
684 let mut payload = Map::new();
685
686 payload.insert("operation".to_string(), Value::from(operation));
687 payload.insert("input".to_string(), input);
688 payload.insert("prompt".to_string(), Value::from(prompt));
689 payload.insert("options".to_string(), Value::Object(universal));
690 payload.insert("regenerate".to_string(), Value::Bool(options.regenerate));
691
692 if let Some(schema) = schema {
693 payload.insert("schema".to_string(), schema);
694 }
695
696 if let Some(model) = options.model {
697 payload.insert("model".to_string(), Value::from(model.as_str()));
698 }
699
700 if let Some(system_prompt) = &options.system_prompt {
701 payload.insert(
702 "systemPrompt".to_string(),
703 Value::from(system_prompt.as_str()),
704 );
705 }
706
707 if let Some(timeout) = options.timeout {
708 payload.insert("timeout".to_string(), Value::from(milliseconds(timeout)));
709 }
710
711 Value::Object(payload)
712}
713
714fn milliseconds(timeout: Duration) -> u64 {
716 u64::try_from(timeout.as_millis()).unwrap_or(u64::MAX)
717}
718
719fn metadata_of(metadata: Option<&Value>) -> Metadata {
721 let Some(metadata) = metadata else {
722 return Metadata::default();
723 };
724
725 Metadata {
726 input_tokens: count(metadata, "input_tokens").unwrap_or(0),
727 output_tokens: count(metadata, "output_tokens").unwrap_or(0),
728 reasoning_tokens: count(metadata, "reasoning_tokens"),
729 reasoning: metadata
730 .get("reasoning")
731 .and_then(Value::as_str)
732 .map(str::to_string),
733 }
734}
735
736fn count(metadata: &Value, key: &str) -> Option<u64> {
738 metadata.get(key).and_then(Value::as_u64)
739}
740
741fn upload_pending(value: Value) -> Result<Value, Error> {
747 if is_pending(&value) {
748 return host::transport()?
749 .call(UPLOAD_EPHEMERAL.to_string(), value)
750 .map_err(|cause| {
751 cause.hint(
752 "The file was not uploaded and the operation did not run. Upload the file, \
753 then pass the handle that upload answered with.",
754 )
755 });
756 }
757
758 if let Value::Array(items) = value {
759 let mut uploaded = Vec::with_capacity(items.len());
760
761 for item in items {
762 uploaded.push(upload_pending(item)?);
763 }
764
765 return Ok(Value::Array(uploaded));
766 }
767
768 Ok(value)
769}
770
771fn is_pending(value: &Value) -> bool {
776 value.get("pending").and_then(Value::as_bool) == Some(true) && has_file_hash(value)
777}
778
779fn has_file_hash(value: &Value) -> bool {
781 value
782 .get("file_hash")
783 .and_then(Value::as_str)
784 .is_some_and(|hash| !hash.is_empty())
785}
786
787fn refuse_empty(value: &Value, message: &str, hint: &str) -> Result<(), Error> {
789 let empty = match value {
790 Value::Null => true,
791 Value::String(text) => text.is_empty(),
792 _ => false,
793 };
794
795 if empty {
796 return Err(Error::invalid(message).hint(hint));
797 }
798
799 Ok(())
800}
801
802fn refuse_empty_prompt(prompt: &str, operation: &str) -> Result<(), Error> {
804 if prompt.trim().is_empty() {
805 return Err(Error::invalid(format!("{operation} needs a prompt."))
806 .hint("Say what the operation is to produce, in a sentence the model can act on."));
807 }
808
809 Ok(())
810}
811
812fn refuse_unless_media(document: &Value) -> Result<(), Error> {
814 if !has_file_hash(document) {
815 return Err(
816 Error::invalid("transcribe needs a document handle to work on.").hint(
817 "Pass the handle of the uploaded file, the one carrying file_hash and mime_type.",
818 ),
819 );
820 }
821
822 let media = document
823 .get("mime_type")
824 .and_then(Value::as_str)
825 .map(str::to_lowercase)
826 .is_some_and(|mime| mime.starts_with("audio/") || mime.starts_with("video/"));
827
828 if !media {
829 return Err(Error::invalid("transcribe works on audio and video.")
830 .hint("Pass a handle whose mime_type begins audio/ or video/."));
831 }
832
833 Ok(())
834}
835
836fn transcribe_schema(wanted: &TranscribeOptions) -> Value {
838 let identify = wanted.participants.wanted();
839
840 let mut properties = Map::new();
841 let mut required = vec![Value::from("language")];
842
843 properties.insert(
844 "language".to_string(),
845 json!({
846 "description": "The detected language of the audio (ISO 639-1 code, e.g., \"en\", \"es\")",
847 "type": "string"
848 }),
849 );
850
851 if wanted.include_transcript {
852 let description = match (identify, wanted.include_timestamps) {
853 (true, true) => {
854 "The full transcript with participant labels and timestamps. \
855 Format: [MM:SS] Participant Name: text"
856 }
857 (true, false) => {
858 "The full transcript with participant labels. Format: Participant Name: text"
859 }
860 (false, true) => "The full transcript with timestamps. Format: [MM:SS] text",
861 (false, false) => "The full transcript of the audio",
862 };
863
864 properties.insert(
865 "transcript".to_string(),
866 json!({ "description": description, "type": "string" }),
867 );
868 required.push(Value::from("transcript"));
869 }
870
871 if wanted.summarize {
872 let description = if identify {
873 "A concise summary of the audio content, including key points from each participant"
874 } else {
875 "A concise summary of the audio content"
876 };
877
878 properties.insert(
879 "summary".to_string(),
880 json!({ "description": description, "type": "string" }),
881 );
882 required.push(Value::from("summary"));
883 }
884
885 if identify {
886 properties.insert(
887 "participants".to_string(),
888 json!({
889 "description": "List of identified participants in the audio",
890 "items": { "type": "string" },
891 "type": "array"
892 }),
893 );
894 required.push(Value::from("participants"));
895 }
896
897 json!({ "properties": properties, "required": required, "type": "object" })
898}
899
900fn transcribe_prompt(wanted: &TranscribeOptions) -> String {
902 let identify = wanted.participants.wanted();
903 let names = wanted.participants.names();
904
905 let mut prompt = String::from("Analyze this audio/video file and provide:\n");
906
907 if wanted.include_transcript {
908 if identify {
909 match &names {
910 Some(names) => {
911 prompt.push_str("- A complete transcript identifying these participants: ");
912 prompt.push_str(names);
913 prompt.push_str(". ");
914 }
915 None => prompt.push_str(
916 "- A complete transcript with participant identification \
917 (label participants as Participant 1, Participant 2, etc.). ",
918 ),
919 }
920
921 if wanted.include_timestamps {
922 prompt.push_str(
923 "Include timestamps in [MM:SS] format before each participant segment.\n",
924 );
925 } else {
926 prompt.push_str("Format each line as \"Participant Name: text\".\n");
927 }
928 } else if wanted.include_timestamps {
929 prompt.push_str(
930 "- A complete transcript with timestamps in [MM:SS] format before each segment\n",
931 );
932 } else {
933 prompt.push_str("- A complete transcript of all spoken content\n");
934 }
935 }
936
937 if wanted.summarize {
938 if identify {
939 prompt.push_str("- A concise summary highlighting key points from each participant\n");
940 } else {
941 prompt.push_str("- A concise summary of the main points and key information\n");
942 }
943 }
944
945 if identify {
946 match &names {
947 Some(names) => {
948 prompt.push_str("- Identify and distinguish between these participants: ");
949 prompt.push_str(names);
950 prompt.push('\n');
951 }
952 None => prompt.push_str("- Identify and list all distinct participants in the audio\n"),
953 }
954 }
955
956 prompt.push_str("- The detected language code (ISO 639-1 format)\n");
957
958 prompt
959}
960
961#[cfg(test)]
962mod tests {
963 use serde_json::json;
964
965 use super::*;
966 use crate::testing;
967
968 fn answered() -> Value {
970 json!({ "data": { "ok": true }, "metadata": { "input_tokens": 1, "output_tokens": 2 } })
971 }
972
973 #[test]
974 fn an_extraction_asks_the_primitive_and_answers_with_the_type_it_was_asked_for() {
975 #[derive(Debug, Deserialize, PartialEq)]
976 struct Invoice {
977 number: String,
978 total: f64,
979 }
980
981 let session = testing::install(|name, params| {
982 assert_eq!(name, ORCHESTRATOR);
983 assert_eq!(params["operation"], json!("extract"));
984 assert_eq!(params["prompt"], json!("Read it."));
985 assert_eq!(params["input"], json!("INV-8, 240.00"));
986 assert_eq!(params["schema"]["type"], json!("object"));
987
988 Ok(json!({
989 "data": { "number": "INV-8", "total": 240.0 },
990 "metadata": { "input_tokens": 11, "output_tokens": 3 }
991 }))
992 });
993
994 let read: Execution<Invoice> = extract(
995 json!("INV-8, 240.00"),
996 "Read it.",
997 json!({ "type": "object" }),
998 Options::default(),
999 )
1000 .unwrap();
1001
1002 assert_eq!(
1003 read.data,
1004 Invoice {
1005 number: "INV-8".to_string(),
1006 total: 240.0
1007 }
1008 );
1009 assert_eq!(read.metadata.input_tokens, 11);
1010 assert_eq!(read.metadata.output_tokens, 3);
1011 assert_eq!(session.calls().len(), 1);
1012 }
1013
1014 #[test]
1015 fn a_default_call_reasons_does_not_regenerate_and_leaves_the_rest_to_the_platform() {
1016 let session = testing::install(|_name, _params| Ok(answered()));
1017
1018 let _: Execution<Value> = extract(
1019 json!("text"),
1020 "Read it.",
1021 json!({ "type": "object" }),
1022 Options::default(),
1023 )
1024 .unwrap();
1025
1026 let sent = session.calls()[0].params.clone();
1027
1028 assert_eq!(sent["options"], json!({ "reasoning": true }));
1029 assert_eq!(sent["regenerate"], json!(false));
1030 assert!(sent.get("model").is_none());
1031 assert!(sent.get("systemPrompt").is_none());
1032 assert!(sent.get("timeout").is_none());
1033 }
1034
1035 #[test]
1036 fn every_option_that_was_set_travels_with_the_operation() {
1037 let session = testing::install(|_name, _params| Ok(answered()));
1038
1039 let _: Execution<Value> = extract(
1040 json!("text"),
1041 "Read it.",
1042 json!({ "type": "object" }),
1043 Options {
1044 model: Some(Model::Xl),
1045 system_prompt: Some("You are an auditor.".to_string()),
1046 temperature: Some(0.25),
1047 reasoning: false,
1048 reasoning_budget: Some(2_048),
1049 regenerate: true,
1050 timeout: Some(Duration::from_secs(90)),
1051 },
1052 )
1053 .unwrap();
1054
1055 let sent = session.calls()[0].params.clone();
1056
1057 assert_eq!(sent["model"], json!("xl"));
1058 assert_eq!(sent["systemPrompt"], json!("You are an auditor."));
1059 assert_eq!(sent["regenerate"], json!(true));
1060 assert_eq!(sent["timeout"], json!(90_000));
1061 assert_eq!(
1062 sent["options"],
1063 json!({ "reasoning": false, "reasoning_budget": 2_048, "temperature": 0.25 })
1064 );
1065 }
1066
1067 #[test]
1068 fn a_summary_answers_with_the_prose_and_carries_no_schema() {
1069 let session = testing::install(|_name, params| {
1070 assert_eq!(params["operation"], json!("summarize"));
1071 assert!(params.get("schema").is_none());
1072
1073 Ok(json!({ "data": "A refund was agreed.", "metadata": { "output_tokens": 5 } }))
1074 });
1075
1076 let written = summarize(json!("A long thread."), "One sentence.", Options::default())
1077 .expect("a summary answers with prose");
1078
1079 assert_eq!(written.data, "A refund was agreed.");
1080 assert_eq!(written.metadata.output_tokens, 5);
1081 assert_eq!(session.calls().len(), 1);
1082 }
1083
1084 #[test]
1085 fn a_pending_document_is_uploaded_before_the_operation_reads_it() {
1086 let session = testing::install(|name, _params| {
1087 if name == UPLOAD_EPHEMERAL {
1088 return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
1089 }
1090
1091 Ok(answered())
1092 });
1093
1094 let _: Execution<Value> = extract(
1095 json!({ "file_hash": "abc", "pending": true }),
1096 "Read it.",
1097 json!({ "type": "object" }),
1098 Options::default(),
1099 )
1100 .unwrap();
1101
1102 let calls = session.calls();
1103
1104 assert_eq!(calls.len(), 2);
1105 assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
1106 assert_eq!(calls[1].name, ORCHESTRATOR);
1107 assert_eq!(
1108 calls[1].params["input"],
1109 json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }),
1110 "the operation reads the handle the upload answered with"
1111 );
1112 }
1113
1114 #[test]
1115 fn a_document_that_is_already_stored_is_read_where_it_is() {
1116 let session = testing::install(|_name, _params| Ok(answered()));
1117
1118 let handle = json!({ "file_hash": "abc", "mime_type": "application/pdf" });
1119
1120 let _: Execution<Value> = extract(
1121 handle.clone(),
1122 "Read it.",
1123 json!({ "type": "object" }),
1124 Options::default(),
1125 )
1126 .unwrap();
1127
1128 let calls = session.calls();
1129
1130 assert_eq!(calls.len(), 1, "nothing was uploaded");
1131 assert_eq!(calls[0].params["input"], handle);
1132 }
1133
1134 #[test]
1135 fn a_list_of_documents_is_uploaded_item_by_item() {
1136 let session = testing::install(|name, params| {
1137 if name == UPLOAD_EPHEMERAL {
1138 return Ok(json!({ "stored": params["file_hash"] }));
1139 }
1140
1141 Ok(answered())
1142 });
1143
1144 let _: Execution<Value> = extract(
1145 json!([
1146 { "file_hash": "one", "pending": true },
1147 { "file_hash": "two", "mime_type": "image/png" },
1148 { "file_hash": "three", "pending": true }
1149 ]),
1150 "Read them.",
1151 json!({ "type": "object" }),
1152 Options::default(),
1153 )
1154 .unwrap();
1155
1156 let calls = session.calls();
1157
1158 assert_eq!(calls.len(), 3, "two uploads and the operation");
1159 assert_eq!(
1160 calls[2].params["input"],
1161 json!([
1162 { "stored": "one" },
1163 { "file_hash": "two", "mime_type": "image/png" },
1164 { "stored": "three" }
1165 ])
1166 );
1167 }
1168
1169 #[test]
1170 fn a_handle_is_pending_only_while_it_says_so_and_carries_a_hash_to_upload_by() {
1171 assert!(is_pending(&json!({ "file_hash": "abc", "pending": true })));
1172 assert!(!is_pending(&json!({ "file_hash": "abc" })));
1173 assert!(!is_pending(&json!({ "pending": true })));
1174 assert!(!is_pending(&json!({ "file_hash": "", "pending": true })));
1175 assert!(!is_pending(
1176 &json!({ "file_hash": "abc", "pending": "yes" })
1177 ));
1178 assert!(!is_pending(&json!("some words")));
1179 assert!(!is_pending(&json!([
1180 { "file_hash": "abc", "pending": true }
1181 ])));
1182 }
1183
1184 #[test]
1185 fn an_answer_that_reports_nothing_about_its_cost_is_still_an_answer() {
1186 let _session = testing::install(|_name, _params| Ok(json!({ "data": "done" })));
1187
1188 let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
1189
1190 assert_eq!(written.data, "done");
1191 assert_eq!(written.metadata, Metadata::default());
1192 }
1193
1194 #[test]
1195 fn reasoning_reaches_the_caller_when_the_run_reported_it() {
1196 let _session = testing::install(|_name, _params| {
1197 Ok(json!({
1198 "data": "done",
1199 "metadata": {
1200 "input_tokens": 9,
1201 "output_tokens": 4,
1202 "reasoning": "Read the total from the last line.",
1203 "reasoning_tokens": 120
1204 }
1205 }))
1206 });
1207
1208 let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
1209
1210 assert_eq!(written.metadata.reasoning_tokens, Some(120));
1211 assert_eq!(
1212 written.metadata.reasoning.as_deref(),
1213 Some("Read the total from the last line.")
1214 );
1215 }
1216
1217 #[test]
1218 fn an_operation_with_nothing_to_do_is_refused_before_anything_is_sent() {
1219 let session = testing::install(|_name, _params| Ok(answered()));
1220
1221 let missing_input = extract::<Value>(
1222 json!(null),
1223 "Read it.",
1224 json!({ "type": "object" }),
1225 Options::default(),
1226 )
1227 .unwrap_err();
1228
1229 let missing_prompt = extract::<Value>(
1230 json!("text"),
1231 " ",
1232 json!({ "type": "object" }),
1233 Options::default(),
1234 )
1235 .unwrap_err();
1236
1237 let missing_schema =
1238 extract::<Value>(json!("text"), "Read it.", json!([]), Options::default()).unwrap_err();
1239
1240 let missing_summary_input =
1241 summarize(json!(""), "One sentence.", Options::default()).unwrap_err();
1242
1243 for refusal in [
1244 &missing_input,
1245 &missing_prompt,
1246 &missing_schema,
1247 &missing_summary_input,
1248 ] {
1249 assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
1250 }
1251
1252 assert!(session.calls().is_empty());
1253 }
1254
1255 #[test]
1256 fn a_transcription_writes_its_own_schema_and_prompt() {
1257 let session = testing::install(|_name, _params| {
1258 Ok(json!({
1259 "data": { "language": "en", "transcript": "Hello." },
1260 "metadata": { "input_tokens": 400, "output_tokens": 12 }
1261 }))
1262 });
1263
1264 let heard = transcribe(
1265 json!({ "file_hash": "abc", "mime_type": "AUDIO/MPEG" }),
1266 TranscribeOptions {
1267 include_transcript: true,
1268 ..Default::default()
1269 },
1270 Options::default(),
1271 )
1272 .expect("an uppercase mime type is the same mime type");
1273
1274 assert_eq!(heard.data.language, "en");
1275 assert_eq!(heard.data.transcript.as_deref(), Some("Hello."));
1276 assert_eq!(heard.data.summary, None);
1277 assert!(heard.data.participants.is_empty());
1278
1279 let sent = session.calls()[0].params.clone();
1280
1281 assert_eq!(sent["operation"], json!("extract"));
1282 assert_eq!(
1283 sent["schema"]["required"],
1284 json!(["language", "transcript"])
1285 );
1286 assert_eq!(sent["schema"]["properties"]["transcript"]["type"], "string");
1287 assert_eq!(
1288 sent["prompt"],
1289 json!(
1290 "Analyze this audio/video file and provide:\n\
1291 - A complete transcript of all spoken content\n\
1292 - The detected language code (ISO 639-1 format)\n"
1293 )
1294 );
1295 }
1296
1297 #[test]
1298 fn named_participants_reach_both_the_prompt_and_the_schema() {
1299 let session = testing::install(|_name, _params| {
1300 Ok(json!({ "data": { "language": "en", "participants": ["Customer", "Agent"] } }))
1301 });
1302
1303 let heard = transcribe(
1304 json!({ "file_hash": "abc", "mime_type": "video/mp4" }),
1305 TranscribeOptions {
1306 include_transcript: true,
1307 include_timestamps: true,
1308 summarize: true,
1309 participants: Participants::Named(vec![
1310 "Customer".to_string(),
1311 "Agent".to_string(),
1312 ]),
1313 },
1314 Options::default(),
1315 )
1316 .unwrap();
1317
1318 assert_eq!(heard.data.participants, ["Customer", "Agent"]);
1319
1320 let sent = session.calls()[0].params.clone();
1321 let prompt = sent["prompt"].as_str().unwrap_or_default().to_string();
1322
1323 assert_eq!(
1324 sent["schema"]["required"],
1325 json!(["language", "transcript", "summary", "participants"])
1326 );
1327 assert_eq!(
1328 sent["schema"]["properties"]["participants"]["items"]["type"],
1329 json!("string")
1330 );
1331 assert!(prompt.contains("identifying these participants: Customer, Agent. "));
1332 assert!(prompt.contains("Include timestamps in [MM:SS] format"));
1333 assert!(
1334 prompt.contains("- A concise summary highlighting key points from each participant\n")
1335 );
1336 assert!(prompt
1337 .contains("- Identify and distinguish between these participants: Customer, Agent\n"));
1338 }
1339
1340 #[test]
1341 fn detected_participants_are_labelled_rather_than_named() {
1342 let session =
1343 testing::install(|_name, _params| Ok(json!({ "data": { "language": "en" } })));
1344
1345 let _ = transcribe(
1346 json!({ "file_hash": "abc", "mime_type": "audio/wav" }),
1347 TranscribeOptions {
1348 include_transcript: true,
1349 participants: Participants::Detect,
1350 ..Default::default()
1351 },
1352 Options::default(),
1353 )
1354 .unwrap();
1355
1356 let prompt = session.calls()[0].params["prompt"]
1357 .as_str()
1358 .unwrap_or_default()
1359 .to_string();
1360
1361 assert!(prompt.contains("label participants as Participant 1, Participant 2, etc."));
1362 assert!(prompt.contains("Format each line as \"Participant Name: text\".\n"));
1363 assert!(prompt.contains("- Identify and list all distinct participants in the audio\n"));
1364 }
1365
1366 #[test]
1367 fn naming_nobody_asks_for_the_same_thing_as_detecting() {
1368 let wanted = |participants| TranscribeOptions {
1369 include_transcript: true,
1370 participants,
1371 ..Default::default()
1372 };
1373
1374 assert_eq!(
1375 transcribe_prompt(&wanted(Participants::Named(Vec::new()))),
1376 transcribe_prompt(&wanted(Participants::Detect))
1377 );
1378 assert_eq!(
1379 transcribe_schema(&wanted(Participants::Named(Vec::new()))),
1380 transcribe_schema(&wanted(Participants::Detect))
1381 );
1382 }
1383
1384 #[test]
1385 fn a_transcription_that_cannot_run_is_refused_before_anything_is_sent() {
1386 let session = testing::install(|_name, _params| Ok(answered()));
1387
1388 let audio = json!({ "file_hash": "abc", "mime_type": "audio/mpeg" });
1389
1390 let nothing_wanted = transcribe(
1391 audio.clone(),
1392 TranscribeOptions::default(),
1393 Options::default(),
1394 )
1395 .unwrap_err();
1396
1397 let not_media = transcribe(
1398 json!({ "file_hash": "abc", "mime_type": "application/pdf" }),
1399 TranscribeOptions {
1400 include_transcript: true,
1401 ..Default::default()
1402 },
1403 Options::default(),
1404 )
1405 .unwrap_err();
1406
1407 let not_a_handle = transcribe(
1408 json!("some words"),
1409 TranscribeOptions {
1410 summarize: true,
1411 ..Default::default()
1412 },
1413 Options::default(),
1414 )
1415 .unwrap_err();
1416
1417 for refusal in [¬hing_wanted, ¬_media, ¬_a_handle] {
1418 assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
1419 }
1420
1421 assert!(session.calls().is_empty());
1422 }
1423
1424 #[test]
1425 fn an_enrolment_answers_with_the_id_the_face_was_filed_under() {
1426 let session = testing::install(|name, params| {
1427 assert_eq!(name, FACE_ENROLL);
1428 assert_eq!(params["subject_id"], json!("EMP-42"));
1429 assert_eq!(params["image"], json!("iVBORw0KGgo"));
1430
1431 Ok(json!({ "face_id": "FACE-1" }))
1432 });
1433
1434 assert_eq!(
1435 enroll_face("EMP-42", json!("iVBORw0KGgo")).unwrap(),
1436 "FACE-1"
1437 );
1438 assert_eq!(session.calls().len(), 1);
1439 }
1440
1441 #[test]
1442 fn an_enrolment_uploads_a_pending_image_first() {
1443 let session = testing::install(|name, _params| {
1444 if name == UPLOAD_EPHEMERAL {
1445 return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
1446 }
1447
1448 Ok(json!({ "face_id": "FACE-1" }))
1449 });
1450
1451 enroll_face("EMP-42", json!({ "file_hash": "abc", "pending": true })).unwrap();
1452
1453 let calls = session.calls();
1454
1455 assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
1456 assert_eq!(
1457 calls[1].params["image"],
1458 json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" })
1459 );
1460 }
1461
1462 #[test]
1463 fn an_enrolment_without_a_subject_or_an_image_is_refused() {
1464 let session = testing::install(|_name, _params| Ok(json!({ "face_id": "FACE-1" })));
1465
1466 assert_eq!(
1467 enroll_face(" ", json!("image"))
1468 .unwrap_err()
1469 .code()
1470 .as_str(),
1471 "INVALID_TOOL_INPUT"
1472 );
1473 assert_eq!(
1474 enroll_face("EMP-42", json!(null))
1475 .unwrap_err()
1476 .code()
1477 .as_str(),
1478 "INVALID_TOOL_INPUT"
1479 );
1480 assert!(session.calls().is_empty());
1481 }
1482
1483 #[test]
1484 fn an_enrolment_that_answers_without_an_id_is_reported_rather_than_guessed_at() {
1485 let _session = testing::install(|_name, _params| Ok(json!({ "enrolled": true })));
1486
1487 let error = enroll_face("EMP-42", json!("image")).unwrap_err();
1488
1489 assert!(matches!(error, Error::Json(_)));
1490 assert_eq!(error.code().as_str(), "ACTION_FAILED");
1491 }
1492
1493 #[test]
1494 fn a_search_carries_only_the_narrowing_it_was_given() {
1495 let session = testing::install(|name, params| {
1496 assert_eq!(name, FACE_SEARCH);
1497
1498 Ok(json!({ "matches": params["options"].clone() }))
1499 });
1500
1501 let wide: Value = search_face(json!("image"), FaceSearch::default()).unwrap();
1502
1503 let narrow: Value = search_face(
1504 json!("image"),
1505 FaceSearch {
1506 max_faces: Some(3),
1507 similarity_threshold: Some(92.5),
1508 },
1509 )
1510 .unwrap();
1511
1512 assert_eq!(wide["matches"], json!({}), "the platform's own defaults");
1513 assert_eq!(
1514 narrow["matches"],
1515 json!({ "max_faces": 3, "similarity_threshold": 92.5 })
1516 );
1517 assert_eq!(session.calls().len(), 2);
1518 }
1519
1520 #[test]
1521 fn a_search_answers_with_the_type_the_call_asked_for() {
1522 #[derive(Debug, Deserialize, PartialEq)]
1523 struct Match {
1524 similarity: f64,
1525 subject_id: String,
1526 }
1527
1528 let _session = testing::install(|_name, _params| {
1529 Ok(json!([{ "similarity": 99.1, "subject_id": "EMP-42" }]))
1530 });
1531
1532 let found: Vec<Match> = search_face(json!("image"), FaceSearch::default()).unwrap();
1533
1534 assert_eq!(
1535 found,
1536 vec![Match {
1537 similarity: 99.1,
1538 subject_id: "EMP-42".to_string()
1539 }]
1540 );
1541 }
1542
1543 #[test]
1544 fn a_search_with_no_image_is_refused_before_anything_is_sent() {
1545 let session = testing::install(|_name, _params| Ok(json!([])));
1546
1547 let error = search_face::<Value>(json!(null), FaceSearch::default()).unwrap_err();
1548
1549 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
1550 assert!(session.calls().is_empty());
1551 }
1552
1553 #[test]
1554 fn a_removal_reports_the_ids_the_platform_says_it_removed() {
1555 let session = testing::install(|name, params| {
1556 assert_eq!(name, FACE_DELETE);
1557 assert_eq!(params["face_ids"], json!(["FACE-1", "FACE-2"]));
1558
1559 Ok(json!({ "deleted": ["FACE-1"] }))
1560 });
1561
1562 let removed = delete_face(&["FACE-1".to_string(), "FACE-2".to_string()]).unwrap();
1563
1564 assert_eq!(removed, ["FACE-1"]);
1565 assert_eq!(session.calls().len(), 1);
1566 }
1567
1568 #[test]
1569 fn a_removal_reads_a_bare_list_of_ids_as_well() {
1570 let _session = testing::install(|_name, _params| Ok(json!(["FACE-1", "FACE-2"])));
1571
1572 assert_eq!(
1573 delete_face(&["FACE-1".to_string()]).unwrap(),
1574 ["FACE-1", "FACE-2"]
1575 );
1576 }
1577
1578 #[test]
1579 fn a_removal_that_names_nothing_removed_answers_with_nothing() {
1580 let _session = testing::install(|_name, _params| Ok(json!({ "ok": true })));
1581
1582 assert!(delete_face(&["FACE-1".to_string()]).unwrap().is_empty());
1583 }
1584
1585 #[test]
1586 fn a_removal_with_no_ids_is_refused_before_anything_is_sent() {
1587 let session = testing::install(|_name, _params| Ok(json!([])));
1588
1589 let error = delete_face(&[]).unwrap_err();
1590
1591 assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
1592 assert!(session.calls().is_empty());
1593 }
1594
1595 #[test]
1596 fn what_the_host_said_survives_into_every_failure() {
1597 let _session = testing::install(|_name, _params| Err(Error::failed("the engine is busy")));
1598
1599 let operation = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
1600 let enrolment = enroll_face("EMP-42", json!("image")).unwrap_err();
1601 let search = search_face::<Value>(json!("image"), FaceSearch::default()).unwrap_err();
1602 let removal = delete_face(&["FACE-1".to_string()]).unwrap_err();
1603
1604 for failure in [&operation, &enrolment, &search, &removal] {
1605 assert!(failure.message().contains("the engine is busy"));
1606 assert!(!failure.fault().hint().is_empty(), "and says what to do");
1607 }
1608 }
1609
1610 #[test]
1611 fn an_answer_that_does_not_fit_the_type_is_reported_as_having_run() {
1612 let _session = testing::install(|_name, _params| Ok(json!({ "data": { "total": 240.0 } })));
1613
1614 let error = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
1615
1616 assert!(matches!(error, Error::Json(_)));
1617 assert_eq!(error.code().as_str(), "ACTION_FAILED");
1618 assert!(error
1619 .fault()
1620 .hint()
1621 .contains("rather than running it again"));
1622 }
1623
1624 #[test]
1625 fn a_timeout_travels_as_the_milliseconds_the_wire_carries() {
1626 assert_eq!(milliseconds(Duration::from_secs(30)), 30_000);
1627 assert_eq!(milliseconds(Duration::from_millis(1)), 1);
1628 assert_eq!(milliseconds(Duration::MAX), u64::MAX);
1629 }
1630
1631 #[test]
1632 fn every_model_names_itself_as_the_wire_spells_it() {
1633 assert_eq!(Model::Lite.to_string(), "lite");
1634 assert_eq!(Model::Medium.to_string(), "medium");
1635 assert_eq!(Model::Large.to_string(), "large");
1636 assert_eq!(Model::Xl.to_string(), "xl");
1637 }
1638}