Skip to main content

simpleplatform_sdk/
ai.rs

1//! Asking the AI engine for an answer.
2//!
3//! Four operations read something and answer with it — [`extract`] pulls
4//! structured data out against a schema you give, [`summarize`] writes prose,
5//! [`transcribe`] turns audio or video into words, and [`transcribe_pages`]
6//! reads the pages of a PDF that have no text of their own from their images.
7//! Three more hold the tenant's face collection: [`enroll_face`],
8//! [`search_face`] and [`delete_face`].
9//!
10//! ```
11//! # use simpleplatform_sdk::prelude::*;
12//! # use simpleplatform_sdk::ai::{Execution, Options};
13//! # use simpleplatform_sdk::testing;
14//! #[derive(Deserialize)]
15//! struct Invoice {
16//!     number: String,
17//!     total: f64,
18//! }
19//!
20//! # let _session = testing::install(|_name, _params| {
21//! #     Ok(json!({
22//! #         "data": { "number": "INV-8", "total": 240.0 },
23//! #         "metadata": { "input_tokens": 812, "output_tokens": 24 }
24//! #     }))
25//! # });
26//! let schema = json!({
27//!     "type": "object",
28//!     "properties": {
29//!         "number": { "type": "string" },
30//!         "total": { "type": "number" }
31//!     },
32//!     "required": ["number", "total"]
33//! });
34//!
35//! let read: Execution<Invoice> = simple::ai::extract(
36//!     json!({ "file_hash": "9f2c…", "mime_type": "application/pdf" }),
37//!     "Read the invoice number and the total.",
38//!     schema,
39//!     Options::default(),
40//! )?;
41//!
42//! assert_eq!(read.data.number, "INV-8");
43//! assert_eq!(read.metadata.input_tokens, 812);
44//! # Ok::<(), Error>(())
45//! ```
46//!
47//! # The shape, and why it is this one
48//!
49//! **What an operation must have is an argument; what it may have is a field.**
50//! An input, a prompt and a schema are the operation — leave one out and there
51//! is nothing to run — so they are arguments, and the type system asks for them.
52//! Everything else has a working default, so it lives in [`Options`], which
53//! derives one:
54//!
55//! ```
56//! # use simpleplatform_sdk::ai::{Model, Options};
57//! # use std::time::Duration;
58//! let options = Options {
59//!     model: Some(Model::Large),
60//!     timeout: Some(Duration::from_secs(90)),
61//!     ..Default::default()
62//! };
63//! ```
64//!
65//! Nobody passes six `None`s, and a member added to [`Options`] later does not
66//! disturb a call that was written with `..Default::default()`.
67//!
68//! **The answer type is yours.** [`extract`] is generic over what it decodes
69//! into, exactly as [`crate::graphql::query`] is, so an extraction lands in your
70//! own struct rather than in a `Value` you then have to pick apart. Where the
71//! answer's shape is settled it is named for you instead: [`summarize`] answers
72//! with prose, and [`transcribe`] answers with a [`Transcript`], because this
73//! module wrote the schema that produced it.
74//!
75//! **Every answer carries what it cost.** An operation answers with an
76//! [`Execution`] — the data and the [`Metadata`] beside it — so token counts are
77//! there to record without a second call.
78//!
79//! # Asking for part of a file, or for its text
80//!
81//! A file reference may say how the file should travel and which of its pages
82//! should. [`DocumentInput`] is that reference with those two beside it, and
83//! [`Delivery`] and [`Pages`] are what they say. A plain handle asks for nothing
84//! and sends the whole file the way its type is sent by default.
85//!
86//! What was asked for is not always what happened, so every answer says how
87//! each file travelled, in [`Metadata::delivery`]: as the document, as its text
88//! or as an image, which pages were read from their images, and, when text was
89//! asked for and the document went instead, which pages could not be read.
90//!
91//! # Files that have not been uploaded yet
92//!
93//! A document handle that is still pending is uploaded to ephemeral storage
94//! before the operation runs, and the operation is given the handle that upload
95//! answered with. A handle that is already stored is passed straight through,
96//! and so is a list of handles, item by item. Nothing in a call site changes:
97//! pass the handle you were given.
98
99use 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
111/// The primitive that runs an AI operation.
112const ORCHESTRATOR: &str = "logic:dev.simple.system/ai-orchestrator";
113
114/// The host action that puts a pending file into ephemeral storage.
115const UPLOAD_EPHEMERAL: &str = "action:documents/upload-ephemeral";
116
117/// The host action that adds a face to the tenant's collection.
118const FACE_ENROLL: &str = "action:ai/face/enroll";
119
120/// The host action that searches the tenant's collection.
121const FACE_SEARCH: &str = "action:ai/face/search";
122
123/// The host action that removes faces from the tenant's collection.
124const FACE_DELETE: &str = "action:ai/face/delete";
125
126/// The size of model an operation runs on.
127///
128/// It is `#[non_exhaustive]`: a `match` on it needs a `_` arm, so a size added
129/// later does not break an action that was already written.
130#[non_exhaustive]
131#[derive(Clone, Copy, Debug, PartialEq, Eq)]
132pub enum Model {
133    /// The quickest and cheapest.
134    Lite,
135    /// The middle of the range.
136    Medium,
137    /// The one to reach for when the answer has to be right.
138    Large,
139    /// The largest available.
140    Xl,
141}
142
143impl Model {
144    /// The size exactly as it travels on the wire.
145    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/// How a document reaches the model.
162///
163/// Both answers are sayable, so a call can write the default down rather than
164/// leaving it to the absence of a value.
165///
166/// It is `#[non_exhaustive]`: a `match` on it needs a `_` arm, so a way added
167/// later does not break an action that was already written.
168#[non_exhaustive]
169#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]
170#[serde(rename_all = "lowercase")]
171pub enum Delivery {
172    /// The document itself, which is how a PDF travels unless you say
173    /// otherwise.
174    Document,
175    /// The text the platform reads out of the document.
176    Text,
177}
178
179/// The pages of a PDF to use, counted from 1 with both ends included.
180///
181/// The two ends are one value here because the engine refuses one without the
182/// other. A half-written range cannot be expressed, so it cannot be sent.
183///
184/// What this type does not decide is still the engine's: a `first` below 1, a
185/// `last` before `first`, or a range that runs past the end of the document is
186/// refused there, before the file is read or anything is spent.
187#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]
188pub struct Pages {
189    /// The first page to use, counted from 1.
190    pub first_page: u32,
191    /// The last page to use, included.
192    pub last_page: u32,
193}
194
195impl Pages {
196    /// Pages `first` to `last`, counted from 1 with both ends included.
197    pub fn new(first: u32, last: u32) -> Pages {
198        Pages {
199            first_page: first,
200            last_page: last,
201        }
202    }
203}
204
205/// A stored file handed to an AI operation, together with what should be done
206/// with it.
207///
208/// A PDF travels to the model as a PDF, because the model reads one: its
209/// tables, its layout and its figures survive the trip, and none of them
210/// survive being turned into text. Asking for text is therefore opt-in.
211///
212/// ```
213/// # use simpleplatform_sdk::prelude::*;
214/// # use simpleplatform_sdk::ai::{self, Delivery, DocumentInput, Execution, Pages};
215/// # use simpleplatform_sdk::testing;
216/// # let _session = testing::install(|_name, _params| {
217/// #     Ok(json!({ "data": "The first three pages sign the contract off." }))
218/// # });
219/// let contract = DocumentInput {
220///     file: DocumentHandle {
221///         file_hash: "9f2c…".into(),
222///         filename: "contract.pdf".into(),
223///         mime_type: "application/pdf".into(),
224///         size: 1_048_576,
225///         storage_path: "acme/documents/9f/2c/9f2c….pdf".into(),
226///     },
227///     pages: Some(Pages::new(1, 3)),
228///     deliver_as: Some(Delivery::Text),
229/// };
230///
231/// let read: Execution<String> =
232///     ai::summarize(json!(contract), "Say what it commits us to.", Options::default())?;
233/// # Ok::<(), Error>(())
234/// ```
235///
236/// The pages and the delivery are two questions, asked in that order. The pages
237/// say WHICH DOCUMENT the call is about: they are taken out of the PDF first,
238/// and everything after that is about them and nothing else. The delivery then
239/// says how that document should reach the model.
240///
241/// Refused by the engine, before the file is read or anything is spent:
242///
243/// * [`pages`](DocumentInput::pages) on anything that is not a PDF;
244/// * a range that runs past the end of the document, or one whose last page
245///   precedes its first;
246/// * [`Delivery::Text`] on an image, which is not read as text;
247/// * [`Delivery::Document`] on a Word, Excel, PowerPoint, CSV, RTF or text
248///   file, which only ever travels as text.
249///
250/// A page with no usable text of its own — a scan, or text that reads as noise
251/// — is read from its image instead, and that text stands in its place, marked
252/// `[Transcribed from the page image.]` under its page label. Only if that
253/// reading fails are the pages asked for sent as a PDF, so an answer is never
254/// built on text with a hole in it. The answer's [`Metadata::delivery`] says
255/// which happened.
256///
257/// Pages asked for as text arrive numbered from 1, because by then they are a
258/// document of their own. A line above them says which pages of which document
259/// they were, rather than the numbers being rewritten inside the text: a page
260/// number printed in a header or a cross-reference cannot be told apart from a
261/// page label, so editing them would corrupt the document's own words.
262#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
263pub struct DocumentInput {
264    /// The stored file, as the upload or the record that holds it answered
265    /// with.
266    #[serde(flatten)]
267    pub file: DocumentHandle,
268
269    /// Which pages of the PDF to send. Unset sends the whole document.
270    #[serde(default, flatten)]
271    pub pages: Option<Pages>,
272
273    /// How the document reaches the model. Unset sends it the way its type is
274    /// sent by default.
275    ///
276    #[serde(default, skip_serializing_if = "Option::is_none")]
277    pub deliver_as: Option<Delivery>,
278}
279
280/// The reader used for scanned pages; omission or `Standard` preserves the default.
281/// `Precise` costs more and suits exact characters (codes, part numbers); text pages are unaffected.
282#[non_exhaustive]
283#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]
284#[serde(rename_all = "lowercase")]
285pub enum Transcription {
286    /// Use the standard reader.
287    Standard,
288    /// Use the higher-cost precise reader.
289    Precise,
290}
291
292/// What any operation may be told, beyond the inputs that define it.
293///
294/// Every member has a default, so a call that wants one thing changed says that
295/// thing and nothing else:
296///
297/// ```
298/// # use simpleplatform_sdk::ai::{Model, Options};
299/// let options = Options {
300///     model: Some(Model::Large),
301///     reasoning: false,
302///     ..Default::default()
303/// };
304/// ```
305#[derive(Clone, Debug)]
306pub struct Options {
307    /// Selects the reader for scanned pages; omission or `Standard` preserves the default.
308    /// `Precise` costs more and suits exact characters (codes, part numbers); text pages are unaffected.
309    pub transcription: Option<Transcription>,
310
311    /// Which size of model to run on. Unset leaves the choice to the platform.
312    pub model: Option<Model>,
313
314    /// The role, or the standing instruction, the model holds for the whole
315    /// task. Unset sends none.
316    pub system_prompt: Option<String>,
317
318    /// How far the model may range, from `0.0` for the most settled answer to
319    /// `1.0` for the most inventive. Unset leaves the model's own default.
320    pub temperature: Option<f64>,
321
322    /// Whether the model works the answer out step by step, and reports how.
323    /// On unless you turn it off.
324    pub reasoning: bool,
325
326    /// The most tokens the reasoning may spend. Unset leaves the platform's
327    /// default, and it is read only while `reasoning` is on.
328    pub reasoning_budget: Option<u32>,
329
330    /// Whether to do the work again rather than answer from a cached result for
331    /// the same input, prompt, schema, model and options.
332    pub regenerate: bool,
333
334    /// How long to wait for the answer. Unset leaves the platform's default.
335    pub timeout: Option<Duration>,
336}
337
338impl Default for Options {
339    /// Reasoning on, and every other choice left to the platform.
340    fn default() -> Options {
341        Options {
342            transcription: None,
343            model: None,
344            system_prompt: None,
345            temperature: None,
346            reasoning: true,
347            reasoning_budget: None,
348            regenerate: false,
349            timeout: None,
350        }
351    }
352}
353
354/// Whether to tell the speakers apart, and what to call them.
355#[derive(Clone, Debug, Default, PartialEq, Eq)]
356pub enum Participants {
357    /// Do not tell the speakers apart.
358    #[default]
359    Ignore,
360
361    /// Tell the speakers apart, and label them `Participant 1`,
362    /// `Participant 2`, and so on.
363    Detect,
364
365    /// Tell the speakers apart under the names given. Naming nobody asks for
366    /// the same thing as [`Participants::Detect`].
367    Named(Vec<String>),
368}
369
370impl Participants {
371    /// Whether the speakers are to be told apart at all.
372    fn wanted(&self) -> bool {
373        !matches!(self, Participants::Ignore)
374    }
375
376    /// The names to identify, as one list, or nothing when none were given.
377    fn names(&self) -> Option<String> {
378        match self {
379            Participants::Named(names) if !names.is_empty() => Some(names.join(", ")),
380            _ => None,
381        }
382    }
383}
384
385/// What a transcription is to produce.
386///
387/// At least one of `include_transcript` and `summarize` has to be set, since
388/// between them they are the whole of what a transcription answers with.
389#[derive(Clone, Debug, Default)]
390pub struct TranscribeOptions {
391    /// Ask for the words that were said.
392    pub include_transcript: bool,
393
394    /// Ask for `[MM:SS]` stamps through the transcript. Read only while
395    /// `include_transcript` is set.
396    pub include_timestamps: bool,
397
398    /// Ask for a summary of what was said.
399    pub summarize: bool,
400
401    /// Whether to tell the speakers apart, and what to call them.
402    pub participants: Participants,
403}
404
405/// What a transcription answered with.
406///
407/// A member that was not asked for is empty, and every member survives an
408/// answer that leaves it out.
409#[derive(Clone, Debug, Default, Deserialize)]
410#[serde(default)]
411pub struct Transcript {
412    /// The language that was heard, as an ISO 639-1 code such as `en` or `es`.
413    pub language: String,
414
415    /// The words that were said, when they were asked for.
416    pub transcript: Option<String>,
417
418    /// The summary, when it was asked for.
419    pub summary: Option<String>,
420
421    /// The speakers that were told apart, when they were asked for.
422    pub participants: Vec<String>,
423}
424
425/// What [`transcribe_pages`] may be told, beyond the PDF and the pages.
426///
427/// There is no prompt, model or reasoning switch, which is why this is not
428/// [`Options`]: the instructions are the platform's, and every page is read at
429/// the platform's own accuracy-first effort.
430#[derive(Clone, Debug, Default)]
431pub struct TranscribePagesOptions {
432    /// Selects the reader for scanned pages; omission or `Standard` preserves the default.
433    /// `Precise` costs more and suits exact characters (codes, part numbers); text pages are unaffected.
434    pub transcription: Option<Transcription>,
435
436    /// Whether to run the operation again rather than answer from its kept
437    /// result. A page already read is still served from its kept read, which
438    /// is tied to this version of the file and to the platform's instructions.
439    pub regenerate: bool,
440
441    /// How long to wait for the answer. Unset leaves the platform's default.
442    pub timeout: Option<Duration>,
443}
444
445/// One page's transcription, or why it has none.
446///
447/// Pages are numbered in the original document, whatever range was asked for.
448/// A page either has its text or has a reason, never both, so a caller cannot
449/// mistake a partial read for the page.
450#[derive(Clone, Debug, PartialEq, Eq)]
451pub enum PageTranscription {
452    /// The page was read from its image.
453    Read {
454        /// The page's number in the original document.
455        page: u32,
456
457        /// The page's text: verbatim markdown, in reading order, tables as
458        /// markdown tables, `[illegible]` where a word could not be read. An
459        /// empty string is a read that found the page blank.
460        text: String,
461    },
462
463    /// The page could not be read.
464    Unread {
465        /// The page's number in the original document.
466        page: u32,
467
468        /// Why, in the platform's words. No partial text is given.
469        error: String,
470    },
471}
472
473impl PageTranscription {
474    /// The page's number in the original document, read or not.
475    pub fn page(&self) -> u32 {
476        match self {
477            PageTranscription::Read { page, .. } | PageTranscription::Unread { page, .. } => *page,
478        }
479    }
480
481    /// The page's text, when it was read.
482    pub fn text(&self) -> Option<&str> {
483        match self {
484            PageTranscription::Read { text, .. } => Some(text),
485            PageTranscription::Unread { .. } => None,
486        }
487    }
488}
489
490/// What an operation answered, and what it cost.
491#[derive(Clone, Debug)]
492pub struct Execution<T> {
493    /// The answer itself, decoded into the type the call asked for.
494    pub data: T,
495
496    /// What the run spent, and how it reasoned.
497    pub metadata: Metadata,
498}
499
500/// What a run spent, how it reasoned, and how its files reached the model.
501#[derive(Clone, Debug, Default, PartialEq, Eq)]
502pub struct Metadata {
503    /// Tokens in what was sent.
504    pub input_tokens: u64,
505
506    /// Tokens in what came back.
507    pub output_tokens: u64,
508
509    /// Tokens spent reasoning, when the run reported them.
510    pub reasoning_tokens: Option<u64>,
511
512    /// The reasoning itself, when the run reported it.
513    pub reasoning: Option<String>,
514
515    /// How each file the run carried reached the model, in the order the files
516    /// were given. Empty when the run carried no file, and on an answer kept
517    /// from before the platform reported it.
518    pub delivery: Vec<FileDelivery>,
519}
520
521/// How one file an operation carried reached the model.
522///
523/// A file asked for as text is not always sent as text. A page with no text of
524/// its own is read from its image, and when that reading fails the document is
525/// sent instead, so the answer is never built on text with a hole in it. This
526/// is how a caller finds out which happened, without reading a platform log.
527///
528/// Page numbers are the original document's, whatever range was cut from it,
529/// so a page named here is the page a person would turn to.
530///
531/// ```
532/// # use simpleplatform_sdk::prelude::*;
533/// # use simpleplatform_sdk::ai::{DeliveredAs, Options, Pages};
534/// # use simpleplatform_sdk::testing;
535/// # let _session = testing::install(|_name, _params| {
536/// #     Ok(json!({
537/// #         "data": "It commits us to a fixed price.",
538/// #         "metadata": { "delivery": [{
539/// #             "filename": "contract.pdf",
540/// #             "delivered_as": "document",
541/// #             "first_page": 40,
542/// #             "last_page": 52,
543/// #             "transcribed_pages": [],
544/// #             "fallback": {
545/// #                 "reason": "transcription_failed",
546/// #                 "pages": [44],
547/// #                 "message": "page 44: the page image could not be read"
548/// #             }
549/// #         }] }
550/// #     }))
551/// # });
552/// let read = simple::ai::summarize(
553///     json!({
554///         "file_hash": "9f2c…",
555///         "filename": "contract.pdf",
556///         "mime_type": "application/pdf",
557///         "first_page": 40,
558///         "last_page": 52,
559///         "deliver_as": "text"
560///     }),
561///     "Say what it commits us to.",
562///     Options::default(),
563/// )?;
564///
565/// for file in &read.metadata.delivery {
566///     if let Some(fallback) = &file.fallback {
567///         println!("{} was read as a PDF: {}", file.filename, fallback.message);
568///     }
569/// }
570///
571/// let contract = &read.metadata.delivery[0];
572///
573/// assert_eq!(contract.delivered_as, DeliveredAs::Document);
574/// assert_eq!(contract.pages, Some(Pages::new(40, 52)));
575/// # Ok::<(), Error>(())
576/// ```
577#[derive(Clone, Debug, PartialEq, Eq)]
578pub struct FileDelivery {
579    /// The file's name.
580    pub filename: String,
581
582    /// How the file travelled.
583    pub delivered_as: DeliveredAs,
584
585    /// The range the file was cut to, when one was asked for. Unset when the
586    /// whole file travelled.
587    pub pages: Option<Pages>,
588
589    /// The pages whose text was read from their images rather than from their
590    /// text layer. Empty when none were.
591    pub transcribed_pages: Vec<u32>,
592
593    /// Set only when text was asked for and the document travelled instead:
594    /// which pages could not be read, and why.
595    pub fallback: Option<DeliveryFallback>,
596}
597
598/// How a file reached the model.
599///
600/// This is what happened, where [`Delivery`] is what was asked for, and it has
601/// a way that cannot be asked for: an image only ever travels as one.
602///
603/// It is `#[non_exhaustive]`: a `match` on it needs a `_` arm, so a way added
604/// later does not break an action that was already written.
605#[non_exhaustive]
606#[derive(Clone, Copy, Debug, PartialEq, Eq)]
607pub enum DeliveredAs {
608    /// The document itself, which the model reads with its layout, tables and
609    /// figures.
610    Document,
611    /// The text read out of the document, with any page that had none read from
612    /// its image.
613    Text,
614    /// An image.
615    Image,
616}
617
618/// Why a file asked for as text travelled as the document instead.
619#[derive(Clone, Debug, Default, PartialEq, Eq)]
620pub struct DeliveryFallback {
621    /// Why, as the platform names it: `transcription_failed` when pages with no
622    /// text of their own could not be read from their images. It is kept as
623    /// the platform's word rather than narrowed to a list, so a reason added
624    /// later still reaches you instead of hiding that a fallback happened.
625    pub reason: String,
626
627    /// The pages that could not be read, numbered in the original document.
628    pub pages: Vec<u32>,
629
630    /// What went wrong, page by page, in the platform's words.
631    pub message: String,
632}
633
634/// How far a face search reaches.
635#[derive(Clone, Debug, Default)]
636pub struct FaceSearch {
637    /// The most matches to answer with. Unset leaves the platform's default.
638    pub max_faces: Option<u32>,
639
640    /// The similarity a match has to reach, as a percentage from `0.0` to
641    /// `100.0`. Unset leaves the platform's default.
642    pub similarity_threshold: Option<f64>,
643}
644
645/// Read structured data out of an input, against a schema you give.
646///
647/// The schema is the contract the answer is held to, and the type parameter is
648/// what that answer is decoded into — so give the model the schema of the struct
649/// you want back.
650///
651/// ```
652/// # use simpleplatform_sdk::prelude::*;
653/// # use simpleplatform_sdk::ai::{Execution, Options};
654/// # use simpleplatform_sdk::testing;
655/// #[derive(Deserialize)]
656/// struct Sentiment {
657///     score: f64,
658/// }
659///
660/// # let _session = testing::install(|_name, _params| {
661/// #     Ok(json!({ "data": { "score": 0.8 }, "metadata": { "output_tokens": 6 } }))
662/// # });
663/// let schema = json!({
664///     "type": "object",
665///     "properties": { "score": { "type": "number" } },
666///     "required": ["score"]
667/// });
668///
669/// let read: Execution<Sentiment> = simple::ai::extract(
670///     json!("The delivery arrived early and intact."),
671///     "Score the sentiment from -1.0 to 1.0.",
672///     schema,
673///     Options::default(),
674/// )?;
675///
676/// assert_eq!(read.data.score, 0.8);
677/// # Ok::<(), Error>(())
678/// ```
679pub fn extract<T: DeserializeOwned>(
680    input: Value,
681    prompt: &str,
682    schema: Value,
683    options: Options,
684) -> Result<Execution<T>, Error> {
685    refuse_empty(
686        &input,
687        "extract needs something to read.",
688        "Pass the text, the document handle, or the object the extraction is to read.",
689    )?;
690    refuse_empty_prompt(prompt, "extract")?;
691
692    if !schema.is_object() {
693        return Err(
694            Error::invalid("extract needs a JSON Schema object describing the answer.").hint(
695                "Pass a schema object naming the type and the properties the answer is to have.",
696            ),
697        );
698    }
699
700    run("extract", input, Some(prompt), Some(schema), &options)
701}
702
703/// Write prose about an input.
704///
705/// ```
706/// # use simpleplatform_sdk::prelude::*;
707/// # use simpleplatform_sdk::ai::Options;
708/// # use simpleplatform_sdk::testing;
709/// # let _session = testing::install(|_name, _params| {
710/// #     Ok(json!({ "data": "A refund was agreed.", "metadata": { "output_tokens": 5 } }))
711/// # });
712/// let written = simple::ai::summarize(
713///     json!({ "file_hash": "3a91…", "mime_type": "application/pdf" }),
714///     "Summarise what was agreed, in one sentence.",
715///     Options::default(),
716/// )?;
717///
718/// assert_eq!(written.data, "A refund was agreed.");
719/// # Ok::<(), Error>(())
720/// ```
721pub fn summarize(input: Value, prompt: &str, options: Options) -> Result<Execution<String>, Error> {
722    refuse_empty(
723        &input,
724        "summarize needs something to read.",
725        "Pass the text, the document handle, or the object the summary is to be written from.",
726    )?;
727    refuse_empty_prompt(prompt, "summarize")?;
728
729    run("summarize", input, Some(prompt), None, &options)
730}
731
732/// Turn audio or video into words.
733///
734/// `document` is the handle of an uploaded audio or video file. The prompt and
735/// the schema are written here, from what `wanted` asks for, which is why the
736/// answer is a [`Transcript`] rather than a type you have to name.
737///
738/// ```
739/// # use simpleplatform_sdk::prelude::*;
740/// # use simpleplatform_sdk::ai::{Options, Participants, TranscribeOptions};
741/// # use simpleplatform_sdk::testing;
742/// # let _session = testing::install(|_name, _params| {
743/// #     Ok(json!({
744/// #         "data": {
745/// #             "language": "en",
746/// #             "transcript": "Customer: My order is late.\nAgent: I have refunded it.",
747/// #             "participants": ["Customer", "Agent"]
748/// #         },
749/// #         "metadata": { "input_tokens": 4_200, "output_tokens": 96 }
750/// #     }))
751/// # });
752/// let heard = simple::ai::transcribe(
753///     json!({ "file_hash": "c07b…", "mime_type": "audio/mpeg" }),
754///     TranscribeOptions {
755///         include_transcript: true,
756///         participants: Participants::Named(vec!["Customer".into(), "Agent".into()]),
757///         ..Default::default()
758///     },
759///     Options::default(),
760/// )?;
761///
762/// assert_eq!(heard.data.language, "en");
763/// assert_eq!(heard.data.participants, ["Customer", "Agent"]);
764/// # Ok::<(), Error>(())
765/// ```
766pub fn transcribe(
767    document: Value,
768    wanted: TranscribeOptions,
769    options: Options,
770) -> Result<Execution<Transcript>, Error> {
771    refuse_unless_media(&document)?;
772
773    if !wanted.include_transcript && !wanted.summarize {
774        return Err(
775            Error::invalid("transcribe needs to be told what to produce.")
776                .hint("Set include_transcript, summarize, or both."),
777        );
778    }
779
780    let prompt = transcribe_prompt(&wanted);
781
782    run(
783        "extract",
784        document,
785        Some(&prompt),
786        Some(transcribe_schema(&wanted)),
787        &options,
788    )
789}
790
791/// Read the pages of a PDF that have no usable text of their own — scans,
792/// image-only exhibits, text that reads as noise — from their images.
793///
794/// Every such page is read once, and it is the same transcription an
795/// [`extract`] or [`summarize`] that asked for [`Delivery::Text`] is given in
796/// the page's place, so the text a caller holds for an image page is exactly the
797/// text the answer was built on. Pages the platform reads as text are neither
798/// read nor returned.
799///
800/// A page is not transcribed a second time to check the first: that would be
801/// the same model reading the same image again, doubling the cost of every
802/// scanned page without being independent of the first read. An independent
803/// check reads the pages a second way, as the document itself
804/// ([`Delivery::Document`]), and compares the answers.
805///
806/// Transcriptions are kept per version of the file and page, and shared with
807/// every other operation, so a page already read for an [`extract`] or
808/// [`summarize`] that asked for text is not read again.
809///
810/// `pages` narrows the reading to a range, counted from 1 with both ends
811/// included, and the answer still numbers pages in the original document. The
812/// file is taken as a [`DocumentHandle`] rather than a [`DocumentInput`]
813/// because the pages are answered as text, so a delivery has no meaning here
814/// and cannot be sent. Anything that is not a PDF is refused before the host
815/// is asked.
816///
817/// ```
818/// # use simpleplatform_sdk::prelude::*;
819/// # use simpleplatform_sdk::ai::{PageTranscription, Pages, TranscribePagesOptions};
820/// # use simpleplatform_sdk::testing;
821/// # let _session = testing::install(|_name, _params| {
822/// #     Ok(json!({
823/// #         "data": { "pages": [
824/// #             { "page": 41, "text": "## Scope of Work\n\nThe Contractor shall furnish…" },
825/// #             { "page": 44, "error": "the page image could not be read" }
826/// #         ] },
827/// #         "metadata": { "input_tokens": 0, "output_tokens": 0 }
828/// #     }))
829/// # });
830/// # let contract = DocumentHandle {
831/// #     file_hash: "9f2c…".into(),
832/// #     filename: "contract.pdf".into(),
833/// #     mime_type: "application/pdf".into(),
834/// #     size: 1_048_576,
835/// #     storage_path: "acme/documents/9f/2c/9f2c….pdf".into(),
836/// # };
837/// let read = simple::ai::transcribe_pages(
838///     &contract,
839///     Some(Pages::new(40, 52)),
840///     TranscribePagesOptions::default(),
841/// )?;
842///
843/// for page in &read.data {
844///     match page {
845///         PageTranscription::Read { page, text } => {
846///             println!("page {page}: {text}");
847///         }
848///         PageTranscription::Unread { page, error } => {
849///             println!("page {page} could not be read: {error}");
850///         }
851///     }
852/// }
853///
854/// assert_eq!(
855///     read.data[0].text(),
856///     Some("## Scope of Work\n\nThe Contractor shall furnish…")
857/// );
858/// assert_eq!(read.data[1].page(), 44);
859/// # Ok::<(), Error>(())
860/// ```
861pub fn transcribe_pages(
862    document: &DocumentHandle,
863    pages: Option<Pages>,
864    options: TranscribePagesOptions,
865) -> Result<Execution<Vec<PageTranscription>>, Error> {
866    refuse_unless_pdf(document)?;
867
868    let input = json!(DocumentInput {
869        file: document.clone(),
870        pages,
871        deliver_as: None,
872    });
873
874    // The same universal options every other caller of the operation sends,
875    // since the whole map is part of the key a kept result is found under.
876    let options = Options {
877        transcription: options.transcription,
878        regenerate: options.regenerate,
879        timeout: options.timeout,
880        ..Options::default()
881    };
882
883    let read: Execution<Value> = run("transcribe", input, None, None, &options)?;
884
885    Ok(Execution {
886        data: page_transcriptions(&read.data),
887        metadata: read.metadata,
888    })
889}
890
891/// Add a face to the tenant's collection, under the subject it belongs to.
892///
893/// `image` is either a base64 image or a document handle. The answer is the id
894/// of the enrolled face, which is what [`delete_face`] takes.
895///
896/// ```
897/// # use simpleplatform_sdk::prelude::*;
898/// # use simpleplatform_sdk::testing;
899/// # let _session = testing::install(|_name, _params| Ok(json!({ "face_id": "FACE-1" })));
900/// let face_id = simple::ai::enroll_face("EMP-42", json!("iVBORw0KGgo…"))?;
901///
902/// assert_eq!(face_id, "FACE-1");
903/// # Ok::<(), Error>(())
904/// ```
905pub fn enroll_face(subject_id: &str, image: Value) -> Result<String, Error> {
906    if subject_id.trim().is_empty() {
907        return Err(
908            Error::invalid("enroll_face needs the subject the face belongs to.")
909                .hint("Pass the id the face is to be found under, such as an employee or user id."),
910        );
911    }
912
913    refuse_empty(
914        &image,
915        "enroll_face needs an image of the face.",
916        "Pass a base64 image, or the handle of an uploaded one.",
917    )?;
918
919    let image = upload_pending(image)?;
920
921    let enrolled = host::transport()?
922        .call(
923            FACE_ENROLL.to_string(),
924            json!({ "image": image, "subject_id": subject_id }),
925        )
926        .map_err(|cause| {
927            cause.hint(
928                "Search the subject before enrolling the same face again, and report the failure.",
929            )
930        })?;
931
932    enrolled
933        .get("face_id")
934        .and_then(Value::as_str)
935        .map(str::to_string)
936        .ok_or_else(|| {
937            Error::Json(Fault::new(
938                Code::unspecified(),
939                "The enrolment answered without the id of the face it enrolled.",
940            ))
941            .hint("Search the subject to establish what was enrolled before enrolling again.")
942        })
943}
944
945/// Find the faces in the tenant's collection that match an image.
946///
947/// `image` is either a base64 image or a document handle. The matches are
948/// decoded into the type the call asks for; name your own to read them, or ask
949/// for a [`Value`] to keep them whole.
950///
951/// ```
952/// # use simpleplatform_sdk::prelude::*;
953/// # use simpleplatform_sdk::ai::FaceSearch;
954/// # use simpleplatform_sdk::testing;
955/// # let _session = testing::install(|_name, _params| Ok(json!([{ "subject_id": "EMP-42" }])));
956/// let found: Value = simple::ai::search_face(
957///     json!("iVBORw0KGgo…"),
958///     FaceSearch {
959///         max_faces: Some(3),
960///         similarity_threshold: Some(92.5),
961///     },
962/// )?;
963///
964/// assert_eq!(found[0]["subject_id"], json!("EMP-42"));
965/// # Ok::<(), Error>(())
966/// ```
967pub fn search_face<T: DeserializeOwned>(image: Value, options: FaceSearch) -> Result<T, Error> {
968    refuse_empty(
969        &image,
970        "search_face needs an image to search with.",
971        "Pass a base64 image, or the handle of an uploaded one.",
972    )?;
973
974    let image = upload_pending(image)?;
975
976    let mut narrowing = Map::new();
977
978    if let Some(max_faces) = options.max_faces {
979        narrowing.insert("max_faces".to_string(), Value::from(max_faces));
980    }
981
982    if let Some(threshold) = options
983        .similarity_threshold
984        .filter(|value| value.is_finite())
985    {
986        narrowing.insert("similarity_threshold".to_string(), Value::from(threshold));
987    }
988
989    let found = host::transport()?
990        .call(
991            FACE_SEARCH.to_string(),
992            json!({ "image": image, "options": narrowing }),
993        )
994        .map_err(|cause| {
995            cause.hint("Nothing in the collection was changed. Report the search failure.")
996        })?;
997
998    serde_json::from_value(found).map_err(|cause| {
999        Error::Json(Fault::new(
1000            Code::unspecified(),
1001            format!("The matches could not be read into the type this action asked for: {cause}"),
1002        ))
1003        .hint("Read the matches as a Value, or name a type that matches what the search answers.")
1004    })
1005}
1006
1007/// Remove faces from the tenant's collection, by the ids they were enrolled
1008/// under.
1009///
1010/// The answer is the ids the platform reports as removed.
1011///
1012/// ```
1013/// # use simpleplatform_sdk::prelude::*;
1014/// # use simpleplatform_sdk::testing;
1015/// # let _session = testing::install(|_name, _params| Ok(json!({ "deleted": ["FACE-1"] })));
1016/// let removed = simple::ai::delete_face(&["FACE-1".to_string()])?;
1017///
1018/// assert_eq!(removed, ["FACE-1"]);
1019/// # Ok::<(), Error>(())
1020/// ```
1021pub fn delete_face(face_ids: &[String]) -> Result<Vec<String>, Error> {
1022    if face_ids.is_empty() {
1023        return Err(Error::invalid("delete_face needs at least one face id.")
1024            .hint("Pass the ids enroll_face answered with."));
1025    }
1026
1027    let removed = host::transport()?
1028        .call(FACE_DELETE.to_string(), json!({ "face_ids": face_ids }))
1029        .map_err(|cause| {
1030            cause.hint(
1031                "Treat the removal as unfinished: search the collection to establish what is \
1032                 still in it before deleting again.",
1033            )
1034        })?;
1035
1036    let listed = match &removed {
1037        Value::Array(ids) => Some(ids),
1038        other => other.get("deleted").and_then(Value::as_array),
1039    };
1040
1041    Ok(listed
1042        .map(|ids| {
1043            ids.iter()
1044                .filter_map(Value::as_str)
1045                .map(str::to_string)
1046                .collect()
1047        })
1048        .unwrap_or_default())
1049}
1050
1051/// One operation: upload what is pending, ask the primitive, read the answer.
1052fn run<T: DeserializeOwned>(
1053    operation: &str,
1054    input: Value,
1055    prompt: Option<&str>,
1056    schema: Option<Value>,
1057    options: &Options,
1058) -> Result<Execution<T>, Error> {
1059    let input = upload_pending(input)?;
1060
1061    let answered = host::transport()?
1062        .call(
1063            ORCHESTRATOR.to_string(),
1064            payload(operation, input, prompt, schema, options),
1065        )
1066        .map_err(|cause| {
1067            cause.hint(
1068                "No tenant record was changed. Review the input, the prompt and the schema, \
1069                 and report the failure.",
1070            )
1071        })?;
1072
1073    // The metadata is read on its own and never decides the outcome, so a run
1074    // that answered is reported as one whatever it said about its own cost.
1075    let metadata = metadata_of(answered.get("metadata"));
1076    let data = answered.get("data").cloned().unwrap_or(Value::Null);
1077
1078    let data = serde_json::from_value(data).map_err(|cause| {
1079        Error::Json(Fault::new(
1080            Code::unspecified(),
1081            format!("The {operation} answer could not be read into the type this action asked for: {cause}"),
1082        ))
1083        .hint(
1084            "The operation ran. Read the answer as a Value, or name a type that matches the \
1085             schema, rather than running it again.",
1086        )
1087    })?;
1088
1089    Ok(Execution { data, metadata })
1090}
1091
1092/// Everything the primitive is told about one operation.
1093///
1094/// A choice that was not made is left out, so what arrives is what the call
1095/// asked for and the platform's own defaults fill the rest.
1096fn payload(
1097    operation: &str,
1098    input: Value,
1099    prompt: Option<&str>,
1100    schema: Option<Value>,
1101    options: &Options,
1102) -> Value {
1103    // The engine reads `reasoning` and `reasoning_budget` from here, and the
1104    // whole map is part of the key a cached result is found under.
1105    let mut universal = Map::new();
1106
1107    universal.insert("reasoning".to_string(), Value::Bool(options.reasoning));
1108
1109    if let Some(transcription) = options.transcription {
1110        universal.insert("transcription".to_string(), json!(transcription));
1111    }
1112
1113    if let Some(budget) = options.reasoning_budget {
1114        universal.insert("reasoning_budget".to_string(), Value::from(budget));
1115    }
1116
1117    if let Some(temperature) = options.temperature.filter(|value| value.is_finite()) {
1118        universal.insert("temperature".to_string(), Value::from(temperature));
1119    }
1120
1121    let mut payload = Map::new();
1122
1123    payload.insert("operation".to_string(), Value::from(operation));
1124    payload.insert("input".to_string(), input);
1125    payload.insert("options".to_string(), Value::Object(universal));
1126
1127    // An operation whose instructions are the platform's is sent none, rather
1128    // than an empty one it would have to tell apart from a prompt.
1129    if let Some(prompt) = prompt {
1130        payload.insert("prompt".to_string(), Value::from(prompt));
1131    }
1132    payload.insert("regenerate".to_string(), Value::Bool(options.regenerate));
1133
1134    if let Some(schema) = schema {
1135        payload.insert("schema".to_string(), schema);
1136    }
1137
1138    if let Some(model) = options.model {
1139        payload.insert("model".to_string(), Value::from(model.as_str()));
1140    }
1141
1142    if let Some(system_prompt) = &options.system_prompt {
1143        payload.insert(
1144            "systemPrompt".to_string(),
1145            Value::from(system_prompt.as_str()),
1146        );
1147    }
1148
1149    if let Some(timeout) = options.timeout {
1150        payload.insert("timeout".to_string(), Value::from(milliseconds(timeout)));
1151    }
1152
1153    Value::Object(payload)
1154}
1155
1156/// A duration as the milliseconds the wire carries.
1157fn milliseconds(timeout: Duration) -> u64 {
1158    u64::try_from(timeout.as_millis()).unwrap_or(u64::MAX)
1159}
1160
1161/// What a run reported about itself.
1162fn metadata_of(metadata: Option<&Value>) -> Metadata {
1163    let Some(metadata) = metadata else {
1164        return Metadata::default();
1165    };
1166
1167    Metadata {
1168        input_tokens: count(metadata, "input_tokens").unwrap_or(0),
1169        output_tokens: count(metadata, "output_tokens").unwrap_or(0),
1170        reasoning_tokens: count(metadata, "reasoning_tokens"),
1171        reasoning: metadata
1172            .get("reasoning")
1173            .and_then(Value::as_str)
1174            .map(str::to_string),
1175        delivery: delivery_of(metadata.get("delivery")),
1176    }
1177}
1178
1179/// One token count, when it is there and is a count.
1180fn count(metadata: &Value, key: &str) -> Option<u64> {
1181    metadata.get(key).and_then(Value::as_u64)
1182}
1183
1184/// How each file travelled, as far as the report can be read.
1185///
1186/// The report explains an answer; it never decides whether there is one. An
1187/// entry that is not an object, names no file, or names a way of travelling
1188/// this SDK does not know is left out rather than failing a run that answered.
1189fn delivery_of(delivery: Option<&Value>) -> Vec<FileDelivery> {
1190    delivery
1191        .and_then(Value::as_array)
1192        .map(|files| files.iter().filter_map(file_delivery).collect())
1193        .unwrap_or_default()
1194}
1195
1196/// One file's delivery, when the entry can be read as one.
1197///
1198/// A range is kept only when both ends are there, because a range with one end
1199/// is not one the engine could have cut. A key sent as `null` reads as absent.
1200fn file_delivery(file: &Value) -> Option<FileDelivery> {
1201    let delivered_as = match file.get("delivered_as").and_then(Value::as_str)? {
1202        "document" => DeliveredAs::Document,
1203        "text" => DeliveredAs::Text,
1204        "image" => DeliveredAs::Image,
1205        _ => return None,
1206    };
1207
1208    let first_page = file.get("first_page").and_then(page_number);
1209    let last_page = file.get("last_page").and_then(page_number);
1210
1211    Some(FileDelivery {
1212        filename: file.get("filename").and_then(Value::as_str)?.to_string(),
1213        delivered_as,
1214        pages: first_page
1215            .zip(last_page)
1216            .map(|(first, last)| Pages::new(first, last)),
1217        transcribed_pages: page_numbers(file.get("transcribed_pages")),
1218        fallback: file
1219            .get("fallback")
1220            .filter(|fallback| fallback.is_object())
1221            .map(delivery_fallback),
1222    })
1223}
1224
1225/// A fallback, read leniently: that the document went instead of its text is
1226/// the fact that matters, so a member missing from the report does not lose it.
1227fn delivery_fallback(fallback: &Value) -> DeliveryFallback {
1228    let text = |key: &str| {
1229        fallback
1230            .get(key)
1231            .and_then(Value::as_str)
1232            .unwrap_or_default()
1233            .to_string()
1234    };
1235
1236    DeliveryFallback {
1237        reason: text("reason"),
1238        pages: page_numbers(fallback.get("pages")),
1239        message: text("message"),
1240    }
1241}
1242
1243/// A page number, when this is one: a whole number from 1.
1244fn page_number(value: &Value) -> Option<u32> {
1245    value
1246        .as_u64()
1247        .and_then(|number| u32::try_from(number).ok())
1248        .filter(|page| *page > 0)
1249}
1250
1251/// The page numbers in a list, leaving out anything that is not one.
1252fn page_numbers(pages: Option<&Value>) -> Vec<u32> {
1253    pages
1254        .and_then(Value::as_array)
1255        .map(|pages| pages.iter().filter_map(page_number).collect())
1256        .unwrap_or_default()
1257}
1258
1259/// Why a page the platform answered for without its text is unread.
1260const NO_TRANSCRIPTION: &str = "no transcription was returned for this page";
1261
1262/// Each page a transcription answered for, in the shape a caller can rely on.
1263///
1264/// An answer without a list of pages has none. An entry that names no page is
1265/// left out, since there is no page it could be the transcription of.
1266fn page_transcriptions(data: &Value) -> Vec<PageTranscription> {
1267    data.get("pages")
1268        .and_then(Value::as_array)
1269        .map(|pages| pages.iter().filter_map(page_transcription).collect())
1270        .unwrap_or_default()
1271}
1272
1273/// One page's transcription: its text or its error, never both.
1274///
1275/// The platform's page is mapped rather than passed through. An error wins
1276/// over any text, so no partial text is handed on, and a page that carries no
1277/// text is answered as unread rather than as text that is not there.
1278fn page_transcription(entry: &Value) -> Option<PageTranscription> {
1279    let page = entry.get("page").and_then(page_number)?;
1280    let error = entry.get("error").and_then(Value::as_str);
1281    let text = entry.get("text").and_then(Value::as_str);
1282
1283    Some(match (error, text) {
1284        (None, Some(text)) => PageTranscription::Read {
1285            page,
1286            text: text.to_string(),
1287        },
1288        (error, _) => PageTranscription::Unread {
1289            page,
1290            error: error.unwrap_or(NO_TRANSCRIPTION).to_string(),
1291        },
1292    })
1293}
1294
1295/// Put whatever is still pending into ephemeral storage, and answer with what
1296/// the operation is to be given instead.
1297///
1298/// A handle that is already stored, and anything that is not a handle at all,
1299/// comes back as it went in.
1300fn upload_pending(value: Value) -> Result<Value, Error> {
1301    if is_pending(&value) {
1302        let stored = host::transport()?
1303            .call(UPLOAD_EPHEMERAL.to_string(), value.clone())
1304            .map_err(|cause| {
1305                cause.hint(
1306                    "The file was not uploaded and the operation did not run. Upload the file, \
1307                     then pass the handle that upload answered with.",
1308                )
1309            })?;
1310
1311        return Ok(stored_handle(value, stored));
1312    }
1313
1314    if let Value::Array(items) = value {
1315        let mut uploaded = Vec::with_capacity(items.len());
1316
1317        for item in items {
1318            uploaded.push(upload_pending(item)?);
1319        }
1320
1321        return Ok(Value::Array(uploaded));
1322    }
1323
1324    Ok(value)
1325}
1326
1327/// The handle the operation reads, once a pending file has been stored.
1328///
1329/// The upload answers with the stored file's own reference: where it is, what
1330/// it hashes to, its name, its type and its size. Every one of those keys
1331/// describes the file, so every one of them is taken from the upload and none
1332/// is carried over. A value from before the upload would name a file that is
1333/// no longer the one being read.
1334///
1335/// Everything else on the handle is the caller's: how the file is to be sent,
1336/// which of its pages, and any key added to a file reference later. Those
1337/// describe the request, not the file, and the upload knows nothing about
1338/// them, so they are carried over. A caller reads a pending file and a stored
1339/// one the same way.
1340///
1341/// `pending` is the one key that is neither. It said the bytes had not been
1342/// stored yet. They have been now, so it is dropped. A handle that still
1343/// called itself pending would be uploaded a second time on the next pass.
1344fn stored_handle(handle: Value, stored: Value) -> Value {
1345    match (handle, stored) {
1346        (Value::Object(mut handle), Value::Object(stored)) => {
1347            handle.remove("pending");
1348            handle.extend(stored);
1349
1350            Value::Object(handle)
1351        }
1352        (_, stored) => stored,
1353    }
1354}
1355
1356/// Whether this is a document handle whose file is still to be uploaded.
1357///
1358/// It is one when it says it is pending and carries the hash of the file it
1359/// stands for, since that hash is what the upload is asked for by.
1360fn is_pending(value: &Value) -> bool {
1361    value.get("pending").and_then(Value::as_bool) == Some(true) && has_file_hash(value)
1362}
1363
1364/// Whether this carries the hash of a file.
1365fn has_file_hash(value: &Value) -> bool {
1366    value
1367        .get("file_hash")
1368        .and_then(Value::as_str)
1369        .is_some_and(|hash| !hash.is_empty())
1370}
1371
1372/// Refuse a value that names nothing, in the words of whoever needed it.
1373fn refuse_empty(value: &Value, message: &str, hint: &str) -> Result<(), Error> {
1374    let empty = match value {
1375        Value::Null => true,
1376        Value::String(text) => text.is_empty(),
1377        _ => false,
1378    };
1379
1380    if empty {
1381        return Err(Error::invalid(message).hint(hint));
1382    }
1383
1384    Ok(())
1385}
1386
1387/// Refuse an operation that has been given nothing to do.
1388fn refuse_empty_prompt(prompt: &str, operation: &str) -> Result<(), Error> {
1389    if prompt.trim().is_empty() {
1390        return Err(Error::invalid(format!("{operation} needs a prompt."))
1391            .hint("Say what the operation is to produce, in a sentence the model can act on."));
1392    }
1393
1394    Ok(())
1395}
1396
1397/// Refuse anything that is not the handle of an audio or video file.
1398fn refuse_unless_media(document: &Value) -> Result<(), Error> {
1399    if !has_file_hash(document) {
1400        return Err(
1401            Error::invalid("transcribe needs a document handle to work on.").hint(
1402                "Pass the handle of the uploaded file, the one carrying file_hash and mime_type.",
1403            ),
1404        );
1405    }
1406
1407    let media = document
1408        .get("mime_type")
1409        .and_then(Value::as_str)
1410        .map(str::to_lowercase)
1411        .is_some_and(|mime| mime.starts_with("audio/") || mime.starts_with("video/"));
1412
1413    if !media {
1414        return Err(Error::invalid("transcribe works on audio and video.")
1415            .hint("Pass a handle whose mime_type begins audio/ or video/."));
1416    }
1417
1418    Ok(())
1419}
1420
1421/// Refuse anything that is not the handle of a stored PDF.
1422///
1423/// The type is compared without its parameters and without regard to case, so
1424/// `Application/PDF; version=1.7` is a PDF.
1425fn refuse_unless_pdf(document: &DocumentHandle) -> Result<(), Error> {
1426    if document.file_hash.is_empty() {
1427        return Err(
1428            Error::invalid("transcribe_pages needs the handle of a stored file.").hint(
1429                "Pass the handle the upload or the record answered with, the one carrying \
1430                 file_hash.",
1431            ),
1432        );
1433    }
1434
1435    let essence = document.mime_type.split(';').next().unwrap_or_default();
1436
1437    if !essence.trim().eq_ignore_ascii_case("application/pdf") {
1438        return Err(Error::invalid("transcribe_pages reads the pages of a PDF.")
1439            .hint("Pass the handle of a PDF. Read any other file with extract or summarize."));
1440    }
1441
1442    Ok(())
1443}
1444
1445/// The schema a transcription is held to, written from what was asked for.
1446fn transcribe_schema(wanted: &TranscribeOptions) -> Value {
1447    let identify = wanted.participants.wanted();
1448
1449    let mut properties = Map::new();
1450    let mut required = vec![Value::from("language")];
1451
1452    properties.insert(
1453        "language".to_string(),
1454        json!({
1455            "description": "The detected language of the audio (ISO 639-1 code, e.g., \"en\", \"es\")",
1456            "type": "string"
1457        }),
1458    );
1459
1460    if wanted.include_transcript {
1461        let description = match (identify, wanted.include_timestamps) {
1462            (true, true) => {
1463                "The full transcript with participant labels and timestamps. \
1464                 Format: [MM:SS] Participant Name: text"
1465            }
1466            (true, false) => {
1467                "The full transcript with participant labels. Format: Participant Name: text"
1468            }
1469            (false, true) => "The full transcript with timestamps. Format: [MM:SS] text",
1470            (false, false) => "The full transcript of the audio",
1471        };
1472
1473        properties.insert(
1474            "transcript".to_string(),
1475            json!({ "description": description, "type": "string" }),
1476        );
1477        required.push(Value::from("transcript"));
1478    }
1479
1480    if wanted.summarize {
1481        let description = if identify {
1482            "A concise summary of the audio content, including key points from each participant"
1483        } else {
1484            "A concise summary of the audio content"
1485        };
1486
1487        properties.insert(
1488            "summary".to_string(),
1489            json!({ "description": description, "type": "string" }),
1490        );
1491        required.push(Value::from("summary"));
1492    }
1493
1494    if identify {
1495        properties.insert(
1496            "participants".to_string(),
1497            json!({
1498                "description": "List of identified participants in the audio",
1499                "items": { "type": "string" },
1500                "type": "array"
1501            }),
1502        );
1503        required.push(Value::from("participants"));
1504    }
1505
1506    json!({ "properties": properties, "required": required, "type": "object" })
1507}
1508
1509/// The prompt a transcription runs on, written from what was asked for.
1510fn transcribe_prompt(wanted: &TranscribeOptions) -> String {
1511    let identify = wanted.participants.wanted();
1512    let names = wanted.participants.names();
1513
1514    let mut prompt = String::from("Analyze this audio/video file and provide:\n");
1515
1516    if wanted.include_transcript {
1517        if identify {
1518            match &names {
1519                Some(names) => {
1520                    prompt.push_str("- A complete transcript identifying these participants: ");
1521                    prompt.push_str(names);
1522                    prompt.push_str(". ");
1523                }
1524                None => prompt.push_str(
1525                    "- A complete transcript with participant identification \
1526                     (label participants as Participant 1, Participant 2, etc.). ",
1527                ),
1528            }
1529
1530            if wanted.include_timestamps {
1531                prompt.push_str(
1532                    "Include timestamps in [MM:SS] format before each participant segment.\n",
1533                );
1534            } else {
1535                prompt.push_str("Format each line as \"Participant Name: text\".\n");
1536            }
1537        } else if wanted.include_timestamps {
1538            prompt.push_str(
1539                "- A complete transcript with timestamps in [MM:SS] format before each segment\n",
1540            );
1541        } else {
1542            prompt.push_str("- A complete transcript of all spoken content\n");
1543        }
1544    }
1545
1546    if wanted.summarize {
1547        if identify {
1548            prompt.push_str("- A concise summary highlighting key points from each participant\n");
1549        } else {
1550            prompt.push_str("- A concise summary of the main points and key information\n");
1551        }
1552    }
1553
1554    if identify {
1555        match &names {
1556            Some(names) => {
1557                prompt.push_str("- Identify and distinguish between these participants: ");
1558                prompt.push_str(names);
1559                prompt.push('\n');
1560            }
1561            None => prompt.push_str("- Identify and list all distinct participants in the audio\n"),
1562        }
1563    }
1564
1565    prompt.push_str("- The detected language code (ISO 639-1 format)\n");
1566
1567    prompt
1568}
1569
1570#[cfg(test)]
1571mod tests {
1572    #[test]
1573    fn transcription_posts_exact_options_on_all_four_calls() {
1574        for transcription in [
1575            None,
1576            Some(Transcription::Standard),
1577            Some(Transcription::Precise),
1578        ] {
1579            for operation in ["extract", "summarize", "transcribe", "transcribe_pages"] {
1580                let session = testing::install(move |_name, _params| {
1581                    Ok(
1582                        json!({ "data": if operation == "summarize" { json!("summary") } else { json!({ "pages": [] }) } }),
1583                    )
1584                });
1585                let options = Options {
1586                    transcription,
1587                    ..Default::default()
1588                };
1589                match operation {
1590                    "extract" => {
1591                        let _: Execution<Value> = extract(
1592                            json!(stored()),
1593                            "Read it.",
1594                            json!({ "type": "object" }),
1595                            options,
1596                        )
1597                        .unwrap();
1598                    }
1599                    "summarize" => {
1600                        summarize(json!(stored()), "Read it.", options).unwrap();
1601                    }
1602                    "transcribe" => {
1603                        transcribe(
1604                            json!({ "file_hash": "abc", "mime_type": "audio/wav" }),
1605                            TranscribeOptions {
1606                                include_transcript: true,
1607                                ..Default::default()
1608                            },
1609                            options,
1610                        )
1611                        .unwrap();
1612                    }
1613                    _ => {
1614                        transcribe_pages(
1615                            &stored(),
1616                            None,
1617                            TranscribePagesOptions {
1618                                transcription,
1619                                ..Default::default()
1620                            },
1621                        )
1622                        .unwrap();
1623                    }
1624                }
1625                let expected = match transcription {
1626                    None => json!({ "reasoning": true }),
1627                    Some(Transcription::Standard) => {
1628                        json!({ "reasoning": true, "transcription": "standard" })
1629                    }
1630                    Some(Transcription::Precise) => {
1631                        json!({ "reasoning": true, "transcription": "precise" })
1632                    }
1633                };
1634                assert_eq!(session.calls().len(), 1);
1635                assert_eq!(session.calls()[0].name, ORCHESTRATOR);
1636                assert_eq!(session.calls()[0].params["options"], expected);
1637                assert_eq!(session.calls()[0].params["regenerate"], json!(false));
1638            }
1639        }
1640    }
1641
1642    #[test]
1643    fn transcription_preserves_existing_options_and_adds_only_its_wire_key() {
1644        for operation in ["extract", "summarize", "transcribe", "transcribe_pages"] {
1645            let session = testing::install(move |_name, _params| {
1646                Ok(
1647                    json!({ "data": if operation == "summarize" { json!("summary") } else { json!({ "pages": [] }) } }),
1648                )
1649            });
1650            for transcription in [None, Some(Transcription::Precise)] {
1651                let options = Options {
1652                    transcription,
1653                    reasoning: false,
1654                    reasoning_budget: Some(2048),
1655                    temperature: Some(0.25),
1656                    regenerate: true,
1657                    timeout: Some(Duration::from_secs(90)),
1658                    ..Default::default()
1659                };
1660                match operation {
1661                    "extract" => {
1662                        let _: Execution<Value> = extract(
1663                            json!(stored()),
1664                            "Read it.",
1665                            json!({ "type": "object" }),
1666                            options,
1667                        )
1668                        .unwrap();
1669                    }
1670                    "summarize" => {
1671                        summarize(json!(stored()), "Read it.", options).unwrap();
1672                    }
1673                    "transcribe" => {
1674                        transcribe(
1675                            json!({ "file_hash": "abc", "mime_type": "audio/wav" }),
1676                            TranscribeOptions {
1677                                include_transcript: true,
1678                                ..Default::default()
1679                            },
1680                            options,
1681                        )
1682                        .unwrap();
1683                    }
1684                    _ => {
1685                        transcribe_pages(
1686                            &stored(),
1687                            None,
1688                            TranscribePagesOptions {
1689                                transcription,
1690                                regenerate: true,
1691                                timeout: Some(Duration::from_secs(90)),
1692                            },
1693                        )
1694                        .unwrap();
1695                    }
1696                }
1697            }
1698            let calls = session.calls();
1699            let expected = if operation == "transcribe_pages" {
1700                json!({ "reasoning": true })
1701            } else {
1702                json!({ "reasoning": false, "reasoning_budget": 2048, "temperature": 0.25 })
1703            };
1704            assert_eq!(calls[0].params["options"], expected);
1705            let mut precise = calls[0].params.clone();
1706            precise["options"]["transcription"] = json!("precise");
1707            assert_eq!(calls[1].params, precise);
1708        }
1709    }
1710
1711    #[test]
1712    fn transcription_refuses_invalid_values_before_any_host_call() {
1713        let session = testing::install(|_name, _params| Ok(answered()));
1714        for value in [
1715            json!("other"),
1716            json!(""),
1717            Value::Null,
1718            json!(0),
1719            json!(false),
1720            json!({}),
1721            json!([]),
1722        ] {
1723            let error = serde_json::from_value::<Transcription>(value).unwrap_err();
1724            if error.to_string().contains("unknown variant") {
1725                assert!(error.to_string().contains("standard"));
1726                assert!(error.to_string().contains("precise"));
1727            }
1728        }
1729        assert!(session.calls().is_empty());
1730    }
1731
1732    use serde_json::json;
1733
1734    use super::*;
1735    use crate::testing;
1736
1737    /// What the primitive answers when a test does not care what came back.
1738    fn answered() -> Value {
1739        json!({ "data": { "ok": true }, "metadata": { "input_tokens": 1, "output_tokens": 2 } })
1740    }
1741
1742    /// A stored file, as an upload answers with one.
1743    fn stored() -> DocumentHandle {
1744        DocumentHandle {
1745            file_hash: "ffce20f1".to_string(),
1746            filename: "contract.pdf".to_string(),
1747            mime_type: "application/pdf".to_string(),
1748            size: 1_234,
1749            storage_path: "acme/documents/ffce20f1".to_string(),
1750        }
1751    }
1752
1753    #[test]
1754    fn a_document_input_travels_as_the_handle_with_the_keys_the_engine_reads() {
1755        let sent = json!(DocumentInput {
1756            file: stored(),
1757            pages: Some(Pages::new(12, 30)),
1758            deliver_as: Some(Delivery::Text),
1759        });
1760
1761        assert_eq!(sent["storage_path"], json!("acme/documents/ffce20f1"));
1762        assert_eq!(sent["file_hash"], json!("ffce20f1"));
1763        assert_eq!(sent["mime_type"], json!("application/pdf"));
1764        assert_eq!(
1765            sent["first_page"],
1766            json!(12),
1767            "a range travels as the two keys the engine reads, not as a nested one"
1768        );
1769        assert_eq!(sent["last_page"], json!(30));
1770        assert_eq!(sent["deliver_as"], json!("text"));
1771    }
1772
1773    #[test]
1774    fn a_document_input_that_asks_for_nothing_carries_neither_key() {
1775        let sent = json!(DocumentInput {
1776            file: stored(),
1777            ..Default::default()
1778        });
1779
1780        assert_eq!(sent["filename"], json!("contract.pdf"));
1781        assert_eq!(
1782            sent.get("deliver_as"),
1783            None,
1784            "asking for nothing says nothing, so the default stays the engine's"
1785        );
1786        assert_eq!(sent.get("first_page"), None);
1787        assert_eq!(sent.get("last_page"), None);
1788    }
1789
1790    #[test]
1791    fn an_extraction_asks_the_primitive_and_answers_with_the_type_it_was_asked_for() {
1792        #[derive(Debug, Deserialize, PartialEq)]
1793        struct Invoice {
1794            number: String,
1795            total: f64,
1796        }
1797
1798        let session = testing::install(|name, params| {
1799            assert_eq!(name, ORCHESTRATOR);
1800            assert_eq!(params["operation"], json!("extract"));
1801            assert_eq!(params["prompt"], json!("Read it."));
1802            assert_eq!(params["input"], json!("INV-8, 240.00"));
1803            assert_eq!(params["schema"]["type"], json!("object"));
1804
1805            Ok(json!({
1806                "data": { "number": "INV-8", "total": 240.0 },
1807                "metadata": { "input_tokens": 11, "output_tokens": 3 }
1808            }))
1809        });
1810
1811        let read: Execution<Invoice> = extract(
1812            json!("INV-8, 240.00"),
1813            "Read it.",
1814            json!({ "type": "object" }),
1815            Options::default(),
1816        )
1817        .unwrap();
1818
1819        assert_eq!(
1820            read.data,
1821            Invoice {
1822                number: "INV-8".to_string(),
1823                total: 240.0
1824            }
1825        );
1826        assert_eq!(read.metadata.input_tokens, 11);
1827        assert_eq!(read.metadata.output_tokens, 3);
1828        assert_eq!(session.calls().len(), 1);
1829    }
1830
1831    #[test]
1832    fn a_default_call_reasons_does_not_regenerate_and_leaves_the_rest_to_the_platform() {
1833        let session = testing::install(|_name, _params| Ok(answered()));
1834
1835        let _: Execution<Value> = extract(
1836            json!("text"),
1837            "Read it.",
1838            json!({ "type": "object" }),
1839            Options::default(),
1840        )
1841        .unwrap();
1842
1843        let sent = session.calls()[0].params.clone();
1844
1845        assert_eq!(sent["options"], json!({ "reasoning": true }));
1846        assert_eq!(sent["regenerate"], json!(false));
1847        assert!(sent.get("model").is_none());
1848        assert!(sent.get("systemPrompt").is_none());
1849        assert!(sent.get("timeout").is_none());
1850    }
1851
1852    #[test]
1853    fn every_option_that_was_set_travels_with_the_operation() {
1854        let session = testing::install(|_name, _params| Ok(answered()));
1855
1856        let _: Execution<Value> = extract(
1857            json!("text"),
1858            "Read it.",
1859            json!({ "type": "object" }),
1860            Options {
1861                model: Some(Model::Xl),
1862                transcription: None,
1863                system_prompt: Some("You are an auditor.".to_string()),
1864                temperature: Some(0.25),
1865                reasoning: false,
1866                reasoning_budget: Some(2_048),
1867                regenerate: true,
1868                timeout: Some(Duration::from_secs(90)),
1869            },
1870        )
1871        .unwrap();
1872
1873        let sent = session.calls()[0].params.clone();
1874
1875        assert_eq!(sent["model"], json!("xl"));
1876        assert_eq!(sent["systemPrompt"], json!("You are an auditor."));
1877        assert_eq!(sent["regenerate"], json!(true));
1878        assert_eq!(sent["timeout"], json!(90_000));
1879        assert_eq!(
1880            sent["options"],
1881            json!({ "reasoning": false, "reasoning_budget": 2_048, "temperature": 0.25 })
1882        );
1883    }
1884
1885    #[test]
1886    fn a_summary_answers_with_the_prose_and_carries_no_schema() {
1887        let session = testing::install(|_name, params| {
1888            assert_eq!(params["operation"], json!("summarize"));
1889            assert!(params.get("schema").is_none());
1890
1891            Ok(json!({ "data": "A refund was agreed.", "metadata": { "output_tokens": 5 } }))
1892        });
1893
1894        let written = summarize(json!("A long thread."), "One sentence.", Options::default())
1895            .expect("a summary answers with prose");
1896
1897        assert_eq!(written.data, "A refund was agreed.");
1898        assert_eq!(written.metadata.output_tokens, 5);
1899        assert_eq!(session.calls().len(), 1);
1900    }
1901
1902    #[test]
1903    fn a_pending_document_is_uploaded_before_the_operation_reads_it() {
1904        let session = testing::install(|name, _params| {
1905            if name == UPLOAD_EPHEMERAL {
1906                return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
1907            }
1908
1909            Ok(answered())
1910        });
1911
1912        let _: Execution<Value> = extract(
1913            json!({ "file_hash": "abc", "pending": true }),
1914            "Read it.",
1915            json!({ "type": "object" }),
1916            Options::default(),
1917        )
1918        .unwrap();
1919
1920        let calls = session.calls();
1921
1922        assert_eq!(calls.len(), 2);
1923        assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
1924        assert_eq!(calls[1].name, ORCHESTRATOR);
1925        assert_eq!(
1926            calls[1].params["input"],
1927            json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }),
1928            "the operation reads the handle the upload answered with"
1929        );
1930    }
1931
1932    #[test]
1933    fn a_pending_document_is_read_the_way_the_caller_asked_for_it() {
1934        let session = testing::install(|name, _params| {
1935            if name == UPLOAD_EPHEMERAL {
1936                return Ok(json!({
1937                    "file_hash": "ffce20f1",
1938                    "filename": "contract.pdf",
1939                    "mime_type": "application/pdf",
1940                    "size": 1_234,
1941                    "storage_path": "acme/ephemeral/ffce20f1"
1942                }));
1943            }
1944
1945            Ok(answered())
1946        });
1947
1948        let _: Execution<Value> = extract(
1949            json!({
1950                "file_hash": "staged",
1951                "first_page": 12,
1952                "last_page": 30,
1953                "pending": true,
1954                "deliver_as": "text",
1955                "storage_path": "acme/staged/staged"
1956            }),
1957            "Read it.",
1958            json!({ "type": "object" }),
1959            Options::default(),
1960        )
1961        .unwrap();
1962
1963        let calls = session.calls();
1964        let sent = calls[1].params["input"].clone();
1965
1966        assert_eq!(
1967            sent["deliver_as"],
1968            json!("text"),
1969            "the caller said how the file was to be sent"
1970        );
1971        assert_eq!(
1972            sent["first_page"],
1973            json!(12),
1974            "the caller asked for a range"
1975        );
1976        assert_eq!(sent["last_page"], json!(30), "the caller asked for a range");
1977        assert_eq!(
1978            sent["file_hash"],
1979            json!("ffce20f1"),
1980            "the file is the one the upload stored"
1981        );
1982        assert_eq!(
1983            sent["storage_path"],
1984            json!("acme/ephemeral/ffce20f1"),
1985            "the file is read from where the upload put it"
1986        );
1987        assert_eq!(sent["filename"], json!("contract.pdf"));
1988        assert_eq!(sent["mime_type"], json!("application/pdf"));
1989        assert_eq!(sent["size"], json!(1_234));
1990        assert!(
1991            sent.get("pending").is_none(),
1992            "the file is stored, so the handle may not still call itself pending"
1993        );
1994    }
1995
1996    #[test]
1997    fn a_document_that_is_already_stored_is_read_where_it_is() {
1998        let session = testing::install(|_name, _params| Ok(answered()));
1999
2000        let handle = json!({ "file_hash": "abc", "mime_type": "application/pdf" });
2001
2002        let _: Execution<Value> = extract(
2003            handle.clone(),
2004            "Read it.",
2005            json!({ "type": "object" }),
2006            Options::default(),
2007        )
2008        .unwrap();
2009
2010        let calls = session.calls();
2011
2012        assert_eq!(calls.len(), 1, "nothing was uploaded");
2013        assert_eq!(calls[0].params["input"], handle);
2014    }
2015
2016    #[test]
2017    fn a_list_of_documents_is_uploaded_item_by_item() {
2018        let session = testing::install(|name, params| {
2019            if name == UPLOAD_EPHEMERAL {
2020                let hash = params["file_hash"].as_str().unwrap_or_default();
2021
2022                return Ok(json!({
2023                    "file_hash": hash,
2024                    "storage_path": format!("ephemeral/{hash}")
2025                }));
2026            }
2027
2028            Ok(answered())
2029        });
2030
2031        let _: Execution<Value> = extract(
2032            json!([
2033                { "file_hash": "one", "pending": true },
2034                { "file_hash": "two", "mime_type": "image/png" },
2035                { "file_hash": "three", "pending": true }
2036            ]),
2037            "Read them.",
2038            json!({ "type": "object" }),
2039            Options::default(),
2040        )
2041        .unwrap();
2042
2043        let calls = session.calls();
2044
2045        assert_eq!(calls.len(), 3, "two uploads and the operation");
2046        assert_eq!(
2047            calls[2].params["input"],
2048            json!([
2049                { "file_hash": "one", "storage_path": "ephemeral/one" },
2050                { "file_hash": "two", "mime_type": "image/png" },
2051                { "file_hash": "three", "storage_path": "ephemeral/three" }
2052            ])
2053        );
2054    }
2055
2056    #[test]
2057    fn a_handle_is_pending_only_while_it_says_so_and_carries_a_hash_to_upload_by() {
2058        assert!(is_pending(&json!({ "file_hash": "abc", "pending": true })));
2059        assert!(!is_pending(&json!({ "file_hash": "abc" })));
2060        assert!(!is_pending(&json!({ "pending": true })));
2061        assert!(!is_pending(&json!({ "file_hash": "", "pending": true })));
2062        assert!(!is_pending(
2063            &json!({ "file_hash": "abc", "pending": "yes" })
2064        ));
2065        assert!(!is_pending(&json!("some words")));
2066        assert!(!is_pending(&json!([
2067            { "file_hash": "abc", "pending": true }
2068        ])));
2069    }
2070
2071    #[test]
2072    fn an_answer_that_reports_nothing_about_its_cost_is_still_an_answer() {
2073        let _session = testing::install(|_name, _params| Ok(json!({ "data": "done" })));
2074
2075        let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
2076
2077        assert_eq!(written.data, "done");
2078        assert_eq!(written.metadata, Metadata::default());
2079    }
2080
2081    #[test]
2082    fn reasoning_reaches_the_caller_when_the_run_reported_it() {
2083        let _session = testing::install(|_name, _params| {
2084            Ok(json!({
2085                "data": "done",
2086                "metadata": {
2087                    "input_tokens": 9,
2088                    "output_tokens": 4,
2089                    "reasoning": "Read the total from the last line.",
2090                    "reasoning_tokens": 120
2091                }
2092            }))
2093        });
2094
2095        let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
2096
2097        assert_eq!(written.metadata.reasoning_tokens, Some(120));
2098        assert_eq!(
2099            written.metadata.reasoning.as_deref(),
2100            Some("Read the total from the last line.")
2101        );
2102    }
2103
2104    #[test]
2105    fn a_run_reports_how_each_file_travelled_in_the_order_the_files_were_given() {
2106        let _session = testing::install(|_name, _params| {
2107            Ok(json!({
2108                "data": "done",
2109                "metadata": {
2110                    "input_tokens": 9,
2111                    "output_tokens": 4,
2112                    "delivery": [
2113                        {
2114                            "filename": "contract.pdf",
2115                            "delivered_as": "text",
2116                            "first_page": 40,
2117                            "last_page": 52,
2118                            "transcribed_pages": [41, 44],
2119                            "fallback": null
2120                        },
2121                        {
2122                            "filename": "drawings.pdf",
2123                            "delivered_as": "document",
2124                            "first_page": null,
2125                            "last_page": null,
2126                            "transcribed_pages": [],
2127                            "fallback": {
2128                                "reason": "transcription_failed",
2129                                "pages": [3, 7],
2130                                "message": "page 3: timed out; page 7: blank answer"
2131                            }
2132                        },
2133                        {
2134                            "filename": "site.jpg",
2135                            "delivered_as": "image",
2136                            "first_page": null,
2137                            "last_page": null,
2138                            "transcribed_pages": [],
2139                            "fallback": null
2140                        }
2141                    ]
2142                }
2143            }))
2144        });
2145
2146        let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
2147
2148        assert_eq!(
2149            written.metadata.delivery,
2150            vec![
2151                FileDelivery {
2152                    filename: "contract.pdf".to_string(),
2153                    delivered_as: DeliveredAs::Text,
2154                    pages: Some(Pages::new(40, 52)),
2155                    transcribed_pages: vec![41, 44],
2156                    fallback: None,
2157                },
2158                FileDelivery {
2159                    filename: "drawings.pdf".to_string(),
2160                    delivered_as: DeliveredAs::Document,
2161                    pages: None,
2162                    transcribed_pages: Vec::new(),
2163                    fallback: Some(DeliveryFallback {
2164                        reason: "transcription_failed".to_string(),
2165                        pages: vec![3, 7],
2166                        message: "page 3: timed out; page 7: blank answer".to_string(),
2167                    }),
2168                },
2169                FileDelivery {
2170                    filename: "site.jpg".to_string(),
2171                    delivered_as: DeliveredAs::Image,
2172                    pages: None,
2173                    transcribed_pages: Vec::new(),
2174                    fallback: None,
2175                },
2176            ]
2177        );
2178        assert_eq!(
2179            written.metadata.input_tokens, 9,
2180            "the members a result already had read as they did"
2181        );
2182    }
2183
2184    #[test]
2185    fn an_answer_without_a_delivery_report_carries_none() {
2186        for metadata in [
2187            json!({ "input_tokens": 1 }),
2188            json!({ "delivery": null }),
2189            json!({ "delivery": "document" }),
2190            json!({ "delivery": { "filename": "contract.pdf", "delivered_as": "text" } }),
2191        ] {
2192            let _session = testing::install(move |_name, _params| {
2193                Ok(json!({ "data": "done", "metadata": metadata.clone() }))
2194            });
2195
2196            let written = summarize(json!("text"), "One sentence.", Options::default())
2197                .expect("a report that cannot be read never fails the run");
2198
2199            assert!(written.metadata.delivery.is_empty());
2200        }
2201    }
2202
2203    #[test]
2204    fn a_delivery_entry_that_cannot_be_read_is_left_out_and_the_rest_are_kept() {
2205        let delivery = delivery_of(Some(&json!([
2206            "contract.pdf",
2207            { "filename": "no-way.pdf" },
2208            { "filename": "audio.mp3", "delivered_as": "audio" },
2209            { "delivered_as": "text" },
2210            { "filename": 7, "delivered_as": "text" },
2211            {
2212                "filename": "kept.pdf",
2213                "delivered_as": "text",
2214                "first_page": 4,
2215                "transcribed_pages": ["5", -1, 0, 6, 4_294_967_296_u64, null]
2216            }
2217        ])));
2218
2219        assert_eq!(
2220            delivery,
2221            vec![FileDelivery {
2222                filename: "kept.pdf".to_string(),
2223                delivered_as: DeliveredAs::Text,
2224                pages: None,
2225                transcribed_pages: vec![6],
2226                fallback: None,
2227            }],
2228            "a range with one end is not a range, and only whole pages from 1 are pages"
2229        );
2230    }
2231
2232    #[test]
2233    fn a_fallback_that_is_reported_is_never_lost_to_a_missing_member() {
2234        let delivery = delivery_of(Some(&json!([
2235            {
2236                "filename": "contract.pdf",
2237                "delivered_as": "document",
2238                "fallback": { "reason": "transcription_failed" }
2239            },
2240            {
2241                "filename": "drawings.pdf",
2242                "delivered_as": "document",
2243                "fallback": "transcription_failed"
2244            }
2245        ])));
2246
2247        assert_eq!(
2248            delivery[0].fallback,
2249            Some(DeliveryFallback {
2250                reason: "transcription_failed".to_string(),
2251                pages: Vec::new(),
2252                message: String::new(),
2253            })
2254        );
2255        assert_eq!(
2256            delivery[1].fallback, None,
2257            "a fallback that is not an object says nothing that can be read"
2258        );
2259        assert!(delivery[0].transcribed_pages.is_empty());
2260    }
2261
2262    #[test]
2263    fn an_operation_with_nothing_to_do_is_refused_before_anything_is_sent() {
2264        let session = testing::install(|_name, _params| Ok(answered()));
2265
2266        let missing_input = extract::<Value>(
2267            json!(null),
2268            "Read it.",
2269            json!({ "type": "object" }),
2270            Options::default(),
2271        )
2272        .unwrap_err();
2273
2274        let missing_prompt = extract::<Value>(
2275            json!("text"),
2276            "   ",
2277            json!({ "type": "object" }),
2278            Options::default(),
2279        )
2280        .unwrap_err();
2281
2282        let missing_schema =
2283            extract::<Value>(json!("text"), "Read it.", json!([]), Options::default()).unwrap_err();
2284
2285        let missing_summary_input =
2286            summarize(json!(""), "One sentence.", Options::default()).unwrap_err();
2287
2288        for refusal in [
2289            &missing_input,
2290            &missing_prompt,
2291            &missing_schema,
2292            &missing_summary_input,
2293        ] {
2294            assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
2295        }
2296
2297        assert!(session.calls().is_empty());
2298    }
2299
2300    #[test]
2301    fn a_transcription_writes_its_own_schema_and_prompt() {
2302        let session = testing::install(|_name, _params| {
2303            Ok(json!({
2304                "data": { "language": "en", "transcript": "Hello." },
2305                "metadata": { "input_tokens": 400, "output_tokens": 12 }
2306            }))
2307        });
2308
2309        let heard = transcribe(
2310            json!({ "file_hash": "abc", "mime_type": "AUDIO/MPEG" }),
2311            TranscribeOptions {
2312                include_transcript: true,
2313                ..Default::default()
2314            },
2315            Options::default(),
2316        )
2317        .expect("an uppercase mime type is the same mime type");
2318
2319        assert_eq!(heard.data.language, "en");
2320        assert_eq!(heard.data.transcript.as_deref(), Some("Hello."));
2321        assert_eq!(heard.data.summary, None);
2322        assert!(heard.data.participants.is_empty());
2323
2324        let sent = session.calls()[0].params.clone();
2325
2326        assert_eq!(sent["operation"], json!("extract"));
2327        assert_eq!(
2328            sent["schema"]["required"],
2329            json!(["language", "transcript"])
2330        );
2331        assert_eq!(sent["schema"]["properties"]["transcript"]["type"], "string");
2332        assert_eq!(
2333            sent["prompt"],
2334            json!(
2335                "Analyze this audio/video file and provide:\n\
2336                 - A complete transcript of all spoken content\n\
2337                 - The detected language code (ISO 639-1 format)\n"
2338            )
2339        );
2340    }
2341
2342    #[test]
2343    fn named_participants_reach_both_the_prompt_and_the_schema() {
2344        let session = testing::install(|_name, _params| {
2345            Ok(json!({ "data": { "language": "en", "participants": ["Customer", "Agent"] } }))
2346        });
2347
2348        let heard = transcribe(
2349            json!({ "file_hash": "abc", "mime_type": "video/mp4" }),
2350            TranscribeOptions {
2351                include_transcript: true,
2352                include_timestamps: true,
2353                summarize: true,
2354                participants: Participants::Named(vec![
2355                    "Customer".to_string(),
2356                    "Agent".to_string(),
2357                ]),
2358            },
2359            Options::default(),
2360        )
2361        .unwrap();
2362
2363        assert_eq!(heard.data.participants, ["Customer", "Agent"]);
2364
2365        let sent = session.calls()[0].params.clone();
2366        let prompt = sent["prompt"].as_str().unwrap_or_default().to_string();
2367
2368        assert_eq!(
2369            sent["schema"]["required"],
2370            json!(["language", "transcript", "summary", "participants"])
2371        );
2372        assert_eq!(
2373            sent["schema"]["properties"]["participants"]["items"]["type"],
2374            json!("string")
2375        );
2376        assert!(prompt.contains("identifying these participants: Customer, Agent. "));
2377        assert!(prompt.contains("Include timestamps in [MM:SS] format"));
2378        assert!(
2379            prompt.contains("- A concise summary highlighting key points from each participant\n")
2380        );
2381        assert!(prompt
2382            .contains("- Identify and distinguish between these participants: Customer, Agent\n"));
2383    }
2384
2385    #[test]
2386    fn detected_participants_are_labelled_rather_than_named() {
2387        let session =
2388            testing::install(|_name, _params| Ok(json!({ "data": { "language": "en" } })));
2389
2390        let _ = transcribe(
2391            json!({ "file_hash": "abc", "mime_type": "audio/wav" }),
2392            TranscribeOptions {
2393                include_transcript: true,
2394                participants: Participants::Detect,
2395                ..Default::default()
2396            },
2397            Options::default(),
2398        )
2399        .unwrap();
2400
2401        let prompt = session.calls()[0].params["prompt"]
2402            .as_str()
2403            .unwrap_or_default()
2404            .to_string();
2405
2406        assert!(prompt.contains("label participants as Participant 1, Participant 2, etc."));
2407        assert!(prompt.contains("Format each line as \"Participant Name: text\".\n"));
2408        assert!(prompt.contains("- Identify and list all distinct participants in the audio\n"));
2409    }
2410
2411    #[test]
2412    fn naming_nobody_asks_for_the_same_thing_as_detecting() {
2413        let wanted = |participants| TranscribeOptions {
2414            include_transcript: true,
2415            participants,
2416            ..Default::default()
2417        };
2418
2419        assert_eq!(
2420            transcribe_prompt(&wanted(Participants::Named(Vec::new()))),
2421            transcribe_prompt(&wanted(Participants::Detect))
2422        );
2423        assert_eq!(
2424            transcribe_schema(&wanted(Participants::Named(Vec::new()))),
2425            transcribe_schema(&wanted(Participants::Detect))
2426        );
2427    }
2428
2429    #[test]
2430    fn a_transcription_that_cannot_run_is_refused_before_anything_is_sent() {
2431        let session = testing::install(|_name, _params| Ok(answered()));
2432
2433        let audio = json!({ "file_hash": "abc", "mime_type": "audio/mpeg" });
2434
2435        let nothing_wanted = transcribe(
2436            audio.clone(),
2437            TranscribeOptions::default(),
2438            Options::default(),
2439        )
2440        .unwrap_err();
2441
2442        let not_media = transcribe(
2443            json!({ "file_hash": "abc", "mime_type": "application/pdf" }),
2444            TranscribeOptions {
2445                include_transcript: true,
2446                ..Default::default()
2447            },
2448            Options::default(),
2449        )
2450        .unwrap_err();
2451
2452        let not_a_handle = transcribe(
2453            json!("some words"),
2454            TranscribeOptions {
2455                summarize: true,
2456                ..Default::default()
2457            },
2458            Options::default(),
2459        )
2460        .unwrap_err();
2461
2462        for refusal in [&nothing_wanted, &not_media, &not_a_handle] {
2463            assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
2464        }
2465
2466        assert!(session.calls().is_empty());
2467    }
2468
2469    #[test]
2470    fn a_page_transcription_asks_for_the_transcribe_operation_with_the_range_and_no_prompt() {
2471        let session = testing::install(|_name, _params| {
2472            Ok(json!({
2473                "data": {
2474                    "pages": [
2475                        { "page": 41, "text": "Scope of Work" },
2476                        { "page": 42, "error": "the answer carries no pages" }
2477                    ]
2478                },
2479                "metadata": {
2480                    "delivery": null,
2481                    "input_tokens": 0,
2482                    "output_tokens": 0,
2483                    "reasoning_tokens": 0
2484                }
2485            }))
2486        });
2487
2488        let read = transcribe_pages(
2489            &stored(),
2490            Some(Pages::new(40, 52)),
2491            TranscribePagesOptions::default(),
2492        )
2493        .unwrap();
2494
2495        let calls = session.calls();
2496
2497        assert_eq!(calls.len(), 1);
2498        assert_eq!(calls[0].name, ORCHESTRATOR);
2499        assert_eq!(
2500            calls[0].params,
2501            json!({
2502                "operation": "transcribe",
2503                "input": {
2504                    "file_hash": "ffce20f1",
2505                    "filename": "contract.pdf",
2506                    "mime_type": "application/pdf",
2507                    "size": 1_234,
2508                    "storage_path": "acme/documents/ffce20f1",
2509                    "first_page": 40,
2510                    "last_page": 52
2511                },
2512                "options": { "reasoning": true },
2513                "regenerate": false
2514            }),
2515            "no prompt, schema, model or delivery: the instructions are the platform's"
2516        );
2517
2518        assert_eq!(
2519            read.data,
2520            vec![
2521                PageTranscription::Read {
2522                    page: 41,
2523                    text: "Scope of Work".to_string()
2524                },
2525                PageTranscription::Unread {
2526                    page: 42,
2527                    error: "the answer carries no pages".to_string()
2528                },
2529            ]
2530        );
2531        assert_eq!(read.metadata.input_tokens, 0);
2532        assert!(read.metadata.delivery.is_empty());
2533    }
2534
2535    #[test]
2536    fn a_page_transcription_carries_only_the_whole_file_and_the_options_it_was_given() {
2537        let session = testing::install(|_name, _params| Ok(json!({ "data": { "pages": [] } })));
2538
2539        let read = transcribe_pages(
2540            &stored(),
2541            None,
2542            TranscribePagesOptions {
2543                regenerate: true,
2544                timeout: Some(Duration::from_secs(90)),
2545                transcription: None,
2546            },
2547        )
2548        .unwrap();
2549
2550        let sent = session.calls()[0].params.clone();
2551
2552        assert!(read.data.is_empty());
2553        assert!(sent["input"].get("first_page").is_none());
2554        assert!(sent["input"].get("last_page").is_none());
2555        assert_eq!(sent["regenerate"], json!(true));
2556        assert_eq!(sent["timeout"], json!(90_000));
2557        assert_eq!(sent["options"], json!({ "reasoning": true }));
2558    }
2559
2560    #[test]
2561    fn a_page_with_no_text_is_answered_as_unread_never_as_text_that_is_not_there() {
2562        let _session = testing::install(|_name, _params| {
2563            Ok(json!({
2564                "data": {
2565                    "pages": [
2566                        { "page": 7, "text": "" },
2567                        { "page": 8, "error": "the model timed out", "text": "Scope of" },
2568                        { "page": 9 },
2569                        { "page": 10, "transcriptions": ["Scope of Work", "Scope of Work"] },
2570                        { "page": 11, "error": null, "text": "Clause 4" },
2571                        { "page": 12, "error": 500, "text": "Clause 5" },
2572                        { "page": 13, "text": null },
2573                        { "text": "a page with no number" },
2574                        { "page": "14", "text": "a number that is a string" },
2575                        "page 15"
2576                    ]
2577                }
2578            }))
2579        });
2580
2581        let read = transcribe_pages(&stored(), None, TranscribePagesOptions::default()).unwrap();
2582
2583        let unread = |page: u32, error: &str| PageTranscription::Unread {
2584            page,
2585            error: error.to_string(),
2586        };
2587        let read_as = |page: u32, text: &str| PageTranscription::Read {
2588            page,
2589            text: text.to_string(),
2590        };
2591
2592        assert_eq!(
2593            read.data,
2594            vec![
2595                read_as(7, ""),
2596                unread(8, "the model timed out"),
2597                unread(9, NO_TRANSCRIPTION),
2598                unread(10, NO_TRANSCRIPTION),
2599                read_as(11, "Clause 4"),
2600                read_as(12, "Clause 5"),
2601                unread(13, NO_TRANSCRIPTION),
2602            ]
2603        );
2604        assert_eq!(read.data[1].text(), None, "an error wins over partial text");
2605        assert_eq!(read.data[0].text(), Some(""), "a blank page is a read");
2606        assert_eq!(read.data[2].page(), 9);
2607    }
2608
2609    #[test]
2610    fn an_answer_without_a_list_of_pages_has_no_pages() {
2611        for data in [
2612            json!(null),
2613            json!({}),
2614            json!({ "pages": "none" }),
2615            json!([]),
2616        ] {
2617            let _session =
2618                testing::install(move |_name, _params| Ok(json!({ "data": data.clone() })));
2619
2620            let read =
2621                transcribe_pages(&stored(), None, TranscribePagesOptions::default()).unwrap();
2622
2623            assert!(read.data.is_empty());
2624        }
2625    }
2626
2627    #[test]
2628    fn a_page_transcription_of_anything_but_a_pdf_is_refused_before_the_host_is_asked() {
2629        let session = testing::install(|_name, _params| Ok(json!({ "data": { "pages": [] } })));
2630
2631        let spreadsheet = transcribe_pages(
2632            &DocumentHandle {
2633                filename: "rates.csv".to_string(),
2634                mime_type: "text/csv".to_string(),
2635                ..stored()
2636            },
2637            None,
2638            TranscribePagesOptions::default(),
2639        )
2640        .unwrap_err();
2641
2642        let unstored = transcribe_pages(
2643            &DocumentHandle {
2644                file_hash: String::new(),
2645                ..stored()
2646            },
2647            None,
2648            TranscribePagesOptions::default(),
2649        )
2650        .unwrap_err();
2651
2652        for refusal in [&spreadsheet, &unstored] {
2653            assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
2654        }
2655
2656        assert!(spreadsheet.message().contains("reads the pages of a PDF"));
2657        assert!(session.calls().is_empty());
2658
2659        transcribe_pages(
2660            &DocumentHandle {
2661                mime_type: "Application/PDF; version=1.7".to_string(),
2662                ..stored()
2663            },
2664            None,
2665            TranscribePagesOptions::default(),
2666        )
2667        .expect("a PDF type with parameters or in capitals is still a PDF");
2668
2669        assert_eq!(session.calls().len(), 1);
2670    }
2671
2672    #[test]
2673    fn an_enrolment_answers_with_the_id_the_face_was_filed_under() {
2674        let session = testing::install(|name, params| {
2675            assert_eq!(name, FACE_ENROLL);
2676            assert_eq!(params["subject_id"], json!("EMP-42"));
2677            assert_eq!(params["image"], json!("iVBORw0KGgo"));
2678
2679            Ok(json!({ "face_id": "FACE-1" }))
2680        });
2681
2682        assert_eq!(
2683            enroll_face("EMP-42", json!("iVBORw0KGgo")).unwrap(),
2684            "FACE-1"
2685        );
2686        assert_eq!(session.calls().len(), 1);
2687    }
2688
2689    #[test]
2690    fn an_enrolment_uploads_a_pending_image_first() {
2691        let session = testing::install(|name, _params| {
2692            if name == UPLOAD_EPHEMERAL {
2693                return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
2694            }
2695
2696            Ok(json!({ "face_id": "FACE-1" }))
2697        });
2698
2699        enroll_face("EMP-42", json!({ "file_hash": "abc", "pending": true })).unwrap();
2700
2701        let calls = session.calls();
2702
2703        assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
2704        assert_eq!(
2705            calls[1].params["image"],
2706            json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" })
2707        );
2708    }
2709
2710    #[test]
2711    fn an_enrolment_without_a_subject_or_an_image_is_refused() {
2712        let session = testing::install(|_name, _params| Ok(json!({ "face_id": "FACE-1" })));
2713
2714        assert_eq!(
2715            enroll_face("  ", json!("image"))
2716                .unwrap_err()
2717                .code()
2718                .as_str(),
2719            "INVALID_TOOL_INPUT"
2720        );
2721        assert_eq!(
2722            enroll_face("EMP-42", json!(null))
2723                .unwrap_err()
2724                .code()
2725                .as_str(),
2726            "INVALID_TOOL_INPUT"
2727        );
2728        assert!(session.calls().is_empty());
2729    }
2730
2731    #[test]
2732    fn an_enrolment_that_answers_without_an_id_is_reported_rather_than_guessed_at() {
2733        let _session = testing::install(|_name, _params| Ok(json!({ "enrolled": true })));
2734
2735        let error = enroll_face("EMP-42", json!("image")).unwrap_err();
2736
2737        assert!(matches!(error, Error::Json(_)));
2738        assert_eq!(error.code().as_str(), "ACTION_FAILED");
2739    }
2740
2741    #[test]
2742    fn a_search_carries_only_the_narrowing_it_was_given() {
2743        let session = testing::install(|name, params| {
2744            assert_eq!(name, FACE_SEARCH);
2745
2746            Ok(json!({ "matches": params["options"].clone() }))
2747        });
2748
2749        let wide: Value = search_face(json!("image"), FaceSearch::default()).unwrap();
2750
2751        let narrow: Value = search_face(
2752            json!("image"),
2753            FaceSearch {
2754                max_faces: Some(3),
2755                similarity_threshold: Some(92.5),
2756            },
2757        )
2758        .unwrap();
2759
2760        assert_eq!(wide["matches"], json!({}), "the platform's own defaults");
2761        assert_eq!(
2762            narrow["matches"],
2763            json!({ "max_faces": 3, "similarity_threshold": 92.5 })
2764        );
2765        assert_eq!(session.calls().len(), 2);
2766    }
2767
2768    #[test]
2769    fn a_search_answers_with_the_type_the_call_asked_for() {
2770        #[derive(Debug, Deserialize, PartialEq)]
2771        struct Match {
2772            similarity: f64,
2773            subject_id: String,
2774        }
2775
2776        let _session = testing::install(|_name, _params| {
2777            Ok(json!([{ "similarity": 99.1, "subject_id": "EMP-42" }]))
2778        });
2779
2780        let found: Vec<Match> = search_face(json!("image"), FaceSearch::default()).unwrap();
2781
2782        assert_eq!(
2783            found,
2784            vec![Match {
2785                similarity: 99.1,
2786                subject_id: "EMP-42".to_string()
2787            }]
2788        );
2789    }
2790
2791    #[test]
2792    fn a_search_with_no_image_is_refused_before_anything_is_sent() {
2793        let session = testing::install(|_name, _params| Ok(json!([])));
2794
2795        let error = search_face::<Value>(json!(null), FaceSearch::default()).unwrap_err();
2796
2797        assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
2798        assert!(session.calls().is_empty());
2799    }
2800
2801    #[test]
2802    fn a_removal_reports_the_ids_the_platform_says_it_removed() {
2803        let session = testing::install(|name, params| {
2804            assert_eq!(name, FACE_DELETE);
2805            assert_eq!(params["face_ids"], json!(["FACE-1", "FACE-2"]));
2806
2807            Ok(json!({ "deleted": ["FACE-1"] }))
2808        });
2809
2810        let removed = delete_face(&["FACE-1".to_string(), "FACE-2".to_string()]).unwrap();
2811
2812        assert_eq!(removed, ["FACE-1"]);
2813        assert_eq!(session.calls().len(), 1);
2814    }
2815
2816    #[test]
2817    fn a_removal_reads_a_bare_list_of_ids_as_well() {
2818        let _session = testing::install(|_name, _params| Ok(json!(["FACE-1", "FACE-2"])));
2819
2820        assert_eq!(
2821            delete_face(&["FACE-1".to_string()]).unwrap(),
2822            ["FACE-1", "FACE-2"]
2823        );
2824    }
2825
2826    #[test]
2827    fn a_removal_that_names_nothing_removed_answers_with_nothing() {
2828        let _session = testing::install(|_name, _params| Ok(json!({ "ok": true })));
2829
2830        assert!(delete_face(&["FACE-1".to_string()]).unwrap().is_empty());
2831    }
2832
2833    #[test]
2834    fn a_removal_with_no_ids_is_refused_before_anything_is_sent() {
2835        let session = testing::install(|_name, _params| Ok(json!([])));
2836
2837        let error = delete_face(&[]).unwrap_err();
2838
2839        assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
2840        assert!(session.calls().is_empty());
2841    }
2842
2843    #[test]
2844    fn what_the_host_said_survives_into_every_failure() {
2845        let _session = testing::install(|_name, _params| Err(Error::failed("the engine is busy")));
2846
2847        let operation = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
2848        let enrolment = enroll_face("EMP-42", json!("image")).unwrap_err();
2849        let search = search_face::<Value>(json!("image"), FaceSearch::default()).unwrap_err();
2850        let removal = delete_face(&["FACE-1".to_string()]).unwrap_err();
2851
2852        for failure in [&operation, &enrolment, &search, &removal] {
2853            assert!(failure.message().contains("the engine is busy"));
2854            assert!(!failure.fault().hint().is_empty(), "and says what to do");
2855        }
2856    }
2857
2858    #[test]
2859    fn an_answer_that_does_not_fit_the_type_is_reported_as_having_run() {
2860        let _session = testing::install(|_name, _params| Ok(json!({ "data": { "total": 240.0 } })));
2861
2862        let error = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
2863
2864        assert!(matches!(error, Error::Json(_)));
2865        assert_eq!(error.code().as_str(), "ACTION_FAILED");
2866        assert!(error
2867            .fault()
2868            .hint()
2869            .contains("rather than running it again"));
2870    }
2871
2872    #[test]
2873    fn a_timeout_travels_as_the_milliseconds_the_wire_carries() {
2874        assert_eq!(milliseconds(Duration::from_secs(30)), 30_000);
2875        assert_eq!(milliseconds(Duration::from_millis(1)), 1);
2876        assert_eq!(milliseconds(Duration::MAX), u64::MAX);
2877    }
2878
2879    #[test]
2880    fn every_model_names_itself_as_the_wire_spells_it() {
2881        assert_eq!(Model::Lite.to_string(), "lite");
2882        assert_eq!(Model::Medium.to_string(), "medium");
2883        assert_eq!(Model::Large.to_string(), "large");
2884        assert_eq!(Model::Xl.to_string(), "xl");
2885    }
2886}