Skip to main content

simpleplatform_sdk/
ai.rs

1//! Asking the AI engine for an answer.
2//!
3//! Three operations read something and answer with it — [`extract`] pulls
4//! structured data out against a schema you give, [`summarize`] writes prose,
5//! and [`transcribe`] turns audio or video into words. Three more hold the
6//! tenant's face collection: [`enroll_face`], [`search_face`] and
7//! [`delete_face`].
8//!
9//! ```
10//! # use simpleplatform_sdk::prelude::*;
11//! # use simpleplatform_sdk::ai::{Execution, Options};
12//! # use simpleplatform_sdk::testing;
13//! #[derive(Deserialize)]
14//! struct Invoice {
15//!     number: String,
16//!     total: f64,
17//! }
18//!
19//! # let _session = testing::install(|_name, _params| {
20//! #     Ok(json!({
21//! #         "data": { "number": "INV-8", "total": 240.0 },
22//! #         "metadata": { "input_tokens": 812, "output_tokens": 24 }
23//! #     }))
24//! # });
25//! let schema = json!({
26//!     "type": "object",
27//!     "properties": {
28//!         "number": { "type": "string" },
29//!         "total": { "type": "number" }
30//!     },
31//!     "required": ["number", "total"]
32//! });
33//!
34//! let read: Execution<Invoice> = simple::ai::extract(
35//!     json!({ "file_hash": "9f2c…", "mime_type": "application/pdf" }),
36//!     "Read the invoice number and the total.",
37//!     schema,
38//!     Options::default(),
39//! )?;
40//!
41//! assert_eq!(read.data.number, "INV-8");
42//! assert_eq!(read.metadata.input_tokens, 812);
43//! # Ok::<(), Error>(())
44//! ```
45//!
46//! # The shape, and why it is this one
47//!
48//! **What an operation must have is an argument; what it may have is a field.**
49//! An input, a prompt and a schema are the operation — leave one out and there
50//! is nothing to run — so they are arguments, and the type system asks for them.
51//! Everything else has a working default, so it lives in [`Options`], which
52//! derives one:
53//!
54//! ```
55//! # use simpleplatform_sdk::ai::{Model, Options};
56//! # use std::time::Duration;
57//! let options = Options {
58//!     model: Some(Model::Large),
59//!     timeout: Some(Duration::from_secs(90)),
60//!     ..Default::default()
61//! };
62//! ```
63//!
64//! Nobody passes six `None`s, and a member added to [`Options`] later does not
65//! disturb a call that was written with `..Default::default()`.
66//!
67//! **The answer type is yours.** [`extract`] is generic over what it decodes
68//! into, exactly as [`crate::graphql::query`] is, so an extraction lands in your
69//! own struct rather than in a `Value` you then have to pick apart. Where the
70//! answer's shape is settled it is named for you instead: [`summarize`] answers
71//! with prose, and [`transcribe`] answers with a [`Transcript`], because this
72//! module wrote the schema that produced it.
73//!
74//! **Every answer carries what it cost.** An operation answers with an
75//! [`Execution`] — the data and the [`Metadata`] beside it — so token counts are
76//! there to record without a second call.
77//!
78//! # Files that have not been uploaded yet
79//!
80//! A document handle that is still pending is uploaded to ephemeral storage
81//! before the operation runs, and the operation is given the handle that upload
82//! answered with. A handle that is already stored is passed straight through,
83//! and so is a list of handles, item by item. Nothing in a call site changes:
84//! pass the handle you were given.
85
86use std::fmt;
87use std::time::Duration;
88
89use serde::de::DeserializeOwned;
90use serde::Deserialize;
91use serde_json::{json, Map, Value};
92
93use crate::codes::Code;
94use crate::error::{Error, Fault};
95use crate::host;
96
97/// The primitive that runs an AI operation.
98const ORCHESTRATOR: &str = "logic:dev.simple.system/ai-orchestrator";
99
100/// The host action that puts a pending file into ephemeral storage.
101const UPLOAD_EPHEMERAL: &str = "action:documents/upload-ephemeral";
102
103/// The host action that adds a face to the tenant's collection.
104const FACE_ENROLL: &str = "action:ai/face/enroll";
105
106/// The host action that searches the tenant's collection.
107const FACE_SEARCH: &str = "action:ai/face/search";
108
109/// The host action that removes faces from the tenant's collection.
110const FACE_DELETE: &str = "action:ai/face/delete";
111
112/// The size of model an operation runs on.
113///
114/// It is `#[non_exhaustive]`: a `match` on it needs a `_` arm, so a size added
115/// later does not break an action that was already written.
116#[non_exhaustive]
117#[derive(Clone, Copy, Debug, PartialEq, Eq)]
118pub enum Model {
119    /// The quickest and cheapest.
120    Lite,
121    /// The middle of the range.
122    Medium,
123    /// The one to reach for when the answer has to be right.
124    Large,
125    /// The largest available.
126    Xl,
127}
128
129impl Model {
130    /// The size exactly as it travels on the wire.
131    pub fn as_str(&self) -> &str {
132        match self {
133            Model::Lite => "lite",
134            Model::Medium => "medium",
135            Model::Large => "large",
136            Model::Xl => "xl",
137        }
138    }
139}
140
141impl fmt::Display for Model {
142    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
143        formatter.write_str(self.as_str())
144    }
145}
146
147/// What any operation may be told, beyond the inputs that define it.
148///
149/// Every member has a default, so a call that wants one thing changed says that
150/// thing and nothing else:
151///
152/// ```
153/// # use simpleplatform_sdk::ai::{Model, Options};
154/// let options = Options {
155///     model: Some(Model::Large),
156///     reasoning: false,
157///     ..Default::default()
158/// };
159/// ```
160#[derive(Clone, Debug)]
161pub struct Options {
162    /// Which size of model to run on. Unset leaves the choice to the platform.
163    pub model: Option<Model>,
164
165    /// The role, or the standing instruction, the model holds for the whole
166    /// task. Unset sends none.
167    pub system_prompt: Option<String>,
168
169    /// How far the model may range, from `0.0` for the most settled answer to
170    /// `1.0` for the most inventive. Unset leaves the model's own default.
171    pub temperature: Option<f64>,
172
173    /// Whether the model works the answer out step by step, and reports how.
174    /// On unless you turn it off.
175    pub reasoning: bool,
176
177    /// The most tokens the reasoning may spend. Unset leaves the platform's
178    /// default, and it is read only while `reasoning` is on.
179    pub reasoning_budget: Option<u32>,
180
181    /// Whether to do the work again rather than answer from a cached result for
182    /// the same input, prompt, schema, model and options.
183    pub regenerate: bool,
184
185    /// How long to wait for the answer. Unset leaves the platform's default.
186    pub timeout: Option<Duration>,
187}
188
189impl Default for Options {
190    /// Reasoning on, and every other choice left to the platform.
191    fn default() -> Options {
192        Options {
193            model: None,
194            system_prompt: None,
195            temperature: None,
196            reasoning: true,
197            reasoning_budget: None,
198            regenerate: false,
199            timeout: None,
200        }
201    }
202}
203
204/// Whether to tell the speakers apart, and what to call them.
205#[derive(Clone, Debug, Default, PartialEq, Eq)]
206pub enum Participants {
207    /// Do not tell the speakers apart.
208    #[default]
209    Ignore,
210
211    /// Tell the speakers apart, and label them `Participant 1`,
212    /// `Participant 2`, and so on.
213    Detect,
214
215    /// Tell the speakers apart under the names given. Naming nobody asks for
216    /// the same thing as [`Participants::Detect`].
217    Named(Vec<String>),
218}
219
220impl Participants {
221    /// Whether the speakers are to be told apart at all.
222    fn wanted(&self) -> bool {
223        !matches!(self, Participants::Ignore)
224    }
225
226    /// The names to identify, as one list, or nothing when none were given.
227    fn names(&self) -> Option<String> {
228        match self {
229            Participants::Named(names) if !names.is_empty() => Some(names.join(", ")),
230            _ => None,
231        }
232    }
233}
234
235/// What a transcription is to produce.
236///
237/// At least one of `include_transcript` and `summarize` has to be set, since
238/// between them they are the whole of what a transcription answers with.
239#[derive(Clone, Debug, Default)]
240pub struct TranscribeOptions {
241    /// Ask for the words that were said.
242    pub include_transcript: bool,
243
244    /// Ask for `[MM:SS]` stamps through the transcript. Read only while
245    /// `include_transcript` is set.
246    pub include_timestamps: bool,
247
248    /// Ask for a summary of what was said.
249    pub summarize: bool,
250
251    /// Whether to tell the speakers apart, and what to call them.
252    pub participants: Participants,
253}
254
255/// What a transcription answered with.
256///
257/// A member that was not asked for is empty, and every member survives an
258/// answer that leaves it out.
259#[derive(Clone, Debug, Default, Deserialize)]
260#[serde(default)]
261pub struct Transcript {
262    /// The language that was heard, as an ISO 639-1 code such as `en` or `es`.
263    pub language: String,
264
265    /// The words that were said, when they were asked for.
266    pub transcript: Option<String>,
267
268    /// The summary, when it was asked for.
269    pub summary: Option<String>,
270
271    /// The speakers that were told apart, when they were asked for.
272    pub participants: Vec<String>,
273}
274
275/// What an operation answered, and what it cost.
276#[derive(Clone, Debug)]
277pub struct Execution<T> {
278    /// The answer itself, decoded into the type the call asked for.
279    pub data: T,
280
281    /// What the run spent, and how it reasoned.
282    pub metadata: Metadata,
283}
284
285/// What a run spent, and how it reasoned.
286#[derive(Clone, Debug, Default, PartialEq, Eq)]
287pub struct Metadata {
288    /// Tokens in what was sent.
289    pub input_tokens: u64,
290
291    /// Tokens in what came back.
292    pub output_tokens: u64,
293
294    /// Tokens spent reasoning, when the run reported them.
295    pub reasoning_tokens: Option<u64>,
296
297    /// The reasoning itself, when the run reported it.
298    pub reasoning: Option<String>,
299}
300
301/// How far a face search reaches.
302#[derive(Clone, Debug, Default)]
303pub struct FaceSearch {
304    /// The most matches to answer with. Unset leaves the platform's default.
305    pub max_faces: Option<u32>,
306
307    /// The similarity a match has to reach, as a percentage from `0.0` to
308    /// `100.0`. Unset leaves the platform's default.
309    pub similarity_threshold: Option<f64>,
310}
311
312/// Read structured data out of an input, against a schema you give.
313///
314/// The schema is the contract the answer is held to, and the type parameter is
315/// what that answer is decoded into — so give the model the schema of the struct
316/// you want back.
317///
318/// ```
319/// # use simpleplatform_sdk::prelude::*;
320/// # use simpleplatform_sdk::ai::{Execution, Options};
321/// # use simpleplatform_sdk::testing;
322/// #[derive(Deserialize)]
323/// struct Sentiment {
324///     score: f64,
325/// }
326///
327/// # let _session = testing::install(|_name, _params| {
328/// #     Ok(json!({ "data": { "score": 0.8 }, "metadata": { "output_tokens": 6 } }))
329/// # });
330/// let schema = json!({
331///     "type": "object",
332///     "properties": { "score": { "type": "number" } },
333///     "required": ["score"]
334/// });
335///
336/// let read: Execution<Sentiment> = simple::ai::extract(
337///     json!("The delivery arrived early and intact."),
338///     "Score the sentiment from -1.0 to 1.0.",
339///     schema,
340///     Options::default(),
341/// )?;
342///
343/// assert_eq!(read.data.score, 0.8);
344/// # Ok::<(), Error>(())
345/// ```
346pub fn extract<T: DeserializeOwned>(
347    input: Value,
348    prompt: &str,
349    schema: Value,
350    options: Options,
351) -> Result<Execution<T>, Error> {
352    refuse_empty(
353        &input,
354        "extract needs something to read.",
355        "Pass the text, the document handle, or the object the extraction is to read.",
356    )?;
357    refuse_empty_prompt(prompt, "extract")?;
358
359    if !schema.is_object() {
360        return Err(
361            Error::invalid("extract needs a JSON Schema object describing the answer.").hint(
362                "Pass a schema object naming the type and the properties the answer is to have.",
363            ),
364        );
365    }
366
367    run("extract", input, prompt, Some(schema), &options)
368}
369
370/// Write prose about an input.
371///
372/// ```
373/// # use simpleplatform_sdk::prelude::*;
374/// # use simpleplatform_sdk::ai::Options;
375/// # use simpleplatform_sdk::testing;
376/// # let _session = testing::install(|_name, _params| {
377/// #     Ok(json!({ "data": "A refund was agreed.", "metadata": { "output_tokens": 5 } }))
378/// # });
379/// let written = simple::ai::summarize(
380///     json!({ "file_hash": "3a91…", "mime_type": "application/pdf" }),
381///     "Summarise what was agreed, in one sentence.",
382///     Options::default(),
383/// )?;
384///
385/// assert_eq!(written.data, "A refund was agreed.");
386/// # Ok::<(), Error>(())
387/// ```
388pub fn summarize(input: Value, prompt: &str, options: Options) -> Result<Execution<String>, Error> {
389    refuse_empty(
390        &input,
391        "summarize needs something to read.",
392        "Pass the text, the document handle, or the object the summary is to be written from.",
393    )?;
394    refuse_empty_prompt(prompt, "summarize")?;
395
396    run("summarize", input, prompt, None, &options)
397}
398
399/// Turn audio or video into words.
400///
401/// `document` is the handle of an uploaded audio or video file. The prompt and
402/// the schema are written here, from what `wanted` asks for, which is why the
403/// answer is a [`Transcript`] rather than a type you have to name.
404///
405/// ```
406/// # use simpleplatform_sdk::prelude::*;
407/// # use simpleplatform_sdk::ai::{Options, Participants, TranscribeOptions};
408/// # use simpleplatform_sdk::testing;
409/// # let _session = testing::install(|_name, _params| {
410/// #     Ok(json!({
411/// #         "data": {
412/// #             "language": "en",
413/// #             "transcript": "Customer: My order is late.\nAgent: I have refunded it.",
414/// #             "participants": ["Customer", "Agent"]
415/// #         },
416/// #         "metadata": { "input_tokens": 4_200, "output_tokens": 96 }
417/// #     }))
418/// # });
419/// let heard = simple::ai::transcribe(
420///     json!({ "file_hash": "c07b…", "mime_type": "audio/mpeg" }),
421///     TranscribeOptions {
422///         include_transcript: true,
423///         participants: Participants::Named(vec!["Customer".into(), "Agent".into()]),
424///         ..Default::default()
425///     },
426///     Options::default(),
427/// )?;
428///
429/// assert_eq!(heard.data.language, "en");
430/// assert_eq!(heard.data.participants, ["Customer", "Agent"]);
431/// # Ok::<(), Error>(())
432/// ```
433pub fn transcribe(
434    document: Value,
435    wanted: TranscribeOptions,
436    options: Options,
437) -> Result<Execution<Transcript>, Error> {
438    refuse_unless_media(&document)?;
439
440    if !wanted.include_transcript && !wanted.summarize {
441        return Err(
442            Error::invalid("transcribe needs to be told what to produce.")
443                .hint("Set include_transcript, summarize, or both."),
444        );
445    }
446
447    let prompt = transcribe_prompt(&wanted);
448
449    run(
450        "extract",
451        document,
452        &prompt,
453        Some(transcribe_schema(&wanted)),
454        &options,
455    )
456}
457
458/// Add a face to the tenant's collection, under the subject it belongs to.
459///
460/// `image` is either a base64 image or a document handle. The answer is the id
461/// of the enrolled face, which is what [`delete_face`] takes.
462///
463/// ```
464/// # use simpleplatform_sdk::prelude::*;
465/// # use simpleplatform_sdk::testing;
466/// # let _session = testing::install(|_name, _params| Ok(json!({ "face_id": "FACE-1" })));
467/// let face_id = simple::ai::enroll_face("EMP-42", json!("iVBORw0KGgo…"))?;
468///
469/// assert_eq!(face_id, "FACE-1");
470/// # Ok::<(), Error>(())
471/// ```
472pub fn enroll_face(subject_id: &str, image: Value) -> Result<String, Error> {
473    if subject_id.trim().is_empty() {
474        return Err(
475            Error::invalid("enroll_face needs the subject the face belongs to.")
476                .hint("Pass the id the face is to be found under, such as an employee or user id."),
477        );
478    }
479
480    refuse_empty(
481        &image,
482        "enroll_face needs an image of the face.",
483        "Pass a base64 image, or the handle of an uploaded one.",
484    )?;
485
486    let image = upload_pending(image)?;
487
488    let enrolled = host::transport()?
489        .call(
490            FACE_ENROLL.to_string(),
491            json!({ "image": image, "subject_id": subject_id }),
492        )
493        .map_err(|cause| {
494            cause.hint(
495                "Search the subject before enrolling the same face again, and report the failure.",
496            )
497        })?;
498
499    enrolled
500        .get("face_id")
501        .and_then(Value::as_str)
502        .map(str::to_string)
503        .ok_or_else(|| {
504            Error::Json(Fault::new(
505                Code::unspecified(),
506                "The enrolment answered without the id of the face it enrolled.",
507            ))
508            .hint("Search the subject to establish what was enrolled before enrolling again.")
509        })
510}
511
512/// Find the faces in the tenant's collection that match an image.
513///
514/// `image` is either a base64 image or a document handle. The matches are
515/// decoded into the type the call asks for; name your own to read them, or ask
516/// for a [`Value`] to keep them whole.
517///
518/// ```
519/// # use simpleplatform_sdk::prelude::*;
520/// # use simpleplatform_sdk::ai::FaceSearch;
521/// # use simpleplatform_sdk::testing;
522/// # let _session = testing::install(|_name, _params| Ok(json!([{ "subject_id": "EMP-42" }])));
523/// let found: Value = simple::ai::search_face(
524///     json!("iVBORw0KGgo…"),
525///     FaceSearch {
526///         max_faces: Some(3),
527///         similarity_threshold: Some(92.5),
528///     },
529/// )?;
530///
531/// assert_eq!(found[0]["subject_id"], json!("EMP-42"));
532/// # Ok::<(), Error>(())
533/// ```
534pub fn search_face<T: DeserializeOwned>(image: Value, options: FaceSearch) -> Result<T, Error> {
535    refuse_empty(
536        &image,
537        "search_face needs an image to search with.",
538        "Pass a base64 image, or the handle of an uploaded one.",
539    )?;
540
541    let image = upload_pending(image)?;
542
543    let mut narrowing = Map::new();
544
545    if let Some(max_faces) = options.max_faces {
546        narrowing.insert("max_faces".to_string(), Value::from(max_faces));
547    }
548
549    if let Some(threshold) = options
550        .similarity_threshold
551        .filter(|value| value.is_finite())
552    {
553        narrowing.insert("similarity_threshold".to_string(), Value::from(threshold));
554    }
555
556    let found = host::transport()?
557        .call(
558            FACE_SEARCH.to_string(),
559            json!({ "image": image, "options": narrowing }),
560        )
561        .map_err(|cause| {
562            cause.hint("Nothing in the collection was changed. Report the search failure.")
563        })?;
564
565    serde_json::from_value(found).map_err(|cause| {
566        Error::Json(Fault::new(
567            Code::unspecified(),
568            format!("The matches could not be read into the type this action asked for: {cause}"),
569        ))
570        .hint("Read the matches as a Value, or name a type that matches what the search answers.")
571    })
572}
573
574/// Remove faces from the tenant's collection, by the ids they were enrolled
575/// under.
576///
577/// The answer is the ids the platform reports as removed.
578///
579/// ```
580/// # use simpleplatform_sdk::prelude::*;
581/// # use simpleplatform_sdk::testing;
582/// # let _session = testing::install(|_name, _params| Ok(json!({ "deleted": ["FACE-1"] })));
583/// let removed = simple::ai::delete_face(&["FACE-1".to_string()])?;
584///
585/// assert_eq!(removed, ["FACE-1"]);
586/// # Ok::<(), Error>(())
587/// ```
588pub fn delete_face(face_ids: &[String]) -> Result<Vec<String>, Error> {
589    if face_ids.is_empty() {
590        return Err(Error::invalid("delete_face needs at least one face id.")
591            .hint("Pass the ids enroll_face answered with."));
592    }
593
594    let removed = host::transport()?
595        .call(FACE_DELETE.to_string(), json!({ "face_ids": face_ids }))
596        .map_err(|cause| {
597            cause.hint(
598                "Treat the removal as unfinished: search the collection to establish what is \
599                 still in it before deleting again.",
600            )
601        })?;
602
603    let listed = match &removed {
604        Value::Array(ids) => Some(ids),
605        other => other.get("deleted").and_then(Value::as_array),
606    };
607
608    Ok(listed
609        .map(|ids| {
610            ids.iter()
611                .filter_map(Value::as_str)
612                .map(str::to_string)
613                .collect()
614        })
615        .unwrap_or_default())
616}
617
618/// One operation: upload what is pending, ask the primitive, read the answer.
619fn run<T: DeserializeOwned>(
620    operation: &str,
621    input: Value,
622    prompt: &str,
623    schema: Option<Value>,
624    options: &Options,
625) -> Result<Execution<T>, Error> {
626    let input = upload_pending(input)?;
627
628    let answered = host::transport()?
629        .call(
630            ORCHESTRATOR.to_string(),
631            payload(operation, input, prompt, schema, options),
632        )
633        .map_err(|cause| {
634            cause.hint(
635                "No tenant record was changed. Review the input, the prompt and the schema, \
636                 and report the failure.",
637            )
638        })?;
639
640    // The metadata is read on its own and never decides the outcome, so a run
641    // that answered is reported as one whatever it said about its own cost.
642    let metadata = metadata_of(answered.get("metadata"));
643    let data = answered.get("data").cloned().unwrap_or(Value::Null);
644
645    let data = serde_json::from_value(data).map_err(|cause| {
646        Error::Json(Fault::new(
647            Code::unspecified(),
648            format!("The {operation} answer could not be read into the type this action asked for: {cause}"),
649        ))
650        .hint(
651            "The operation ran. Read the answer as a Value, or name a type that matches the \
652             schema, rather than running it again.",
653        )
654    })?;
655
656    Ok(Execution { data, metadata })
657}
658
659/// Everything the primitive is told about one operation.
660///
661/// A choice that was not made is left out, so what arrives is what the call
662/// asked for and the platform's own defaults fill the rest.
663fn payload(
664    operation: &str,
665    input: Value,
666    prompt: &str,
667    schema: Option<Value>,
668    options: &Options,
669) -> Value {
670    // The engine reads `reasoning` and `reasoning_budget` from here, and the
671    // whole map is part of the key a cached result is found under.
672    let mut universal = Map::new();
673
674    universal.insert("reasoning".to_string(), Value::Bool(options.reasoning));
675
676    if let Some(budget) = options.reasoning_budget {
677        universal.insert("reasoning_budget".to_string(), Value::from(budget));
678    }
679
680    if let Some(temperature) = options.temperature.filter(|value| value.is_finite()) {
681        universal.insert("temperature".to_string(), Value::from(temperature));
682    }
683
684    let mut payload = Map::new();
685
686    payload.insert("operation".to_string(), Value::from(operation));
687    payload.insert("input".to_string(), input);
688    payload.insert("prompt".to_string(), Value::from(prompt));
689    payload.insert("options".to_string(), Value::Object(universal));
690    payload.insert("regenerate".to_string(), Value::Bool(options.regenerate));
691
692    if let Some(schema) = schema {
693        payload.insert("schema".to_string(), schema);
694    }
695
696    if let Some(model) = options.model {
697        payload.insert("model".to_string(), Value::from(model.as_str()));
698    }
699
700    if let Some(system_prompt) = &options.system_prompt {
701        payload.insert(
702            "systemPrompt".to_string(),
703            Value::from(system_prompt.as_str()),
704        );
705    }
706
707    if let Some(timeout) = options.timeout {
708        payload.insert("timeout".to_string(), Value::from(milliseconds(timeout)));
709    }
710
711    Value::Object(payload)
712}
713
714/// A duration as the milliseconds the wire carries.
715fn milliseconds(timeout: Duration) -> u64 {
716    u64::try_from(timeout.as_millis()).unwrap_or(u64::MAX)
717}
718
719/// What a run reported about itself.
720fn metadata_of(metadata: Option<&Value>) -> Metadata {
721    let Some(metadata) = metadata else {
722        return Metadata::default();
723    };
724
725    Metadata {
726        input_tokens: count(metadata, "input_tokens").unwrap_or(0),
727        output_tokens: count(metadata, "output_tokens").unwrap_or(0),
728        reasoning_tokens: count(metadata, "reasoning_tokens"),
729        reasoning: metadata
730            .get("reasoning")
731            .and_then(Value::as_str)
732            .map(str::to_string),
733    }
734}
735
736/// One token count, when it is there and is a count.
737fn count(metadata: &Value, key: &str) -> Option<u64> {
738    metadata.get(key).and_then(Value::as_u64)
739}
740
741/// Put whatever is still pending into ephemeral storage, and answer with what
742/// the operation is to be given instead.
743///
744/// A handle that is already stored, and anything that is not a handle at all,
745/// comes back as it went in.
746fn upload_pending(value: Value) -> Result<Value, Error> {
747    if is_pending(&value) {
748        return host::transport()?
749            .call(UPLOAD_EPHEMERAL.to_string(), value)
750            .map_err(|cause| {
751                cause.hint(
752                    "The file was not uploaded and the operation did not run. Upload the file, \
753                     then pass the handle that upload answered with.",
754                )
755            });
756    }
757
758    if let Value::Array(items) = value {
759        let mut uploaded = Vec::with_capacity(items.len());
760
761        for item in items {
762            uploaded.push(upload_pending(item)?);
763        }
764
765        return Ok(Value::Array(uploaded));
766    }
767
768    Ok(value)
769}
770
771/// Whether this is a document handle whose file is still to be uploaded.
772///
773/// It is one when it says it is pending and carries the hash of the file it
774/// stands for, since that hash is what the upload is asked for by.
775fn is_pending(value: &Value) -> bool {
776    value.get("pending").and_then(Value::as_bool) == Some(true) && has_file_hash(value)
777}
778
779/// Whether this carries the hash of a file.
780fn has_file_hash(value: &Value) -> bool {
781    value
782        .get("file_hash")
783        .and_then(Value::as_str)
784        .is_some_and(|hash| !hash.is_empty())
785}
786
787/// Refuse a value that names nothing, in the words of whoever needed it.
788fn refuse_empty(value: &Value, message: &str, hint: &str) -> Result<(), Error> {
789    let empty = match value {
790        Value::Null => true,
791        Value::String(text) => text.is_empty(),
792        _ => false,
793    };
794
795    if empty {
796        return Err(Error::invalid(message).hint(hint));
797    }
798
799    Ok(())
800}
801
802/// Refuse an operation that has been given nothing to do.
803fn refuse_empty_prompt(prompt: &str, operation: &str) -> Result<(), Error> {
804    if prompt.trim().is_empty() {
805        return Err(Error::invalid(format!("{operation} needs a prompt."))
806            .hint("Say what the operation is to produce, in a sentence the model can act on."));
807    }
808
809    Ok(())
810}
811
812/// Refuse anything that is not the handle of an audio or video file.
813fn refuse_unless_media(document: &Value) -> Result<(), Error> {
814    if !has_file_hash(document) {
815        return Err(
816            Error::invalid("transcribe needs a document handle to work on.").hint(
817                "Pass the handle of the uploaded file, the one carrying file_hash and mime_type.",
818            ),
819        );
820    }
821
822    let media = document
823        .get("mime_type")
824        .and_then(Value::as_str)
825        .map(str::to_lowercase)
826        .is_some_and(|mime| mime.starts_with("audio/") || mime.starts_with("video/"));
827
828    if !media {
829        return Err(Error::invalid("transcribe works on audio and video.")
830            .hint("Pass a handle whose mime_type begins audio/ or video/."));
831    }
832
833    Ok(())
834}
835
836/// The schema a transcription is held to, written from what was asked for.
837fn transcribe_schema(wanted: &TranscribeOptions) -> Value {
838    let identify = wanted.participants.wanted();
839
840    let mut properties = Map::new();
841    let mut required = vec![Value::from("language")];
842
843    properties.insert(
844        "language".to_string(),
845        json!({
846            "description": "The detected language of the audio (ISO 639-1 code, e.g., \"en\", \"es\")",
847            "type": "string"
848        }),
849    );
850
851    if wanted.include_transcript {
852        let description = match (identify, wanted.include_timestamps) {
853            (true, true) => {
854                "The full transcript with participant labels and timestamps. \
855                 Format: [MM:SS] Participant Name: text"
856            }
857            (true, false) => {
858                "The full transcript with participant labels. Format: Participant Name: text"
859            }
860            (false, true) => "The full transcript with timestamps. Format: [MM:SS] text",
861            (false, false) => "The full transcript of the audio",
862        };
863
864        properties.insert(
865            "transcript".to_string(),
866            json!({ "description": description, "type": "string" }),
867        );
868        required.push(Value::from("transcript"));
869    }
870
871    if wanted.summarize {
872        let description = if identify {
873            "A concise summary of the audio content, including key points from each participant"
874        } else {
875            "A concise summary of the audio content"
876        };
877
878        properties.insert(
879            "summary".to_string(),
880            json!({ "description": description, "type": "string" }),
881        );
882        required.push(Value::from("summary"));
883    }
884
885    if identify {
886        properties.insert(
887            "participants".to_string(),
888            json!({
889                "description": "List of identified participants in the audio",
890                "items": { "type": "string" },
891                "type": "array"
892            }),
893        );
894        required.push(Value::from("participants"));
895    }
896
897    json!({ "properties": properties, "required": required, "type": "object" })
898}
899
900/// The prompt a transcription runs on, written from what was asked for.
901fn transcribe_prompt(wanted: &TranscribeOptions) -> String {
902    let identify = wanted.participants.wanted();
903    let names = wanted.participants.names();
904
905    let mut prompt = String::from("Analyze this audio/video file and provide:\n");
906
907    if wanted.include_transcript {
908        if identify {
909            match &names {
910                Some(names) => {
911                    prompt.push_str("- A complete transcript identifying these participants: ");
912                    prompt.push_str(names);
913                    prompt.push_str(". ");
914                }
915                None => prompt.push_str(
916                    "- A complete transcript with participant identification \
917                     (label participants as Participant 1, Participant 2, etc.). ",
918                ),
919            }
920
921            if wanted.include_timestamps {
922                prompt.push_str(
923                    "Include timestamps in [MM:SS] format before each participant segment.\n",
924                );
925            } else {
926                prompt.push_str("Format each line as \"Participant Name: text\".\n");
927            }
928        } else if wanted.include_timestamps {
929            prompt.push_str(
930                "- A complete transcript with timestamps in [MM:SS] format before each segment\n",
931            );
932        } else {
933            prompt.push_str("- A complete transcript of all spoken content\n");
934        }
935    }
936
937    if wanted.summarize {
938        if identify {
939            prompt.push_str("- A concise summary highlighting key points from each participant\n");
940        } else {
941            prompt.push_str("- A concise summary of the main points and key information\n");
942        }
943    }
944
945    if identify {
946        match &names {
947            Some(names) => {
948                prompt.push_str("- Identify and distinguish between these participants: ");
949                prompt.push_str(names);
950                prompt.push('\n');
951            }
952            None => prompt.push_str("- Identify and list all distinct participants in the audio\n"),
953        }
954    }
955
956    prompt.push_str("- The detected language code (ISO 639-1 format)\n");
957
958    prompt
959}
960
961#[cfg(test)]
962mod tests {
963    use serde_json::json;
964
965    use super::*;
966    use crate::testing;
967
968    /// What the primitive answers when a test does not care what came back.
969    fn answered() -> Value {
970        json!({ "data": { "ok": true }, "metadata": { "input_tokens": 1, "output_tokens": 2 } })
971    }
972
973    #[test]
974    fn an_extraction_asks_the_primitive_and_answers_with_the_type_it_was_asked_for() {
975        #[derive(Debug, Deserialize, PartialEq)]
976        struct Invoice {
977            number: String,
978            total: f64,
979        }
980
981        let session = testing::install(|name, params| {
982            assert_eq!(name, ORCHESTRATOR);
983            assert_eq!(params["operation"], json!("extract"));
984            assert_eq!(params["prompt"], json!("Read it."));
985            assert_eq!(params["input"], json!("INV-8, 240.00"));
986            assert_eq!(params["schema"]["type"], json!("object"));
987
988            Ok(json!({
989                "data": { "number": "INV-8", "total": 240.0 },
990                "metadata": { "input_tokens": 11, "output_tokens": 3 }
991            }))
992        });
993
994        let read: Execution<Invoice> = extract(
995            json!("INV-8, 240.00"),
996            "Read it.",
997            json!({ "type": "object" }),
998            Options::default(),
999        )
1000        .unwrap();
1001
1002        assert_eq!(
1003            read.data,
1004            Invoice {
1005                number: "INV-8".to_string(),
1006                total: 240.0
1007            }
1008        );
1009        assert_eq!(read.metadata.input_tokens, 11);
1010        assert_eq!(read.metadata.output_tokens, 3);
1011        assert_eq!(session.calls().len(), 1);
1012    }
1013
1014    #[test]
1015    fn a_default_call_reasons_does_not_regenerate_and_leaves_the_rest_to_the_platform() {
1016        let session = testing::install(|_name, _params| Ok(answered()));
1017
1018        let _: Execution<Value> = extract(
1019            json!("text"),
1020            "Read it.",
1021            json!({ "type": "object" }),
1022            Options::default(),
1023        )
1024        .unwrap();
1025
1026        let sent = session.calls()[0].params.clone();
1027
1028        assert_eq!(sent["options"], json!({ "reasoning": true }));
1029        assert_eq!(sent["regenerate"], json!(false));
1030        assert!(sent.get("model").is_none());
1031        assert!(sent.get("systemPrompt").is_none());
1032        assert!(sent.get("timeout").is_none());
1033    }
1034
1035    #[test]
1036    fn every_option_that_was_set_travels_with_the_operation() {
1037        let session = testing::install(|_name, _params| Ok(answered()));
1038
1039        let _: Execution<Value> = extract(
1040            json!("text"),
1041            "Read it.",
1042            json!({ "type": "object" }),
1043            Options {
1044                model: Some(Model::Xl),
1045                system_prompt: Some("You are an auditor.".to_string()),
1046                temperature: Some(0.25),
1047                reasoning: false,
1048                reasoning_budget: Some(2_048),
1049                regenerate: true,
1050                timeout: Some(Duration::from_secs(90)),
1051            },
1052        )
1053        .unwrap();
1054
1055        let sent = session.calls()[0].params.clone();
1056
1057        assert_eq!(sent["model"], json!("xl"));
1058        assert_eq!(sent["systemPrompt"], json!("You are an auditor."));
1059        assert_eq!(sent["regenerate"], json!(true));
1060        assert_eq!(sent["timeout"], json!(90_000));
1061        assert_eq!(
1062            sent["options"],
1063            json!({ "reasoning": false, "reasoning_budget": 2_048, "temperature": 0.25 })
1064        );
1065    }
1066
1067    #[test]
1068    fn a_summary_answers_with_the_prose_and_carries_no_schema() {
1069        let session = testing::install(|_name, params| {
1070            assert_eq!(params["operation"], json!("summarize"));
1071            assert!(params.get("schema").is_none());
1072
1073            Ok(json!({ "data": "A refund was agreed.", "metadata": { "output_tokens": 5 } }))
1074        });
1075
1076        let written = summarize(json!("A long thread."), "One sentence.", Options::default())
1077            .expect("a summary answers with prose");
1078
1079        assert_eq!(written.data, "A refund was agreed.");
1080        assert_eq!(written.metadata.output_tokens, 5);
1081        assert_eq!(session.calls().len(), 1);
1082    }
1083
1084    #[test]
1085    fn a_pending_document_is_uploaded_before_the_operation_reads_it() {
1086        let session = testing::install(|name, _params| {
1087            if name == UPLOAD_EPHEMERAL {
1088                return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
1089            }
1090
1091            Ok(answered())
1092        });
1093
1094        let _: Execution<Value> = extract(
1095            json!({ "file_hash": "abc", "pending": true }),
1096            "Read it.",
1097            json!({ "type": "object" }),
1098            Options::default(),
1099        )
1100        .unwrap();
1101
1102        let calls = session.calls();
1103
1104        assert_eq!(calls.len(), 2);
1105        assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
1106        assert_eq!(calls[1].name, ORCHESTRATOR);
1107        assert_eq!(
1108            calls[1].params["input"],
1109            json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }),
1110            "the operation reads the handle the upload answered with"
1111        );
1112    }
1113
1114    #[test]
1115    fn a_document_that_is_already_stored_is_read_where_it_is() {
1116        let session = testing::install(|_name, _params| Ok(answered()));
1117
1118        let handle = json!({ "file_hash": "abc", "mime_type": "application/pdf" });
1119
1120        let _: Execution<Value> = extract(
1121            handle.clone(),
1122            "Read it.",
1123            json!({ "type": "object" }),
1124            Options::default(),
1125        )
1126        .unwrap();
1127
1128        let calls = session.calls();
1129
1130        assert_eq!(calls.len(), 1, "nothing was uploaded");
1131        assert_eq!(calls[0].params["input"], handle);
1132    }
1133
1134    #[test]
1135    fn a_list_of_documents_is_uploaded_item_by_item() {
1136        let session = testing::install(|name, params| {
1137            if name == UPLOAD_EPHEMERAL {
1138                return Ok(json!({ "stored": params["file_hash"] }));
1139            }
1140
1141            Ok(answered())
1142        });
1143
1144        let _: Execution<Value> = extract(
1145            json!([
1146                { "file_hash": "one", "pending": true },
1147                { "file_hash": "two", "mime_type": "image/png" },
1148                { "file_hash": "three", "pending": true }
1149            ]),
1150            "Read them.",
1151            json!({ "type": "object" }),
1152            Options::default(),
1153        )
1154        .unwrap();
1155
1156        let calls = session.calls();
1157
1158        assert_eq!(calls.len(), 3, "two uploads and the operation");
1159        assert_eq!(
1160            calls[2].params["input"],
1161            json!([
1162                { "stored": "one" },
1163                { "file_hash": "two", "mime_type": "image/png" },
1164                { "stored": "three" }
1165            ])
1166        );
1167    }
1168
1169    #[test]
1170    fn a_handle_is_pending_only_while_it_says_so_and_carries_a_hash_to_upload_by() {
1171        assert!(is_pending(&json!({ "file_hash": "abc", "pending": true })));
1172        assert!(!is_pending(&json!({ "file_hash": "abc" })));
1173        assert!(!is_pending(&json!({ "pending": true })));
1174        assert!(!is_pending(&json!({ "file_hash": "", "pending": true })));
1175        assert!(!is_pending(
1176            &json!({ "file_hash": "abc", "pending": "yes" })
1177        ));
1178        assert!(!is_pending(&json!("some words")));
1179        assert!(!is_pending(&json!([
1180            { "file_hash": "abc", "pending": true }
1181        ])));
1182    }
1183
1184    #[test]
1185    fn an_answer_that_reports_nothing_about_its_cost_is_still_an_answer() {
1186        let _session = testing::install(|_name, _params| Ok(json!({ "data": "done" })));
1187
1188        let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
1189
1190        assert_eq!(written.data, "done");
1191        assert_eq!(written.metadata, Metadata::default());
1192    }
1193
1194    #[test]
1195    fn reasoning_reaches_the_caller_when_the_run_reported_it() {
1196        let _session = testing::install(|_name, _params| {
1197            Ok(json!({
1198                "data": "done",
1199                "metadata": {
1200                    "input_tokens": 9,
1201                    "output_tokens": 4,
1202                    "reasoning": "Read the total from the last line.",
1203                    "reasoning_tokens": 120
1204                }
1205            }))
1206        });
1207
1208        let written = summarize(json!("text"), "One sentence.", Options::default()).unwrap();
1209
1210        assert_eq!(written.metadata.reasoning_tokens, Some(120));
1211        assert_eq!(
1212            written.metadata.reasoning.as_deref(),
1213            Some("Read the total from the last line.")
1214        );
1215    }
1216
1217    #[test]
1218    fn an_operation_with_nothing_to_do_is_refused_before_anything_is_sent() {
1219        let session = testing::install(|_name, _params| Ok(answered()));
1220
1221        let missing_input = extract::<Value>(
1222            json!(null),
1223            "Read it.",
1224            json!({ "type": "object" }),
1225            Options::default(),
1226        )
1227        .unwrap_err();
1228
1229        let missing_prompt = extract::<Value>(
1230            json!("text"),
1231            "   ",
1232            json!({ "type": "object" }),
1233            Options::default(),
1234        )
1235        .unwrap_err();
1236
1237        let missing_schema =
1238            extract::<Value>(json!("text"), "Read it.", json!([]), Options::default()).unwrap_err();
1239
1240        let missing_summary_input =
1241            summarize(json!(""), "One sentence.", Options::default()).unwrap_err();
1242
1243        for refusal in [
1244            &missing_input,
1245            &missing_prompt,
1246            &missing_schema,
1247            &missing_summary_input,
1248        ] {
1249            assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
1250        }
1251
1252        assert!(session.calls().is_empty());
1253    }
1254
1255    #[test]
1256    fn a_transcription_writes_its_own_schema_and_prompt() {
1257        let session = testing::install(|_name, _params| {
1258            Ok(json!({
1259                "data": { "language": "en", "transcript": "Hello." },
1260                "metadata": { "input_tokens": 400, "output_tokens": 12 }
1261            }))
1262        });
1263
1264        let heard = transcribe(
1265            json!({ "file_hash": "abc", "mime_type": "AUDIO/MPEG" }),
1266            TranscribeOptions {
1267                include_transcript: true,
1268                ..Default::default()
1269            },
1270            Options::default(),
1271        )
1272        .expect("an uppercase mime type is the same mime type");
1273
1274        assert_eq!(heard.data.language, "en");
1275        assert_eq!(heard.data.transcript.as_deref(), Some("Hello."));
1276        assert_eq!(heard.data.summary, None);
1277        assert!(heard.data.participants.is_empty());
1278
1279        let sent = session.calls()[0].params.clone();
1280
1281        assert_eq!(sent["operation"], json!("extract"));
1282        assert_eq!(
1283            sent["schema"]["required"],
1284            json!(["language", "transcript"])
1285        );
1286        assert_eq!(sent["schema"]["properties"]["transcript"]["type"], "string");
1287        assert_eq!(
1288            sent["prompt"],
1289            json!(
1290                "Analyze this audio/video file and provide:\n\
1291                 - A complete transcript of all spoken content\n\
1292                 - The detected language code (ISO 639-1 format)\n"
1293            )
1294        );
1295    }
1296
1297    #[test]
1298    fn named_participants_reach_both_the_prompt_and_the_schema() {
1299        let session = testing::install(|_name, _params| {
1300            Ok(json!({ "data": { "language": "en", "participants": ["Customer", "Agent"] } }))
1301        });
1302
1303        let heard = transcribe(
1304            json!({ "file_hash": "abc", "mime_type": "video/mp4" }),
1305            TranscribeOptions {
1306                include_transcript: true,
1307                include_timestamps: true,
1308                summarize: true,
1309                participants: Participants::Named(vec![
1310                    "Customer".to_string(),
1311                    "Agent".to_string(),
1312                ]),
1313            },
1314            Options::default(),
1315        )
1316        .unwrap();
1317
1318        assert_eq!(heard.data.participants, ["Customer", "Agent"]);
1319
1320        let sent = session.calls()[0].params.clone();
1321        let prompt = sent["prompt"].as_str().unwrap_or_default().to_string();
1322
1323        assert_eq!(
1324            sent["schema"]["required"],
1325            json!(["language", "transcript", "summary", "participants"])
1326        );
1327        assert_eq!(
1328            sent["schema"]["properties"]["participants"]["items"]["type"],
1329            json!("string")
1330        );
1331        assert!(prompt.contains("identifying these participants: Customer, Agent. "));
1332        assert!(prompt.contains("Include timestamps in [MM:SS] format"));
1333        assert!(
1334            prompt.contains("- A concise summary highlighting key points from each participant\n")
1335        );
1336        assert!(prompt
1337            .contains("- Identify and distinguish between these participants: Customer, Agent\n"));
1338    }
1339
1340    #[test]
1341    fn detected_participants_are_labelled_rather_than_named() {
1342        let session =
1343            testing::install(|_name, _params| Ok(json!({ "data": { "language": "en" } })));
1344
1345        let _ = transcribe(
1346            json!({ "file_hash": "abc", "mime_type": "audio/wav" }),
1347            TranscribeOptions {
1348                include_transcript: true,
1349                participants: Participants::Detect,
1350                ..Default::default()
1351            },
1352            Options::default(),
1353        )
1354        .unwrap();
1355
1356        let prompt = session.calls()[0].params["prompt"]
1357            .as_str()
1358            .unwrap_or_default()
1359            .to_string();
1360
1361        assert!(prompt.contains("label participants as Participant 1, Participant 2, etc."));
1362        assert!(prompt.contains("Format each line as \"Participant Name: text\".\n"));
1363        assert!(prompt.contains("- Identify and list all distinct participants in the audio\n"));
1364    }
1365
1366    #[test]
1367    fn naming_nobody_asks_for_the_same_thing_as_detecting() {
1368        let wanted = |participants| TranscribeOptions {
1369            include_transcript: true,
1370            participants,
1371            ..Default::default()
1372        };
1373
1374        assert_eq!(
1375            transcribe_prompt(&wanted(Participants::Named(Vec::new()))),
1376            transcribe_prompt(&wanted(Participants::Detect))
1377        );
1378        assert_eq!(
1379            transcribe_schema(&wanted(Participants::Named(Vec::new()))),
1380            transcribe_schema(&wanted(Participants::Detect))
1381        );
1382    }
1383
1384    #[test]
1385    fn a_transcription_that_cannot_run_is_refused_before_anything_is_sent() {
1386        let session = testing::install(|_name, _params| Ok(answered()));
1387
1388        let audio = json!({ "file_hash": "abc", "mime_type": "audio/mpeg" });
1389
1390        let nothing_wanted = transcribe(
1391            audio.clone(),
1392            TranscribeOptions::default(),
1393            Options::default(),
1394        )
1395        .unwrap_err();
1396
1397        let not_media = transcribe(
1398            json!({ "file_hash": "abc", "mime_type": "application/pdf" }),
1399            TranscribeOptions {
1400                include_transcript: true,
1401                ..Default::default()
1402            },
1403            Options::default(),
1404        )
1405        .unwrap_err();
1406
1407        let not_a_handle = transcribe(
1408            json!("some words"),
1409            TranscribeOptions {
1410                summarize: true,
1411                ..Default::default()
1412            },
1413            Options::default(),
1414        )
1415        .unwrap_err();
1416
1417        for refusal in [&nothing_wanted, &not_media, &not_a_handle] {
1418            assert_eq!(refusal.code().as_str(), "INVALID_TOOL_INPUT");
1419        }
1420
1421        assert!(session.calls().is_empty());
1422    }
1423
1424    #[test]
1425    fn an_enrolment_answers_with_the_id_the_face_was_filed_under() {
1426        let session = testing::install(|name, params| {
1427            assert_eq!(name, FACE_ENROLL);
1428            assert_eq!(params["subject_id"], json!("EMP-42"));
1429            assert_eq!(params["image"], json!("iVBORw0KGgo"));
1430
1431            Ok(json!({ "face_id": "FACE-1" }))
1432        });
1433
1434        assert_eq!(
1435            enroll_face("EMP-42", json!("iVBORw0KGgo")).unwrap(),
1436            "FACE-1"
1437        );
1438        assert_eq!(session.calls().len(), 1);
1439    }
1440
1441    #[test]
1442    fn an_enrolment_uploads_a_pending_image_first() {
1443        let session = testing::install(|name, _params| {
1444            if name == UPLOAD_EPHEMERAL {
1445                return Ok(json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" }));
1446            }
1447
1448            Ok(json!({ "face_id": "FACE-1" }))
1449        });
1450
1451        enroll_face("EMP-42", json!({ "file_hash": "abc", "pending": true })).unwrap();
1452
1453        let calls = session.calls();
1454
1455        assert_eq!(calls[0].name, UPLOAD_EPHEMERAL);
1456        assert_eq!(
1457            calls[1].params["image"],
1458            json!({ "file_hash": "abc", "storage_path": "ephemeral/abc" })
1459        );
1460    }
1461
1462    #[test]
1463    fn an_enrolment_without_a_subject_or_an_image_is_refused() {
1464        let session = testing::install(|_name, _params| Ok(json!({ "face_id": "FACE-1" })));
1465
1466        assert_eq!(
1467            enroll_face("  ", json!("image"))
1468                .unwrap_err()
1469                .code()
1470                .as_str(),
1471            "INVALID_TOOL_INPUT"
1472        );
1473        assert_eq!(
1474            enroll_face("EMP-42", json!(null))
1475                .unwrap_err()
1476                .code()
1477                .as_str(),
1478            "INVALID_TOOL_INPUT"
1479        );
1480        assert!(session.calls().is_empty());
1481    }
1482
1483    #[test]
1484    fn an_enrolment_that_answers_without_an_id_is_reported_rather_than_guessed_at() {
1485        let _session = testing::install(|_name, _params| Ok(json!({ "enrolled": true })));
1486
1487        let error = enroll_face("EMP-42", json!("image")).unwrap_err();
1488
1489        assert!(matches!(error, Error::Json(_)));
1490        assert_eq!(error.code().as_str(), "ACTION_FAILED");
1491    }
1492
1493    #[test]
1494    fn a_search_carries_only_the_narrowing_it_was_given() {
1495        let session = testing::install(|name, params| {
1496            assert_eq!(name, FACE_SEARCH);
1497
1498            Ok(json!({ "matches": params["options"].clone() }))
1499        });
1500
1501        let wide: Value = search_face(json!("image"), FaceSearch::default()).unwrap();
1502
1503        let narrow: Value = search_face(
1504            json!("image"),
1505            FaceSearch {
1506                max_faces: Some(3),
1507                similarity_threshold: Some(92.5),
1508            },
1509        )
1510        .unwrap();
1511
1512        assert_eq!(wide["matches"], json!({}), "the platform's own defaults");
1513        assert_eq!(
1514            narrow["matches"],
1515            json!({ "max_faces": 3, "similarity_threshold": 92.5 })
1516        );
1517        assert_eq!(session.calls().len(), 2);
1518    }
1519
1520    #[test]
1521    fn a_search_answers_with_the_type_the_call_asked_for() {
1522        #[derive(Debug, Deserialize, PartialEq)]
1523        struct Match {
1524            similarity: f64,
1525            subject_id: String,
1526        }
1527
1528        let _session = testing::install(|_name, _params| {
1529            Ok(json!([{ "similarity": 99.1, "subject_id": "EMP-42" }]))
1530        });
1531
1532        let found: Vec<Match> = search_face(json!("image"), FaceSearch::default()).unwrap();
1533
1534        assert_eq!(
1535            found,
1536            vec![Match {
1537                similarity: 99.1,
1538                subject_id: "EMP-42".to_string()
1539            }]
1540        );
1541    }
1542
1543    #[test]
1544    fn a_search_with_no_image_is_refused_before_anything_is_sent() {
1545        let session = testing::install(|_name, _params| Ok(json!([])));
1546
1547        let error = search_face::<Value>(json!(null), FaceSearch::default()).unwrap_err();
1548
1549        assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
1550        assert!(session.calls().is_empty());
1551    }
1552
1553    #[test]
1554    fn a_removal_reports_the_ids_the_platform_says_it_removed() {
1555        let session = testing::install(|name, params| {
1556            assert_eq!(name, FACE_DELETE);
1557            assert_eq!(params["face_ids"], json!(["FACE-1", "FACE-2"]));
1558
1559            Ok(json!({ "deleted": ["FACE-1"] }))
1560        });
1561
1562        let removed = delete_face(&["FACE-1".to_string(), "FACE-2".to_string()]).unwrap();
1563
1564        assert_eq!(removed, ["FACE-1"]);
1565        assert_eq!(session.calls().len(), 1);
1566    }
1567
1568    #[test]
1569    fn a_removal_reads_a_bare_list_of_ids_as_well() {
1570        let _session = testing::install(|_name, _params| Ok(json!(["FACE-1", "FACE-2"])));
1571
1572        assert_eq!(
1573            delete_face(&["FACE-1".to_string()]).unwrap(),
1574            ["FACE-1", "FACE-2"]
1575        );
1576    }
1577
1578    #[test]
1579    fn a_removal_that_names_nothing_removed_answers_with_nothing() {
1580        let _session = testing::install(|_name, _params| Ok(json!({ "ok": true })));
1581
1582        assert!(delete_face(&["FACE-1".to_string()]).unwrap().is_empty());
1583    }
1584
1585    #[test]
1586    fn a_removal_with_no_ids_is_refused_before_anything_is_sent() {
1587        let session = testing::install(|_name, _params| Ok(json!([])));
1588
1589        let error = delete_face(&[]).unwrap_err();
1590
1591        assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
1592        assert!(session.calls().is_empty());
1593    }
1594
1595    #[test]
1596    fn what_the_host_said_survives_into_every_failure() {
1597        let _session = testing::install(|_name, _params| Err(Error::failed("the engine is busy")));
1598
1599        let operation = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
1600        let enrolment = enroll_face("EMP-42", json!("image")).unwrap_err();
1601        let search = search_face::<Value>(json!("image"), FaceSearch::default()).unwrap_err();
1602        let removal = delete_face(&["FACE-1".to_string()]).unwrap_err();
1603
1604        for failure in [&operation, &enrolment, &search, &removal] {
1605            assert!(failure.message().contains("the engine is busy"));
1606            assert!(!failure.fault().hint().is_empty(), "and says what to do");
1607        }
1608    }
1609
1610    #[test]
1611    fn an_answer_that_does_not_fit_the_type_is_reported_as_having_run() {
1612        let _session = testing::install(|_name, _params| Ok(json!({ "data": { "total": 240.0 } })));
1613
1614        let error = summarize(json!("text"), "One sentence.", Options::default()).unwrap_err();
1615
1616        assert!(matches!(error, Error::Json(_)));
1617        assert_eq!(error.code().as_str(), "ACTION_FAILED");
1618        assert!(error
1619            .fault()
1620            .hint()
1621            .contains("rather than running it again"));
1622    }
1623
1624    #[test]
1625    fn a_timeout_travels_as_the_milliseconds_the_wire_carries() {
1626        assert_eq!(milliseconds(Duration::from_secs(30)), 30_000);
1627        assert_eq!(milliseconds(Duration::from_millis(1)), 1);
1628        assert_eq!(milliseconds(Duration::MAX), u64::MAX);
1629    }
1630
1631    #[test]
1632    fn every_model_names_itself_as_the_wire_spells_it() {
1633        assert_eq!(Model::Lite.to_string(), "lite");
1634        assert_eq!(Model::Medium.to_string(), "medium");
1635        assert_eq!(Model::Large.to_string(), "large");
1636        assert_eq!(Model::Xl.to_string(), "xl");
1637    }
1638}