use std::error::Error;
use std::fmt::{self, Debug, Display, Formatter};
use crate::opaque::Payload;
use crate::redact;
use super::content::{self, Metadata, Part};
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Id(String);
impl Id {
#[must_use]
pub const fn new(value: String) -> Self {
Self(value)
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
#[must_use]
pub fn into_string(self) -> String {
self.0
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Name(String);
impl Name {
#[must_use]
pub const fn new(value: String) -> Self {
Self(value)
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
#[must_use]
pub fn into_string(self) -> String {
self.0
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ToolCall {
id: Id,
name: Name,
arguments: Payload,
}
impl ToolCall {
#[must_use]
pub const fn new(id: Id, name: Name, arguments: Payload) -> Self {
Self {
id,
name,
arguments,
}
}
#[must_use]
pub const fn id(&self) -> &Id {
&self.id
}
#[must_use]
pub const fn name(&self) -> &Name {
&self.name
}
#[must_use]
pub const fn arguments(&self) -> &Payload {
&self.arguments
}
#[must_use]
pub fn into_parts(self) -> (Id, Name, Payload) {
(self.id, self.name, self.arguments)
}
}
#[derive(Clone, Debug)]
pub struct ToolPart(Part);
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum ToolPartError {
UnknownKind(i64),
}
impl Display for ToolPartError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::UnknownKind(kind) => write!(formatter, "unknown tool part kind {kind}"),
}
}
}
impl Error for ToolPartError {}
impl ToolPart {
pub fn try_from_part(part: Part) -> Result<Self, ToolPartError> {
let kind = part.kind();
if kind.known().is_some() {
Ok(Self(part))
} else {
Err(ToolPartError::UnknownKind(kind.as_i64()))
}
}
#[must_use]
pub const fn as_part(&self) -> &Part {
&self.0
}
#[must_use]
pub fn into_part(self) -> Part {
self.0
}
}
#[derive(Clone, Debug)]
pub enum MetadataPresence {
Absent,
PresentNull,
Present(Metadata),
}
#[derive(Clone)]
pub struct ToolOutput {
model_content: Vec<ToolPart>,
user_view: Option<String>,
log_preview: Option<String>,
metadata: MetadataPresence,
}
impl Debug for ToolOutput {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ToolOutput")
.field("model_content", &self.model_content)
.field(
"user_view",
&self
.user_view
.as_deref()
.map(|view| redact::Bytes(view.len())),
)
.field(
"log_preview",
&self
.log_preview
.as_deref()
.map(|preview| redact::Bytes(preview.len())),
)
.field("metadata", &self.metadata)
.finish()
}
}
impl ToolOutput {
#[must_use]
pub const fn new(
model_content: Vec<ToolPart>,
user_view: Option<String>,
log_preview: Option<String>,
metadata: MetadataPresence,
) -> Self {
Self {
model_content,
user_view,
log_preview,
metadata,
}
}
#[must_use]
pub fn model_content(&self) -> &[ToolPart] {
&self.model_content
}
#[must_use]
pub fn user_view(&self) -> Option<&str> {
self.user_view.as_deref()
}
#[must_use]
pub fn log_preview(&self) -> Option<&str> {
self.log_preview.as_deref()
}
#[must_use]
pub const fn metadata(&self) -> &MetadataPresence {
&self.metadata
}
#[must_use]
pub fn into_parts(
self,
) -> (
Vec<ToolPart>,
Option<String>,
Option<String>,
MetadataPresence,
) {
(
self.model_content,
self.user_view,
self.log_preview,
self.metadata,
)
}
}
#[derive(Clone, Debug, Default)]
pub enum ToolResult {
#[default]
NoOutput,
Success(ToolOutput),
BusinessError(ToolOutput),
}
impl ToolResult {
#[must_use]
pub const fn no_output() -> Self {
Self::NoOutput
}
#[must_use]
pub const fn success(output: ToolOutput) -> Self {
Self::Success(output)
}
#[must_use]
pub const fn business_error(output: ToolOutput) -> Self {
Self::BusinessError(output)
}
#[must_use]
pub fn success_text(text: String) -> Self {
Self::Success(text_output(text))
}
#[must_use]
pub fn error_text(text: String) -> Self {
Self::BusinessError(text_output(text))
}
#[must_use]
pub const fn has_output(&self) -> bool {
!matches!(self, Self::NoOutput)
}
#[must_use]
pub const fn is_business_error(&self) -> bool {
matches!(self, Self::BusinessError(_))
}
#[must_use]
pub const fn output(&self) -> Option<&ToolOutput> {
match self {
Self::NoOutput => None,
Self::Success(output) | Self::BusinessError(output) => Some(output),
}
}
#[must_use]
pub fn to_plain_text(&self) -> String {
match self.output() {
None => String::new(),
Some(output) => output.user_view().map_or_else(
|| {
content::join_blocks(
output
.model_content()
.iter()
.map(|part| part.as_part().fields().text()),
)
},
ToOwned::to_owned,
),
}
}
}
fn text_output(text: String) -> ToolOutput {
let preview = bounded_preview(&text);
let model_text = text.clone();
ToolOutput::new(
vec![ToolPart(Part::text(model_text))],
Some(text),
Some(preview),
MetadataPresence::Absent,
)
}
fn bounded_preview(text: &str) -> String {
const LIMIT: usize = 200;
if text.len() <= LIMIT {
return text.to_owned();
}
let mut end = LIMIT;
while !text.is_char_boundary(end) {
end -= 1;
}
let mut preview = text[..end].to_owned();
preview.push('…');
preview
}
#[cfg(feature = "serde")]
mod serde_impl {
use std::fmt::{self, Formatter};
use serde_core::de::{
Deserialize, Deserializer, EnumAccess, Error as DeError, MapAccess, SeqAccess,
VariantAccess, Visitor,
};
use serde_core::ser::{Serialize, SerializeStruct, Serializer};
use super::{Id, MetadataPresence, Name, ToolCall, ToolOutput, ToolPart, ToolResult};
use crate::value::content::Part;
use crate::wire::{self, IdentifierSeed};
const CALL_FIELDS: &[&str] = &["id", "name", "arguments"];
const OUTPUT_FIELDS: &[&str] = &["model_content", "user_view", "log_preview", "metadata"];
const PRESENCE_NAME: &str = "MetadataPresence";
const PRESENCE_VARIANTS: &[&str] = &["absent", "present_null", "present"];
const RESULT_NAME: &str = "ToolResult";
const RESULT_VARIANTS: &[&str] = &["no_output", "success", "business_error"];
impl Serialize for Id {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.serialize_str(&self.0)
}
}
impl<'de> Deserialize<'de> for Id {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
String::deserialize(deserializer).map(Self::new)
}
}
impl Serialize for Name {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.serialize_str(&self.0)
}
}
impl<'de> Deserialize<'de> for Name {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
String::deserialize(deserializer).map(Self::new)
}
}
impl Serialize for ToolCall {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
let mut record = serializer.serialize_struct("ToolCall", 3)?;
record.serialize_field("id", &self.id)?;
record.serialize_field("name", &self.name)?;
record.serialize_field("arguments", &self.arguments)?;
record.end()
}
}
impl<'de> Deserialize<'de> for ToolCall {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
deserializer.deserialize_struct("ToolCall", CALL_FIELDS, CallVisitor)
}
}
struct CallVisitor;
impl<'de> Visitor<'de> for CallVisitor {
type Value = ToolCall;
fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter.write_str("a tool invocation")
}
fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
where
A: SeqAccess<'de>,
{
let id = wire::element(&mut sequence, 0)?;
let name = wire::element(&mut sequence, 1)?;
let arguments = wire::element(&mut sequence, 2)?;
wire::end(&mut sequence, 3)?;
Ok(ToolCall::new(id, name, arguments))
}
fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
where
A: MapAccess<'de>,
{
let mut id = None;
let mut name = None;
let mut arguments = None;
while let Some(field) = entries.next_key_seed(IdentifierSeed(CALL_FIELDS))? {
match field.0.as_str() {
"id" => wire::accept(&mut id, entries.next_value()?, "id")?,
"name" => wire::accept(&mut name, entries.next_value()?, "name")?,
"arguments" => {
wire::accept(&mut arguments, entries.next_value()?, "arguments")?;
}
unknown => return Err(A::Error::unknown_field(unknown, CALL_FIELDS)),
}
}
Ok(ToolCall::new(
wire::require(id, "id")?,
wire::require(name, "name")?,
wire::require(arguments, "arguments")?,
))
}
}
impl Serialize for ToolPart {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
self.0.serialize(serializer)
}
}
impl<'de> Deserialize<'de> for ToolPart {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
let part = Part::deserialize(deserializer)?;
Self::try_from_part(part).map_err(D::Error::custom)
}
}
impl Serialize for MetadataPresence {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
match self {
Self::Absent => serializer.serialize_unit_variant(PRESENCE_NAME, 0, "absent"),
Self::PresentNull => {
serializer.serialize_unit_variant(PRESENCE_NAME, 1, "present_null")
}
Self::Present(metadata) => {
serializer.serialize_newtype_variant(PRESENCE_NAME, 2, "present", metadata)
}
}
}
}
impl<'de> Deserialize<'de> for MetadataPresence {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
deserializer.deserialize_enum(PRESENCE_NAME, PRESENCE_VARIANTS, PresenceVisitor)
}
}
struct PresenceVisitor;
impl<'de> Visitor<'de> for PresenceVisitor {
type Value = MetadataPresence;
fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter.write_str("a tool-result metadata presence state")
}
fn visit_enum<A>(self, data: A) -> Result<Self::Value, A::Error>
where
A: EnumAccess<'de>,
{
let (tag, variant) = data.variant_seed(IdentifierSeed(PRESENCE_VARIANTS))?;
match tag.0.as_str() {
"absent" => {
variant.unit_variant()?;
Ok(MetadataPresence::Absent)
}
"present_null" => {
variant.unit_variant()?;
Ok(MetadataPresence::PresentNull)
}
"present" => variant.newtype_variant().map(MetadataPresence::Present),
unknown => Err(A::Error::unknown_variant(unknown, PRESENCE_VARIANTS)),
}
}
}
impl Serialize for ToolOutput {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
let mut record = serializer.serialize_struct("ToolOutput", 4)?;
record.serialize_field("model_content", &self.model_content)?;
record.serialize_field("user_view", &self.user_view)?;
record.serialize_field("log_preview", &self.log_preview)?;
record.serialize_field("metadata", &self.metadata)?;
record.end()
}
}
impl<'de> Deserialize<'de> for ToolOutput {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
deserializer.deserialize_struct("ToolOutput", OUTPUT_FIELDS, OutputVisitor)
}
}
struct OutputVisitor;
impl<'de> Visitor<'de> for OutputVisitor {
type Value = ToolOutput;
fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter.write_str("a tool output payload")
}
fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
where
A: SeqAccess<'de>,
{
let model_content = wire::element(&mut sequence, 0)?;
let user_view = wire::element(&mut sequence, 1)?;
let log_preview = wire::element(&mut sequence, 2)?;
let metadata = wire::element(&mut sequence, 3)?;
wire::end(&mut sequence, 4)?;
Ok(ToolOutput::new(
model_content,
user_view,
log_preview,
metadata,
))
}
fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
where
A: MapAccess<'de>,
{
let mut model_content = None;
let mut user_view = None;
let mut log_preview = None;
let mut metadata = None;
while let Some(field) = entries.next_key_seed(IdentifierSeed(OUTPUT_FIELDS))? {
match field.0.as_str() {
"model_content" => {
wire::accept(&mut model_content, entries.next_value()?, "model_content")?;
}
"user_view" => {
wire::accept(&mut user_view, entries.next_value()?, "user_view")?;
}
"log_preview" => {
wire::accept(&mut log_preview, entries.next_value()?, "log_preview")?;
}
"metadata" => wire::accept(&mut metadata, entries.next_value()?, "metadata")?,
unknown => return Err(A::Error::unknown_field(unknown, OUTPUT_FIELDS)),
}
}
Ok(ToolOutput::new(
wire::require(model_content, "model_content")?,
wire::require(user_view, "user_view")?,
wire::require(log_preview, "log_preview")?,
wire::require(metadata, "metadata")?,
))
}
}
impl Serialize for ToolResult {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
match self {
Self::NoOutput => serializer.serialize_unit_variant(RESULT_NAME, 0, "no_output"),
Self::Success(output) => {
serializer.serialize_newtype_variant(RESULT_NAME, 1, "success", output)
}
Self::BusinessError(output) => {
serializer.serialize_newtype_variant(RESULT_NAME, 2, "business_error", output)
}
}
}
}
impl<'de> Deserialize<'de> for ToolResult {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
deserializer.deserialize_enum(RESULT_NAME, RESULT_VARIANTS, ResultVisitor)
}
}
struct ResultVisitor;
impl<'de> Visitor<'de> for ResultVisitor {
type Value = ToolResult;
fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter.write_str("a closed tool result")
}
fn visit_enum<A>(self, data: A) -> Result<Self::Value, A::Error>
where
A: EnumAccess<'de>,
{
let (tag, variant) = data.variant_seed(IdentifierSeed(RESULT_VARIANTS))?;
match tag.0.as_str() {
"no_output" => {
variant.unit_variant()?;
Ok(ToolResult::no_output())
}
"success" => variant.newtype_variant().map(ToolResult::success),
"business_error" => variant.newtype_variant().map(ToolResult::business_error),
unknown => Err(A::Error::unknown_variant(unknown, RESULT_VARIANTS)),
}
}
}
}