Skip to main content

fauna_api/parrot/
format.rs

1use std::sync::Arc;
2
3use serde::de::DeserializeOwned;
4use serde_json::{Map, Value, json};
5
6use super::generative::{
7    Content, Embedding, Part, Text, TextOptions, TextPart, TextResponse, Tool, generate_embedding,
8    generate_text_sync,
9};
10use crate::authentification::CredentialsOrApiKey;
11use crate::error::{Error, Result};
12use crate::shared::schema::Schema;
13
14/// `[number | undefined, number | undefined]` in the TypeScript SDK: a lower and
15/// an upper bound, either one open.
16pub type Bounds = [Option<f64>; 2];
17
18/// The `options` argument of `llm`.
19#[derive(Debug, Clone, Default)]
20pub struct LlmOptions {
21    pub content: Option<Vec<Content>>,
22}
23
24fn schema(json: Value) -> Schema {
25    serde_json::from_value(json).expect("format schemas are valid")
26}
27
28fn stringify(value: &Value) -> String {
29    serde_json::to_string(value).unwrap_or_else(|_| "null".to_string())
30}
31
32fn evaluate(key: &'static str) -> super::generative::ToolEvaluate {
33    Arc::new(move |params: Value| {
34        let answer = stringify(&params[key]);
35        Box::pin(async move { Ok(answer) })
36    })
37}
38
39/// Asks `model` with the format's instruction and reads the tool's answer, if any.
40async fn ask(
41    instruction: &str,
42    tool: &Tool,
43    authorization: &CredentialsOrApiKey,
44    model: Text,
45    options: LlmOptions,
46) -> Result<(TextResponse, Option<Value>)> {
47    let prompt = match &tool.instruction {
48        Some(line) => format!("{instruction}\n{}", line(&json!({}))),
49        None => instruction.to_string(),
50    };
51
52    let mut response = generate_text_sync(
53        authorization,
54        model,
55        TextOptions {
56            content: Some(options.content.unwrap_or_default()),
57            ..TextOptions::default()
58        },
59    )
60    .await?;
61    response
62        .content
63        .parts
64        .push(Part::Text(TextPart { text: prompt }));
65
66    let invocation = response.content.parts.iter().find_map(|part| match part {
67        Part::Invocation(invocation) => Some(invocation.clone()),
68        _ => None,
69    });
70    let answer = match invocation {
71        Some(invocation) => {
72            let args = invocation.args.map(Value::Object).unwrap_or(Value::Null);
73            Some(serde_json::from_str((tool.evaluate)(args).await?.as_str())?)
74        }
75        None => None,
76    };
77    Ok((response, answer))
78}
79
80fn read<T: DeserializeOwned>(answer: Value) -> Option<T> {
81    serde_json::from_value(answer).ok()
82}
83
84fn unit(vector: &[f64]) -> Vec<f64> {
85    if vector.is_empty() {
86        return Vec::new();
87    }
88    let norm_squared: f64 = vector.iter().map(|x| x * x).sum();
89    if norm_squared == 0.0 {
90        return Vec::new();
91    }
92    let norm = norm_squared.sqrt();
93    vector.iter().map(|x| x / norm).collect()
94}
95
96fn object(fields: Vec<(&str, Option<Value>)>) -> Value {
97    Value::Object(
98        fields
99            .into_iter()
100            .filter_map(|(key, value)| value.map(|value| (key.to_string(), value)))
101            .collect::<Map<String, Value>>(),
102    )
103}
104
105/// A question's answer shape. `from_json` returns whichever kind the JSON names.
106pub enum Format {
107    Numerical(NumericalFormat),
108    Vector(VectorFormat),
109    Categorical(CategoricalFormat),
110    Selection(SelectionFormat),
111    Utterance(UtteranceFormat),
112}
113
114impl Format {
115    pub fn instruction(&self) -> &str {
116        match self {
117            Format::Numerical(format) => &format.instruction,
118            Format::Vector(format) => &format.instruction,
119            Format::Categorical(format) => &format.instruction,
120            Format::Selection(format) => &format.instruction,
121            Format::Utterance(format) => &format.instruction,
122        }
123    }
124
125    pub fn tool(&self) -> &Tool {
126        match self {
127            Format::Numerical(format) => &format.tool,
128            Format::Vector(format) => &format.tool,
129            Format::Categorical(format) => &format.tool,
130            Format::Selection(format) => &format.tool,
131            Format::Utterance(format) => &format.tool,
132        }
133    }
134
135    fn tool_mut(&mut self) -> &mut Tool {
136        match self {
137            Format::Numerical(format) => &mut format.tool,
138            Format::Vector(format) => &mut format.tool,
139            Format::Categorical(format) => &mut format.tool,
140            Format::Selection(format) => &mut format.tool,
141            Format::Utterance(format) => &mut format.tool,
142        }
143    }
144
145    fn kind(&self) -> &'static str {
146        match self {
147            Format::Numerical(_) => "NumericalFormat",
148            Format::Vector(_) => "VectorFormat",
149            Format::Categorical(_) => "CategoricalFormat",
150            Format::Selection(_) => "SelectionFormat",
151            Format::Utterance(_) => "UtteranceFormat",
152        }
153    }
154
155    /// A fresh format with the same question and no answer.
156    #[allow(clippy::should_implement_trait)]
157    pub fn clone(&self) -> Format {
158        match self {
159            Format::Numerical(format) => Format::Numerical(format.clone()),
160            Format::Vector(format) => Format::Vector(format.clone()),
161            Format::Categorical(format) => Format::Categorical(format.clone()),
162            Format::Selection(format) => Format::Selection(format.clone()),
163            Format::Utterance(format) => Format::Utterance(format.clone()),
164        }
165    }
166
167    /// Sets the answer from its JSON; a value of the wrong shape clears it.
168    pub fn answer(&mut self, response: Value) {
169        match self {
170            Format::Numerical(format) => format.response = read(response),
171            Format::Vector(format) => format.response = read(response),
172            Format::Categorical(format) => format.response = read(response),
173            Format::Selection(format) => format.response = read(response),
174            Format::Utterance(format) => format.response = read(response),
175        }
176    }
177
178    pub fn to_json(&self) -> Value {
179        match self {
180            Format::Numerical(format) => format.to_json(),
181            Format::Vector(format) => format.to_json(),
182            Format::Categorical(format) => format.to_json(),
183            Format::Selection(format) => format.to_json(),
184            Format::Utterance(format) => format.to_json(),
185        }
186    }
187
188    /// Returns a unit-length numerical representation of the format's current
189    /// response. Used by the research agent's per-scope rank-dedup matrix to
190    /// detect linearly-dependent rows (duplicates). Concatenated across an
191    /// entity's atomic fields, the resulting vector is the row's identifier.
192    ///
193    /// Contract: all implementations return a vector with L2 norm == 1 when
194    /// a response is present. If the response is missing or empty, an
195    /// implementation may return a zero-length array; callers MUST skip such
196    /// fields when concatenating (they correspond to optional / unfilled
197    /// fields and are excluded from the rank check).
198    pub fn to_vector(&self) -> Vec<f64> {
199        match self {
200            Format::Numerical(format) => format.to_vector(),
201            Format::Vector(format) => format.to_vector(),
202            Format::Categorical(format) => format.to_vector(),
203            Format::Selection(format) => format.to_vector(),
204            Format::Utterance(format) => format.to_vector(),
205        }
206    }
207
208    pub async fn llm(
209        &mut self,
210        authorization: &CredentialsOrApiKey,
211        model: Text,
212        options: LlmOptions,
213    ) -> Result<TextResponse> {
214        let (response, answer) = ask(
215            self.instruction(),
216            self.tool(),
217            authorization,
218            model,
219            options,
220        )
221        .await?;
222        if let Some(answer) = answer {
223            self.answer(answer);
224        }
225        Ok(response)
226    }
227
228    pub fn get_response(&self) -> Option<Value> {
229        match self {
230            Format::Numerical(format) => format.get_response().map(Value::from),
231            Format::Vector(format) => format.get_response().map(Value::from),
232            Format::Categorical(format) => format.get_response().map(Value::from),
233            Format::Selection(format) => format.get_response().map(Value::from),
234            Format::Utterance(format) => format.get_response().map(Value::from),
235        }
236    }
237
238    pub fn optional(format: &Format) -> Format {
239        let mut clone = format.clone();
240
241        let original = clone.tool().clone();
242        let tool = clone.tool_mut();
243        if let Schema::Object(parameters) = &mut tool.function.parameters {
244            parameters.required = None;
245        }
246        let instruction = format.tool().instruction.clone();
247        tool.instruction = Some(Arc::new(move |params: &Value| {
248            let line = instruction
249                .as_ref()
250                .map(|instruction| instruction(params))
251                .unwrap_or_default();
252            format!(
253                "{line} This is optional. If you would opt out of answering, you may skip the parameters."
254            )
255        }));
256        tool.evaluate = Arc::new(move |params: Value| {
257            let original = original.clone();
258            Box::pin(async move {
259                if params.is_null() {
260                    return Ok(stringify(&Value::Null));
261                }
262                match (original.evaluate)(params).await {
263                    Ok(response) => Ok(response),
264                    Err(_) => Ok(stringify(&Value::Null)),
265                }
266            })
267        });
268
269        clone
270    }
271
272    pub fn calculate_distance(a: &Format, b: &Format) -> Result<f64> {
273        match (a, b) {
274            (Format::Numerical(a), Format::Numerical(b)) => Ok(NumericalFormat::distance(a, b)),
275            (Format::Vector(a), Format::Vector(b)) => Ok(VectorFormat::distance(a, b)),
276            (Format::Categorical(a), Format::Categorical(b)) => {
277                Ok(CategoricalFormat::distance(a, b))
278            }
279            (Format::Selection(a), Format::Selection(b)) => Ok(SelectionFormat::distance(a, b)),
280            (Format::Utterance(a), Format::Utterance(b)) => UtteranceFormat::distance(a, b),
281            _ => Err(Error::Message(format!(
282                "Invalid format type: {} and {}",
283                a.kind(),
284                b.kind()
285            ))),
286        }
287    }
288
289    pub fn from_json(json: &Value) -> Result<Format> {
290        let instruction = json["instruction"].as_str().unwrap_or_default();
291        let mut format = match json["type"].as_str() {
292            Some("numerical") => Format::Numerical(NumericalFormat::new(
293                instruction,
294                read(json["bounds"].clone()).flatten(),
295            )),
296            Some("vector") => Format::Vector(VectorFormat::new(
297                instruction,
298                json["dimension"].as_u64().unwrap_or_default() as usize,
299                read(json["bounds"].clone()).flatten(),
300            )),
301            Some("categorical") => Format::Categorical(CategoricalFormat::new(
302                instruction,
303                read(json["categories"].clone()).unwrap_or_default(),
304            )),
305            Some("selection") => Format::Selection(SelectionFormat::new(
306                instruction,
307                read(json["options"].clone()).unwrap_or_default(),
308            )),
309            Some("utterance") => {
310                Format::Utterance(UtteranceFormat::new(instruction, json["time"].as_f64()))
311            }
312            kind => {
313                return Err(Error::Message(format!(
314                    "Invalid format type: {} for format:\n{json}",
315                    kind.unwrap_or("undefined")
316                )));
317            }
318        };
319        format.answer(json["answer"].clone());
320        Ok(format)
321    }
322}
323
324pub struct NumericalFormat {
325    pub instruction: String,
326    pub tool: Tool,
327    response: Option<f64>,
328
329    pub bounds: Option<Bounds>,
330}
331
332impl NumericalFormat {
333    pub fn new(instruction: &str, bounds: Option<Bounds>) -> Self {
334        NumericalFormat {
335            instruction: instruction.to_string(),
336            tool: NumericalFormat::tool(None),
337            response: None,
338            bounds,
339        }
340    }
341
342    #[allow(clippy::should_implement_trait)]
343    pub fn clone(&self) -> Self {
344        NumericalFormat::new(&self.instruction, self.bounds)
345    }
346
347    pub fn answer(&mut self, response: f64) {
348        self.response = Some(response);
349    }
350
351    pub async fn llm(
352        &mut self,
353        authorization: &CredentialsOrApiKey,
354        model: Text,
355        options: LlmOptions,
356    ) -> Result<TextResponse> {
357        let (response, answer) =
358            ask(&self.instruction, &self.tool, authorization, model, options).await?;
359        if let Some(answer) = answer {
360            self.response = read(answer);
361        }
362        Ok(response)
363    }
364
365    pub fn get_response(&self) -> Option<f64> {
366        let response = self.response?;
367        let Some([lower, upper]) = self.bounds else {
368            return Some(response);
369        };
370        let mut formatted = response;
371        if let Some(lower) = lower
372            && formatted < lower
373        {
374            formatted = lower;
375        }
376        if let Some(upper) = upper
377            && formatted > upper
378        {
379            formatted = upper;
380        }
381        Some(formatted)
382    }
383
384    pub fn to_json(&self) -> Value {
385        object(vec![
386            ("type", Some(Value::from("numerical"))),
387            ("instruction", Some(Value::from(self.instruction.as_str()))),
388            ("bounds", self.bounds.map(|bounds| json!(bounds))),
389            ("answer", self.get_response().map(Value::from)),
390        ])
391    }
392
393    /// Encode the scalar as a 2-dim unit vector `[x, 1] / sqrt(x²+1)`. Direct
394    /// unit-norm on a 1-dim scalar would collapse to just the sign and discard
395    /// magnitude; the 2-dim wrap preserves magnitude as the vector's angle so
396    /// two identical scalars yield identical unit vectors and different scalars
397    /// yield distinguishable directions.
398    pub fn to_vector(&self) -> Vec<f64> {
399        let Some(x) = self.get_response() else {
400            return Vec::new();
401        };
402        let norm = (x * x + 1.0).sqrt();
403        vec![x / norm, 1.0 / norm]
404    }
405
406    pub fn compare(a: f64, b: f64) -> f64 {
407        const EPSILON: f64 = 1e-8;
408        let denom = a.abs().max(b.abs()).max(EPSILON);
409        let relative_diff = (a - b).abs() / denom;
410        1.0 / (1.0 + relative_diff)
411    }
412
413    pub fn distance(a: &NumericalFormat, b: &NumericalFormat) -> f64 {
414        match (a.get_response(), b.get_response()) {
415            (Some(a), Some(b)) => NumericalFormat::compare(a, b),
416            _ => 0.0,
417        }
418    }
419
420    pub fn tool(bounds: Option<Bounds>) -> Tool {
421        Tool {
422            function: super::generative::Function {
423                name: "return_float".to_string(),
424                description: Some("Return a number as a float.".to_string()),
425                parameters: schema(json!({
426                    "type": "OBJECT",
427                    "properties": {
428                        "number": { "type": "NUMBER", "description": "The numeric answer." }
429                    },
430                    "required": ["number"]
431                })),
432                default: None,
433                example: None,
434                behavior: None,
435            },
436            evaluate: evaluate("number"),
437            instruction: Some(Arc::new(move |_params: &Value| match bounds {
438                Some([Some(lower), Some(upper)]) => format!(
439                    "Use the tool \"return_float\" to return your answer as a number on the scale of {lower} to {upper}."
440                ),
441                Some([Some(lower), None]) => format!(
442                    "Use the tool \"return_float\" to return your answer as a number greater than {lower}."
443                ),
444                Some([None, upper]) => format!(
445                    "Use the tool \"return_float\" to return your answer as a number less than {}.",
446                    upper.map_or("undefined".to_string(), |upper| upper.to_string())
447                ),
448                None => {
449                    "Use the tool \"return_float\" to return your answer as a number.".to_string()
450                }
451            })),
452        }
453    }
454}
455
456pub struct VectorFormat {
457    pub instruction: String,
458    pub tool: Tool,
459    response: Option<Vec<f64>>,
460
461    pub dimension: usize,
462    pub bounds: Option<Vec<Option<Bounds>>>,
463}
464
465impl VectorFormat {
466    pub fn new(instruction: &str, dimension: usize, bounds: Option<Vec<Option<Bounds>>>) -> Self {
467        VectorFormat {
468            instruction: instruction.to_string(),
469            tool: VectorFormat::tool(dimension, bounds.clone()),
470            response: None,
471            dimension,
472            bounds,
473        }
474    }
475
476    #[allow(clippy::should_implement_trait)]
477    pub fn clone(&self) -> Self {
478        VectorFormat::new(&self.instruction, self.dimension, self.bounds.clone())
479    }
480
481    pub fn answer(&mut self, response: Vec<f64>) {
482        self.response = Some(response);
483    }
484
485    pub async fn llm(
486        &mut self,
487        authorization: &CredentialsOrApiKey,
488        model: Text,
489        options: LlmOptions,
490    ) -> Result<TextResponse> {
491        let (response, answer) =
492            ask(&self.instruction, &self.tool, authorization, model, options).await?;
493        if let Some(answer) = answer {
494            self.response = read(answer);
495        }
496        Ok(response)
497    }
498
499    pub fn get_response(&self) -> Option<Vec<f64>> {
500        let response = self.response.as_ref()?;
501        let Some(bounds) = &self.bounds else {
502            return Some(response.clone());
503        };
504        Some(
505            response
506                .iter()
507                .enumerate()
508                .map(|(index, &number)| {
509                    let mut number = number;
510                    if let Some(Some([lower, upper])) = bounds.get(index) {
511                        if let Some(lower) = lower
512                            && number < *lower
513                        {
514                            number = *lower;
515                        }
516                        if let Some(upper) = upper
517                            && number > *upper
518                        {
519                            number = *upper;
520                        }
521                    }
522                    number
523                })
524                .collect(),
525        )
526    }
527
528    pub fn to_json(&self) -> Value {
529        object(vec![
530            ("type", Some(Value::from("vector"))),
531            ("instruction", Some(Value::from(self.instruction.as_str()))),
532            ("dimension", Some(Value::from(self.dimension))),
533            ("bounds", self.bounds.as_ref().map(|bounds| json!(bounds))),
534            ("answer", self.get_response().map(Value::from)),
535        ])
536    }
537
538    pub fn to_vector(&self) -> Vec<f64> {
539        unit(&self.get_response().unwrap_or_default())
540    }
541
542    pub fn distance(a: &VectorFormat, b: &VectorFormat) -> f64 {
543        let (Some(vector_a), Some(vector_b)) = (a.get_response(), b.get_response()) else {
544            return 0.0;
545        };
546        let aggregate: f64 = vector_a
547            .iter()
548            .enumerate()
549            .map(|(index, &a)| {
550                NumericalFormat::compare(a, vector_b.get(index).copied().unwrap_or(f64::NAN))
551            })
552            .sum();
553        aggregate / vector_a.len() as f64
554    }
555
556    pub fn tool(dimension: usize, bounds: Option<Vec<Option<Bounds>>>) -> Tool {
557        Tool {
558            function: super::generative::Function {
559                name: "return_vector".to_string(),
560                description: Some(format!("Return a vector of {dimension} numbers.")),
561                parameters: schema(json!({
562                    "type": "OBJECT",
563                    "properties": {
564                        "vector": {
565                            "type": "ARRAY",
566                            "items": { "type": "NUMBER" },
567                            "minimum": dimension,
568                            "maximum": dimension,
569                            "description": format!("A vector of exactly {dimension} numbers.")
570                        }
571                    },
572                    "required": ["vector"]
573                })),
574                default: None,
575                example: None,
576                behavior: None,
577            },
578            evaluate: evaluate("vector"),
579            instruction: Some(Arc::new(move |_params: &Value| {
580                let Some(bounds) = &bounds else {
581                    return format!(
582                        "Use the tool \"return_vector\" to return your answer as a numerical vector of dimension {dimension}."
583                    );
584                };
585
586                let mut lower_bound = String::from("[");
587                let mut upper_bound = String::from("[");
588
589                for index in 0..dimension {
590                    match bounds.get(index).copied().flatten() {
591                        None | Some([None, None]) => {
592                            lower_bound.push_str("-infinity");
593                            upper_bound.push_str("infinity");
594                        }
595                        Some([Some(lower), _]) => {
596                            lower_bound.push_str(&format!(">{lower}"));
597                            upper_bound.push_str("infinity");
598                        }
599                        Some([None, Some(upper)]) => {
600                            lower_bound.push_str("-infinity");
601                            upper_bound.push_str(&format!("<{upper}"));
602                        }
603                    }
604
605                    if index + 1 < dimension {
606                        lower_bound.push_str(", ");
607                        upper_bound.push_str(", ");
608                    }
609                }
610                lower_bound.push(']');
611                upper_bound.push(']');
612
613                format!(
614                    "Use the tool \"return_vector\" to return your answer as a numerical vector of dimension {dimension} of scale {lower_bound} to {upper_bound}."
615                )
616            })),
617        }
618    }
619}
620
621pub struct CategoricalFormat {
622    pub instruction: String,
623    pub tool: Tool,
624    response: Option<String>,
625
626    categories: Vec<String>,
627}
628
629impl CategoricalFormat {
630    pub fn new(instruction: &str, categories: Vec<String>) -> Self {
631        CategoricalFormat {
632            instruction: instruction.to_string(),
633            tool: CategoricalFormat::tool(&categories),
634            response: None,
635            categories,
636        }
637    }
638
639    #[allow(clippy::should_implement_trait)]
640    pub fn clone(&self) -> Self {
641        CategoricalFormat::new(&self.instruction, self.categories.clone())
642    }
643
644    pub fn answer(&mut self, response: String) {
645        self.response = Some(response);
646    }
647
648    pub async fn llm(
649        &mut self,
650        authorization: &CredentialsOrApiKey,
651        model: Text,
652        options: LlmOptions,
653    ) -> Result<TextResponse> {
654        let (response, answer) =
655            ask(&self.instruction, &self.tool, authorization, model, options).await?;
656        if let Some(answer) = answer {
657            self.response = read(answer);
658        }
659        Ok(response)
660    }
661
662    pub fn get_categories(&self) -> &[String] {
663        &self.categories
664    }
665
666    pub fn get_response(&self) -> Option<String> {
667        match &self.response {
668            Some(response) if !response.is_empty() => self
669                .categories
670                .iter()
671                .find(|category| *category == response)
672                .cloned(),
673            response => response.clone(),
674        }
675    }
676
677    pub fn to_json(&self) -> Value {
678        object(vec![
679            ("type", Some(Value::from("categorical"))),
680            ("instruction", Some(Value::from(self.instruction.as_str()))),
681            ("categories", Some(json!(self.categories))),
682            ("answer", self.get_response().map(Value::from)),
683        ])
684    }
685
686    /// One-hot over the category set, already unit-length.
687    pub fn to_vector(&self) -> Vec<f64> {
688        let Some(category) = self.get_response() else {
689            return Vec::new();
690        };
691        let Some(index) = self.categories.iter().position(|other| *other == category) else {
692            return Vec::new();
693        };
694        let mut vector = vec![0.0; self.categories.len()];
695        vector[index] = 1.0;
696        vector
697    }
698
699    pub fn distance(a: &CategoricalFormat, b: &CategoricalFormat) -> f64 {
700        match (a.get_response(), b.get_response()) {
701            (Some(a), Some(b)) if a == b => 1.0,
702            _ => 0.0,
703        }
704    }
705
706    pub fn tool(categories: &[String]) -> Tool {
707        let listed = stringify(&json!(categories));
708        Tool {
709            function: super::generative::Function {
710                name: "return_category".to_string(),
711                description: Some("Return one of the predefined categories.".to_string()),
712                parameters: schema(json!({
713                    "type": "OBJECT",
714                    "properties": {
715                        "category": {
716                            "type": "STRING",
717                            "enum": categories,
718                            "description": "The selected category."
719                        }
720                    },
721                    "required": ["category"]
722                })),
723                default: None,
724                example: None,
725                behavior: None,
726            },
727            evaluate: evaluate("category"),
728            instruction: Some(Arc::new(move |_params: &Value| {
729                format!(
730                    "Use the tool \"return_category\" to return your answer as one of the categories: {listed}."
731                )
732            })),
733        }
734    }
735}
736
737pub struct SelectionFormat {
738    pub instruction: String,
739    pub tool: Tool,
740    response: Option<Vec<String>>,
741
742    options: Vec<String>,
743}
744
745impl SelectionFormat {
746    pub fn new(instruction: &str, options: Vec<String>) -> Self {
747        SelectionFormat {
748            instruction: instruction.to_string(),
749            tool: SelectionFormat::tool(&options),
750            response: None,
751            options,
752        }
753    }
754
755    #[allow(clippy::should_implement_trait)]
756    pub fn clone(&self) -> Self {
757        SelectionFormat::new(&self.instruction, self.options.clone())
758    }
759
760    pub fn answer(&mut self, response: Vec<String>) {
761        self.response = Some(response);
762    }
763
764    pub async fn llm(
765        &mut self,
766        authorization: &CredentialsOrApiKey,
767        model: Text,
768        options: LlmOptions,
769    ) -> Result<TextResponse> {
770        let (response, answer) =
771            ask(&self.instruction, &self.tool, authorization, model, options).await?;
772        if let Some(answer) = answer {
773            self.response = read(answer);
774        }
775        Ok(response)
776    }
777
778    pub fn get_options(&self) -> &[String] {
779        &self.options
780    }
781
782    pub fn get_response(&self) -> Option<Vec<String>> {
783        Some(
784            self.response
785                .iter()
786                .flatten()
787                .filter(|selection| self.options.contains(selection))
788                .cloned()
789                .collect(),
790        )
791    }
792
793    pub fn to_json(&self) -> Value {
794        object(vec![
795            ("type", Some(Value::from("selection"))),
796            ("instruction", Some(Value::from(self.instruction.as_str()))),
797            ("options", Some(json!(self.options))),
798            ("answer", self.get_response().map(Value::from)),
799        ])
800    }
801
802    /// Multi-hot scaled by 1/sqrt(count) so the vector is unit-length.
803    pub fn to_vector(&self) -> Vec<f64> {
804        let selections = self.get_response().unwrap_or_default();
805        if selections.is_empty() {
806            return Vec::new();
807        }
808        let mut vector = vec![0.0; self.options.len()];
809        let mut count = 0;
810        for selection in &selections {
811            if let Some(index) = self.options.iter().position(|option| option == selection) {
812                vector[index] = 1.0;
813                count += 1;
814            }
815        }
816        if count == 0 {
817            return Vec::new();
818        }
819        let scale = 1.0 / (count as f64).sqrt();
820        vector.iter().map(|x| x * scale).collect()
821    }
822
823    pub fn distance(a: &SelectionFormat, b: &SelectionFormat) -> f64 {
824        let selections_a = a.get_response().unwrap_or_default();
825        let selections_b = b.get_response().unwrap_or_default();
826
827        if selections_a.is_empty() && selections_b.is_empty() {
828            return 1.0;
829        }
830        if selections_a.is_empty() || selections_b.is_empty() {
831            return 0.0;
832        }
833
834        let set_a: std::collections::HashSet<&String> = selections_a.iter().collect();
835        let set_b: std::collections::HashSet<&String> = selections_b.iter().collect();
836        let intersection_size = set_a.intersection(&set_b).count();
837        let union_size = set_a.union(&set_b).count();
838        intersection_size as f64 / union_size as f64
839    }
840
841    pub fn tool(options: &[String]) -> Tool {
842        let listed = stringify(&json!(options));
843        Tool {
844            function: super::generative::Function {
845                name: "return_selections".to_string(),
846                description: Some("Return one or more selected options.".to_string()),
847                parameters: schema(json!({
848                    "type": "OBJECT",
849                    "properties": {
850                        "selections": {
851                            "type": "ARRAY",
852                            "items": { "type": "STRING", "enum": options },
853                            "description": "The selected options."
854                        }
855                    },
856                    "required": ["selections"]
857                })),
858                default: None,
859                example: None,
860                behavior: None,
861            },
862            evaluate: evaluate("selections"),
863            instruction: Some(Arc::new(move |_params: &Value| {
864                format!(
865                    "Use the tool \"return_selections\" to return your answer as a categorical vector of one or more in {listed}"
866                )
867            })),
868        }
869    }
870}
871
872pub struct UtteranceFormat {
873    pub instruction: String,
874    pub tool: Tool,
875    response: Option<String>,
876
877    pub time: Option<f64>,
878    pub embedding: Option<Vec<f64>>,
879}
880
881impl UtteranceFormat {
882    pub fn new(instruction: &str, time: Option<f64>) -> Self {
883        UtteranceFormat {
884            instruction: instruction.to_string(),
885            tool: UtteranceFormat::tool(None),
886            response: None,
887            time,
888            embedding: None,
889        }
890    }
891
892    #[allow(clippy::should_implement_trait)]
893    pub fn clone(&self) -> Self {
894        UtteranceFormat::new(&self.instruction, self.time)
895    }
896
897    pub fn answer(&mut self, response: String) {
898        self.response = Some(response);
899    }
900
901    pub async fn llm(
902        &mut self,
903        authorization: &CredentialsOrApiKey,
904        model: Text,
905        options: LlmOptions,
906    ) -> Result<TextResponse> {
907        let (response, answer) =
908            ask(&self.instruction, &self.tool, authorization, model, options).await?;
909        if let Some(answer) = answer {
910            self.response = read(answer);
911        }
912        Ok(response)
913    }
914
915    pub fn get_response(&self) -> Option<String> {
916        self.response.clone()
917    }
918
919    pub fn to_json(&self) -> Value {
920        object(vec![
921            ("type", Some(Value::from("utterance"))),
922            ("instruction", Some(Value::from(self.instruction.as_str()))),
923            ("time", self.time.map(Value::from)),
924            ("answer", self.get_response().map(Value::from)),
925        ])
926    }
927
928    /// Returns the unit-normalized embedding. The caller MUST have populated
929    /// `embedding` first (via `embed()` or the research agent's extraction
930    /// pipeline), otherwise this returns an empty vector and the field is
931    /// excluded from the rank check. Embedding-less utterances cannot
932    /// participate in dedup.
933    pub fn to_vector(&self) -> Vec<f64> {
934        unit(self.embedding.as_deref().unwrap_or_default())
935    }
936
937    pub async fn embed(
938        &mut self,
939        authorization: &CredentialsOrApiKey,
940        model: Embedding,
941    ) -> Result<()> {
942        let Some(utterance) = self.get_response() else {
943            return Err(Error::Message(
944                "Cannot embed an utterance format without an answer.".to_string(),
945            ));
946        };
947        let result = generate_embedding(authorization, model, &utterance, None).await?;
948        self.embedding = Some(result.embedding);
949        Ok(())
950    }
951
952    pub fn distance(a: &UtteranceFormat, b: &UtteranceFormat) -> Result<f64> {
953        fn linear_cosine_similarity(a: &[f64], b: &[f64]) -> f64 {
954            let mut dot_product = 0.0;
955            let mut norm_a = 0.0;
956            let mut norm_b = 0.0;
957
958            for (index, &x) in a.iter().enumerate() {
959                let y = b.get(index).copied().unwrap_or(f64::NAN);
960                dot_product += x * y;
961                norm_a += x * x;
962                norm_b += y * y;
963            }
964
965            let norm_a: f64 = f64::sqrt(norm_a);
966            let norm_b: f64 = f64::sqrt(norm_b);
967
968            let similarity =
969                if norm_a != 0.0 && norm_b != 0.0 && !norm_a.is_nan() && !norm_b.is_nan() {
970                    dot_product / (norm_a * norm_b)
971                } else {
972                    0.0
973                };
974
975            1.0 - similarity.clamp(-1.0, 1.0).acos() / std::f64::consts::PI
976        }
977        match (&a.embedding, &b.embedding) {
978            (Some(a), Some(b)) => Ok(linear_cosine_similarity(a, b)),
979            _ => Err(Error::Message(
980                "Both utterance formats must be embedded before computing distance. Call embed() first."
981                    .to_string(),
982            )),
983        }
984    }
985
986    pub fn tool(time: Option<f64>) -> Tool {
987        let time = time.filter(|time| *time != 0.0 && !time.is_nan());
988        Tool {
989            function: super::generative::Function {
990                name: "return_text".to_string(),
991                description: Some(format!(
992                    "Return a free-form text response {}.",
993                    time.map_or(String::new(), |time| format!(" within {time} seconds)"))
994                )),
995                parameters: schema(json!({
996                    "type": "OBJECT",
997                    "properties": {
998                        "content": { "type": "STRING", "description": "The text response." }
999                    },
1000                    "required": ["content"]
1001                })),
1002                default: None,
1003                example: None,
1004                behavior: None,
1005            },
1006            evaluate: evaluate("content"),
1007            instruction: Some(Arc::new(move |_params: &Value| {
1008                format!(
1009                    "Use the tool \"return_text\" to return your answer as a string of {}.",
1010                    time.map_or("any length".to_string(), |time| format!(
1011                        "length within {time} seconds"
1012                    ))
1013                )
1014            })),
1015        }
1016    }
1017}