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
15pub type Bounds = [Option<f64>; 2];
18
19#[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
29fn 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
57async 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
134pub 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 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 #[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 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 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 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 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 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 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 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 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 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 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 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}