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
14pub type Bounds = [Option<f64>; 2];
17
18#[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(¶ms[key]);
35 Box::pin(async move { Ok(answer) })
36 })
37}
38
39async 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
105pub 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 #[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 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 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 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 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 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 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}