Skip to main content

fauna_api/parrot/
format.rs

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