use std::sync::{Arc, Mutex, PoisonError};
use chrono::Utc;
use serde::de::DeserializeOwned;
use serde_json::{Map, Value, json};
use super::generative::{
Content, Embedding, Function, Part, Role, Text, TextOptions, TextPart, TextResponse, Tool,
ToolsOrTool, generate_embedding, generate_text_sync,
};
use crate::authentification::CredentialsOrApiKey;
use crate::error::{Error, Result};
use crate::shared::schema::{ObjectSchema, Schema};
pub type Bounds = [Option<f64>; 2];
#[derive(Debug, Clone, Default)]
pub struct LlmOptions {
pub content: Option<Vec<Content>>,
}
fn schema(json: Value) -> Schema {
serde_json::from_value(json).expect("format schemas are valid")
}
fn answer_tool(name: &str, description: String, key: &'static str, answer: Value) -> Tool {
Tool {
function: Function {
name: name.to_string(),
description: Some(description),
parameters: schema(json!({
"type": "OBJECT",
"properties": { key: answer.clone() },
"required": [key],
})),
returns: serde_json::from_value::<ObjectSchema>(json!({
"type": "OBJECT",
"properties": { "answer": answer },
"required": ["answer"],
}))
.expect("format returns are valid"),
default: None,
example: None,
behavior: None,
},
evaluate: Arc::new(move |params: Value, _progress| {
let answer = params.get(key).cloned().unwrap_or(Value::Null);
Box::pin(async move { Ok(Map::from_iter([("answer".to_string(), answer)])) })
}),
}
}
async fn ask(
instruction: &str,
usage: &str,
tool: &Tool,
authorization: &CredentialsOrApiKey,
model: Text,
options: LlmOptions,
) -> Result<(TextResponse, Option<Value>)> {
let answered: Arc<Mutex<Option<Value>>> = Arc::default();
let original = tool.clone();
let keep = answered.clone();
let answering = Tool {
function: tool.function.clone(),
evaluate: Arc::new(move |params, progress| {
let (original, keep) = (original.clone(), keep.clone());
Box::pin(async move {
let result = (original.evaluate)(params, progress).await?;
*keep.lock().unwrap_or_else(PoisonError::into_inner) =
result.get("answer").cloned();
Ok(result)
})
}),
};
let mut content = options.content.unwrap_or_default();
content.push(Content {
parts: vec![Part::Text(TextPart {
text: format!("{instruction}\n{usage}"),
})],
role: Role::User,
created_at: Utc::now(),
author: None,
model: None,
});
let response = generate_text_sync(
authorization,
model,
TextOptions {
content: Some(content),
tools: Some(ToolsOrTool::Tool(answering)),
..TextOptions::default()
},
)
.await?;
let answer = answered
.lock()
.unwrap_or_else(PoisonError::into_inner)
.take();
Ok((response, answer))
}
fn read<T: DeserializeOwned>(answer: Value) -> Option<T> {
serde_json::from_value(answer).ok()
}
fn unit(vector: &[f64]) -> Vec<f64> {
if vector.is_empty() {
return Vec::new();
}
let norm_squared: f64 = vector.iter().map(|x| x * x).sum();
if norm_squared == 0.0 {
return Vec::new();
}
let norm = norm_squared.sqrt();
vector.iter().map(|x| x / norm).collect()
}
fn object(fields: Vec<(&str, Option<Value>)>) -> Value {
Value::Object(
fields
.into_iter()
.filter_map(|(key, value)| value.map(|value| (key.to_string(), value)))
.collect::<Map<String, Value>>(),
)
}
pub enum Format {
Numerical(NumericalFormat),
Vector(VectorFormat),
Categorical(CategoricalFormat),
Selection(SelectionFormat),
Utterance(UtteranceFormat),
}
impl Format {
pub fn instruction(&self) -> &str {
match self {
Format::Numerical(format) => &format.instruction,
Format::Vector(format) => &format.instruction,
Format::Categorical(format) => &format.instruction,
Format::Selection(format) => &format.instruction,
Format::Utterance(format) => &format.instruction,
}
}
pub fn usage(&self) -> &str {
match self {
Format::Numerical(format) => &format.usage,
Format::Vector(format) => &format.usage,
Format::Categorical(format) => &format.usage,
Format::Selection(format) => &format.usage,
Format::Utterance(format) => &format.usage,
}
}
fn usage_mut(&mut self) -> &mut String {
match self {
Format::Numerical(format) => &mut format.usage,
Format::Vector(format) => &mut format.usage,
Format::Categorical(format) => &mut format.usage,
Format::Selection(format) => &mut format.usage,
Format::Utterance(format) => &mut format.usage,
}
}
pub fn tool(&self) -> &Tool {
match self {
Format::Numerical(format) => &format.tool,
Format::Vector(format) => &format.tool,
Format::Categorical(format) => &format.tool,
Format::Selection(format) => &format.tool,
Format::Utterance(format) => &format.tool,
}
}
fn tool_mut(&mut self) -> &mut Tool {
match self {
Format::Numerical(format) => &mut format.tool,
Format::Vector(format) => &mut format.tool,
Format::Categorical(format) => &mut format.tool,
Format::Selection(format) => &mut format.tool,
Format::Utterance(format) => &mut format.tool,
}
}
fn kind(&self) -> &'static str {
match self {
Format::Numerical(_) => "NumericalFormat",
Format::Vector(_) => "VectorFormat",
Format::Categorical(_) => "CategoricalFormat",
Format::Selection(_) => "SelectionFormat",
Format::Utterance(_) => "UtteranceFormat",
}
}
#[allow(clippy::should_implement_trait)]
pub fn clone(&self) -> Format {
match self {
Format::Numerical(format) => Format::Numerical(format.clone()),
Format::Vector(format) => Format::Vector(format.clone()),
Format::Categorical(format) => Format::Categorical(format.clone()),
Format::Selection(format) => Format::Selection(format.clone()),
Format::Utterance(format) => Format::Utterance(format.clone()),
}
}
pub fn answer(&mut self, response: Value) {
match self {
Format::Numerical(format) => format.response = read(response),
Format::Vector(format) => format.response = read(response),
Format::Categorical(format) => format.response = read(response),
Format::Selection(format) => format.response = read(response),
Format::Utterance(format) => format.response = read(response),
}
}
pub fn to_json(&self) -> Value {
match self {
Format::Numerical(format) => format.to_json(),
Format::Vector(format) => format.to_json(),
Format::Categorical(format) => format.to_json(),
Format::Selection(format) => format.to_json(),
Format::Utterance(format) => format.to_json(),
}
}
pub fn to_vector(&self) -> Vec<f64> {
match self {
Format::Numerical(format) => format.to_vector(),
Format::Vector(format) => format.to_vector(),
Format::Categorical(format) => format.to_vector(),
Format::Selection(format) => format.to_vector(),
Format::Utterance(format) => format.to_vector(),
}
}
pub async fn llm(
&mut self,
authorization: &CredentialsOrApiKey,
model: Text,
options: LlmOptions,
) -> Result<TextResponse> {
let (response, answer) = ask(
self.instruction(),
self.usage(),
self.tool(),
authorization,
model,
options,
)
.await?;
if let Some(answer) = answer {
self.answer(answer);
}
Ok(response)
}
pub fn get_response(&self) -> Option<Value> {
match self {
Format::Numerical(format) => format.get_response().map(Value::from),
Format::Vector(format) => format.get_response().map(Value::from),
Format::Categorical(format) => format.get_response().map(Value::from),
Format::Selection(format) => format.get_response().map(Value::from),
Format::Utterance(format) => format.get_response().map(Value::from),
}
}
pub fn optional(format: &Format) -> Format {
let mut clone = format.clone();
let original = clone.tool().clone();
*clone.usage_mut() = format!(
"{} This is optional. If you would opt out of answering, you may skip the parameters.",
format.usage()
);
let tool = clone.tool_mut();
if let Schema::Object(parameters) = &mut tool.function.parameters {
parameters.required = None;
}
tool.evaluate = Arc::new(move |params: Value, progress| {
let original = original.clone();
Box::pin(async move {
let skipped = Map::from_iter([("answer".to_string(), Value::Null)]);
if params.is_null() {
return Ok(skipped);
}
Ok((original.evaluate)(params, progress)
.await
.unwrap_or(skipped))
})
});
clone
}
pub fn calculate_distance(a: &Format, b: &Format) -> Result<f64> {
match (a, b) {
(Format::Numerical(a), Format::Numerical(b)) => Ok(NumericalFormat::distance(a, b)),
(Format::Vector(a), Format::Vector(b)) => Ok(VectorFormat::distance(a, b)),
(Format::Categorical(a), Format::Categorical(b)) => {
Ok(CategoricalFormat::distance(a, b))
}
(Format::Selection(a), Format::Selection(b)) => Ok(SelectionFormat::distance(a, b)),
(Format::Utterance(a), Format::Utterance(b)) => UtteranceFormat::distance(a, b),
_ => Err(Error::Message(format!(
"Invalid format type: {} and {}",
a.kind(),
b.kind()
))),
}
}
pub fn from_json(json: &Value) -> Result<Format> {
let instruction = json["instruction"].as_str().unwrap_or_default();
let mut format = match json["type"].as_str() {
Some("numerical") => Format::Numerical(NumericalFormat::new(
instruction,
read(json["bounds"].clone()).flatten(),
)),
Some("vector") => Format::Vector(VectorFormat::new(
instruction,
json["dimension"].as_u64().unwrap_or_default() as usize,
read(json["bounds"].clone()).flatten(),
)),
Some("categorical") => Format::Categorical(CategoricalFormat::new(
instruction,
read(json["categories"].clone()).unwrap_or_default(),
)),
Some("selection") => Format::Selection(SelectionFormat::new(
instruction,
read(json["options"].clone()).unwrap_or_default(),
)),
Some("utterance") => {
Format::Utterance(UtteranceFormat::new(instruction, json["time"].as_f64()))
}
kind => {
return Err(Error::Message(format!(
"Invalid format type: {} for format:\n{json}",
kind.unwrap_or("undefined")
)));
}
};
format.answer(json["answer"].clone());
Ok(format)
}
}
pub struct NumericalFormat {
pub instruction: String,
pub tool: Tool,
pub usage: String,
response: Option<f64>,
pub bounds: Option<Bounds>,
}
impl NumericalFormat {
pub fn new(instruction: &str, bounds: Option<Bounds>) -> Self {
NumericalFormat {
instruction: instruction.to_string(),
tool: NumericalFormat::tool(),
usage: NumericalFormat::usage(bounds),
response: None,
bounds,
}
}
#[allow(clippy::should_implement_trait)]
pub fn clone(&self) -> Self {
NumericalFormat::new(&self.instruction, self.bounds)
}
pub fn answer(&mut self, response: f64) {
self.response = Some(response);
}
pub async fn llm(
&mut self,
authorization: &CredentialsOrApiKey,
model: Text,
options: LlmOptions,
) -> Result<TextResponse> {
let (response, answer) = ask(
&self.instruction,
&self.usage,
&self.tool,
authorization,
model,
options,
)
.await?;
if let Some(answer) = answer {
self.response = read(answer);
}
Ok(response)
}
pub fn get_response(&self) -> Option<f64> {
let response = self.response?;
let Some([lower, upper]) = self.bounds else {
return Some(response);
};
let mut formatted = response;
if let Some(lower) = lower
&& formatted < lower
{
formatted = lower;
}
if let Some(upper) = upper
&& formatted > upper
{
formatted = upper;
}
Some(formatted)
}
pub fn to_json(&self) -> Value {
object(vec![
("type", Some(Value::from("numerical"))),
("instruction", Some(Value::from(self.instruction.as_str()))),
("bounds", self.bounds.map(|bounds| json!(bounds))),
("answer", self.get_response().map(Value::from)),
])
}
pub fn to_vector(&self) -> Vec<f64> {
let Some(x) = self.get_response() else {
return Vec::new();
};
let norm = (x * x + 1.0).sqrt();
vec![x / norm, 1.0 / norm]
}
pub fn compare(a: f64, b: f64) -> f64 {
const EPSILON: f64 = 1e-8;
let denom = a.abs().max(b.abs()).max(EPSILON);
let relative_diff = (a - b).abs() / denom;
1.0 / (1.0 + relative_diff)
}
pub fn distance(a: &NumericalFormat, b: &NumericalFormat) -> f64 {
match (a.get_response(), b.get_response()) {
(Some(a), Some(b)) => NumericalFormat::compare(a, b),
_ => 0.0,
}
}
pub fn tool() -> Tool {
answer_tool(
"return_float",
"Return a number as a float.".to_string(),
"number",
json!({ "type": "NUMBER", "description": "The numeric answer." }),
)
}
pub fn usage(bounds: Option<Bounds>) -> String {
match bounds {
Some([Some(lower), Some(upper)]) => format!(
"Use the tool \"return_float\" to return your answer as a number on the scale of {lower} to {upper}."
),
Some([Some(lower), None]) => format!(
"Use the tool \"return_float\" to return your answer as a number greater than {lower}."
),
Some([None, upper]) => format!(
"Use the tool \"return_float\" to return your answer as a number less than {}.",
upper.map_or("undefined".to_string(), |upper| upper.to_string())
),
None => "Use the tool \"return_float\" to return your answer as a number.".to_string(),
}
}
}
pub struct VectorFormat {
pub instruction: String,
pub tool: Tool,
pub usage: String,
response: Option<Vec<f64>>,
pub dimension: usize,
pub bounds: Option<Vec<Option<Bounds>>>,
}
impl VectorFormat {
pub fn new(instruction: &str, dimension: usize, bounds: Option<Vec<Option<Bounds>>>) -> Self {
VectorFormat {
instruction: instruction.to_string(),
tool: VectorFormat::tool(dimension),
usage: VectorFormat::usage(dimension, bounds.as_deref()),
response: None,
dimension,
bounds,
}
}
#[allow(clippy::should_implement_trait)]
pub fn clone(&self) -> Self {
VectorFormat::new(&self.instruction, self.dimension, self.bounds.clone())
}
pub fn answer(&mut self, response: Vec<f64>) {
self.response = Some(response);
}
pub async fn llm(
&mut self,
authorization: &CredentialsOrApiKey,
model: Text,
options: LlmOptions,
) -> Result<TextResponse> {
let (response, answer) = ask(
&self.instruction,
&self.usage,
&self.tool,
authorization,
model,
options,
)
.await?;
if let Some(answer) = answer {
self.response = read(answer);
}
Ok(response)
}
pub fn get_response(&self) -> Option<Vec<f64>> {
let response = self.response.as_ref()?;
let Some(bounds) = &self.bounds else {
return Some(response.clone());
};
Some(
response
.iter()
.enumerate()
.map(|(index, &number)| {
let mut number = number;
if let Some(Some([lower, upper])) = bounds.get(index) {
if let Some(lower) = lower
&& number < *lower
{
number = *lower;
}
if let Some(upper) = upper
&& number > *upper
{
number = *upper;
}
}
number
})
.collect(),
)
}
pub fn to_json(&self) -> Value {
object(vec![
("type", Some(Value::from("vector"))),
("instruction", Some(Value::from(self.instruction.as_str()))),
("dimension", Some(Value::from(self.dimension))),
("bounds", self.bounds.as_ref().map(|bounds| json!(bounds))),
("answer", self.get_response().map(Value::from)),
])
}
pub fn to_vector(&self) -> Vec<f64> {
unit(&self.get_response().unwrap_or_default())
}
pub fn distance(a: &VectorFormat, b: &VectorFormat) -> f64 {
let (Some(vector_a), Some(vector_b)) = (a.get_response(), b.get_response()) else {
return 0.0;
};
let aggregate: f64 = vector_a
.iter()
.enumerate()
.map(|(index, &a)| {
NumericalFormat::compare(a, vector_b.get(index).copied().unwrap_or(f64::NAN))
})
.sum();
aggregate / vector_a.len() as f64
}
pub fn tool(dimension: usize) -> Tool {
answer_tool(
"return_vector",
format!("Return a vector of {dimension} numbers."),
"vector",
json!({
"type": "ARRAY",
"items": { "type": "NUMBER" },
"minimum": dimension,
"maximum": dimension,
"description": format!("A vector of exactly {dimension} numbers.")
}),
)
}
pub fn usage(dimension: usize, bounds: Option<&[Option<Bounds>]>) -> String {
let Some(bounds) = bounds else {
return format!(
"Use the tool \"return_vector\" to return your answer as a numerical vector of dimension {dimension}."
);
};
let mut lower_bound = String::from("[");
let mut upper_bound = String::from("[");
for index in 0..dimension {
match bounds.get(index).copied().flatten() {
None | Some([None, None]) => {
lower_bound.push_str("-infinity");
upper_bound.push_str("infinity");
}
Some([Some(lower), _]) => {
lower_bound.push_str(&format!(">{lower}"));
upper_bound.push_str("infinity");
}
Some([None, Some(upper)]) => {
lower_bound.push_str("-infinity");
upper_bound.push_str(&format!("<{upper}"));
}
}
if index + 1 < dimension {
lower_bound.push_str(", ");
upper_bound.push_str(", ");
}
}
lower_bound.push(']');
upper_bound.push(']');
format!(
"Use the tool \"return_vector\" to return your answer as a numerical vector of dimension {dimension} of scale {lower_bound} to {upper_bound}."
)
}
}
pub struct CategoricalFormat {
pub instruction: String,
pub tool: Tool,
pub usage: String,
response: Option<String>,
categories: Vec<String>,
}
impl CategoricalFormat {
pub fn new(instruction: &str, categories: Vec<String>) -> Self {
CategoricalFormat {
instruction: instruction.to_string(),
tool: CategoricalFormat::tool(&categories),
usage: CategoricalFormat::usage(&categories),
response: None,
categories,
}
}
#[allow(clippy::should_implement_trait)]
pub fn clone(&self) -> Self {
CategoricalFormat::new(&self.instruction, self.categories.clone())
}
pub fn answer(&mut self, response: String) {
self.response = Some(response);
}
pub async fn llm(
&mut self,
authorization: &CredentialsOrApiKey,
model: Text,
options: LlmOptions,
) -> Result<TextResponse> {
let (response, answer) = ask(
&self.instruction,
&self.usage,
&self.tool,
authorization,
model,
options,
)
.await?;
if let Some(answer) = answer {
self.response = read(answer);
}
Ok(response)
}
pub fn get_categories(&self) -> &[String] {
&self.categories
}
pub fn get_response(&self) -> Option<String> {
match &self.response {
Some(response) if !response.is_empty() => self
.categories
.iter()
.find(|category| *category == response)
.cloned(),
response => response.clone(),
}
}
pub fn to_json(&self) -> Value {
object(vec![
("type", Some(Value::from("categorical"))),
("instruction", Some(Value::from(self.instruction.as_str()))),
("categories", Some(json!(self.categories))),
("answer", self.get_response().map(Value::from)),
])
}
pub fn to_vector(&self) -> Vec<f64> {
let Some(category) = self.get_response() else {
return Vec::new();
};
let Some(index) = self.categories.iter().position(|other| *other == category) else {
return Vec::new();
};
let mut vector = vec![0.0; self.categories.len()];
vector[index] = 1.0;
vector
}
pub fn distance(a: &CategoricalFormat, b: &CategoricalFormat) -> f64 {
match (a.get_response(), b.get_response()) {
(Some(a), Some(b)) if a == b => 1.0,
_ => 0.0,
}
}
pub fn tool(categories: &[String]) -> Tool {
answer_tool(
"return_category",
"Return one of the predefined categories.".to_string(),
"category",
json!({ "type": "STRING", "enum": categories, "description": "The selected category." }),
)
}
pub fn usage(categories: &[String]) -> String {
format!(
"Use the tool \"return_category\" to return your answer as one of the categories: {}.",
json!(categories)
)
}
}
pub struct SelectionFormat {
pub instruction: String,
pub tool: Tool,
pub usage: String,
response: Option<Vec<String>>,
options: Vec<String>,
}
impl SelectionFormat {
pub fn new(instruction: &str, options: Vec<String>) -> Self {
SelectionFormat {
instruction: instruction.to_string(),
tool: SelectionFormat::tool(&options),
usage: SelectionFormat::usage(&options),
response: None,
options,
}
}
#[allow(clippy::should_implement_trait)]
pub fn clone(&self) -> Self {
SelectionFormat::new(&self.instruction, self.options.clone())
}
pub fn answer(&mut self, response: Vec<String>) {
self.response = Some(response);
}
pub async fn llm(
&mut self,
authorization: &CredentialsOrApiKey,
model: Text,
options: LlmOptions,
) -> Result<TextResponse> {
let (response, answer) = ask(
&self.instruction,
&self.usage,
&self.tool,
authorization,
model,
options,
)
.await?;
if let Some(answer) = answer {
self.response = read(answer);
}
Ok(response)
}
pub fn get_options(&self) -> &[String] {
&self.options
}
pub fn get_response(&self) -> Option<Vec<String>> {
Some(
self.response
.iter()
.flatten()
.filter(|selection| self.options.contains(selection))
.cloned()
.collect(),
)
}
pub fn to_json(&self) -> Value {
object(vec![
("type", Some(Value::from("selection"))),
("instruction", Some(Value::from(self.instruction.as_str()))),
("options", Some(json!(self.options))),
("answer", self.get_response().map(Value::from)),
])
}
pub fn to_vector(&self) -> Vec<f64> {
let selections = self.get_response().unwrap_or_default();
if selections.is_empty() {
return Vec::new();
}
let mut vector = vec![0.0; self.options.len()];
let mut count = 0;
for selection in &selections {
if let Some(index) = self.options.iter().position(|option| option == selection) {
vector[index] = 1.0;
count += 1;
}
}
if count == 0 {
return Vec::new();
}
let scale = 1.0 / (count as f64).sqrt();
vector.iter().map(|x| x * scale).collect()
}
pub fn distance(a: &SelectionFormat, b: &SelectionFormat) -> f64 {
let selections_a = a.get_response().unwrap_or_default();
let selections_b = b.get_response().unwrap_or_default();
if selections_a.is_empty() && selections_b.is_empty() {
return 1.0;
}
if selections_a.is_empty() || selections_b.is_empty() {
return 0.0;
}
let set_a: std::collections::HashSet<&String> = selections_a.iter().collect();
let set_b: std::collections::HashSet<&String> = selections_b.iter().collect();
let intersection_size = set_a.intersection(&set_b).count();
let union_size = set_a.union(&set_b).count();
intersection_size as f64 / union_size as f64
}
pub fn tool(options: &[String]) -> Tool {
answer_tool(
"return_selections",
"Return one or more selected options.".to_string(),
"selections",
json!({
"type": "ARRAY",
"items": { "type": "STRING", "enum": options },
"description": "The selected options."
}),
)
}
pub fn usage(options: &[String]) -> String {
format!(
"Use the tool \"return_selections\" to return your answer as a categorical vector of one or more in {}",
json!(options)
)
}
}
pub struct UtteranceFormat {
pub instruction: String,
pub tool: Tool,
pub usage: String,
response: Option<String>,
pub time: Option<f64>,
pub embedding: Option<Vec<f64>>,
}
impl UtteranceFormat {
pub fn new(instruction: &str, time: Option<f64>) -> Self {
UtteranceFormat {
instruction: instruction.to_string(),
tool: UtteranceFormat::tool(time),
usage: UtteranceFormat::usage(time),
response: None,
time,
embedding: None,
}
}
#[allow(clippy::should_implement_trait)]
pub fn clone(&self) -> Self {
UtteranceFormat::new(&self.instruction, self.time)
}
pub fn answer(&mut self, response: String) {
self.response = Some(response);
}
pub async fn llm(
&mut self,
authorization: &CredentialsOrApiKey,
model: Text,
options: LlmOptions,
) -> Result<TextResponse> {
let (response, answer) = ask(
&self.instruction,
&self.usage,
&self.tool,
authorization,
model,
options,
)
.await?;
if let Some(answer) = answer {
self.response = read(answer);
}
Ok(response)
}
pub fn get_response(&self) -> Option<String> {
self.response.clone()
}
pub fn to_json(&self) -> Value {
object(vec![
("type", Some(Value::from("utterance"))),
("instruction", Some(Value::from(self.instruction.as_str()))),
("time", self.time.map(Value::from)),
("answer", self.get_response().map(Value::from)),
])
}
pub fn to_vector(&self) -> Vec<f64> {
unit(self.embedding.as_deref().unwrap_or_default())
}
pub async fn embed(
&mut self,
authorization: &CredentialsOrApiKey,
model: Embedding,
) -> Result<()> {
let Some(utterance) = self.get_response() else {
return Err(Error::Message(
"Cannot embed an utterance format without an answer.".to_string(),
));
};
let result = generate_embedding(authorization, model, &utterance, None).await?;
self.embedding = Some(result.embedding);
Ok(())
}
pub fn distance(a: &UtteranceFormat, b: &UtteranceFormat) -> Result<f64> {
fn linear_cosine_similarity(a: &[f64], b: &[f64]) -> f64 {
let mut dot_product = 0.0;
let mut norm_a = 0.0;
let mut norm_b = 0.0;
for (index, &x) in a.iter().enumerate() {
let y = b.get(index).copied().unwrap_or(f64::NAN);
dot_product += x * y;
norm_a += x * x;
norm_b += y * y;
}
let norm_a: f64 = f64::sqrt(norm_a);
let norm_b: f64 = f64::sqrt(norm_b);
let similarity =
if norm_a != 0.0 && norm_b != 0.0 && !norm_a.is_nan() && !norm_b.is_nan() {
dot_product / (norm_a * norm_b)
} else {
0.0
};
1.0 - similarity.clamp(-1.0, 1.0).acos() / std::f64::consts::PI
}
match (&a.embedding, &b.embedding) {
(Some(a), Some(b)) => Ok(linear_cosine_similarity(a, b)),
_ => Err(Error::Message(
"Both utterance formats must be embedded before computing distance. Call embed() first."
.to_string(),
)),
}
}
pub fn tool(time: Option<f64>) -> Tool {
let time = time.filter(|time| *time != 0.0 && !time.is_nan());
answer_tool(
"return_text",
format!(
"Return a free-form text response {}.",
time.map_or(String::new(), |time| format!(" within {time} seconds)"))
),
"content",
json!({ "type": "STRING", "description": "The text response." }),
)
}
pub fn usage(time: Option<f64>) -> String {
let time = time.filter(|time| *time != 0.0 && !time.is_nan());
format!(
"Use the tool \"return_text\" to return your answer as a string of {}.",
time.map_or("any length".to_string(), |time| format!(
"length within {time} seconds"
))
)
}
}