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