ai_sdk_provider/language_model/

content.rs

use super::tool_result_output::ToolResultOutput;
use crate::SharedProviderMetadata;
use serde::{Deserialize, Serialize};

/// Represents a single content element in a language model's response or message.
///
/// Content can take multiple forms depending on what the model generates or what is included
/// in a message. This enum provides a unified interface for handling different types of content
/// including text, files, tool calls, and citations.
///
/// # Variants
///
/// * `Text` - Plain text content generated by the model
/// * `Reasoning` - Internal reasoning content from specialized reasoning models (e.g., o1)
/// * `File` - Media content including images, audio, video, or other file types
/// * `Source` - Citation or reference to an external source document
/// * `ToolCall` - A tool/function call invocation from the model
/// * `ToolResult` - The result of executing a tool or function
///
/// # Usage
///
/// Content elements are typically generated as part of a larger response and should be
/// examined to determine the appropriate handling for each type.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "kebab-case")]
pub enum Content {
    /// Plain text content generated by the model
    Text(TextPart),
    /// Internal reasoning content from specialized reasoning models
    Reasoning(ReasoningPart),
    /// Media content including images, audio, video, or other file types
    File(FilePart),
    /// Citation or reference to an external source document
    Source(SourcePart),
    /// A tool or function call invocation from the model
    ToolCall(ToolCallPart),
    /// The result of executing a tool or function
    ToolResult(ToolResultPart),
}

/// Plain text content part from a language model response.
///
/// Represents textual content generated by the model. This is the most common content type
/// and contains the main textual output of the language model.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TextPart {
    /// The actual text content
    pub text: String,

    /// Optional provider-specific metadata that may include usage information, model details,
    /// or other provider-specific properties
    #[serde(skip_serializing_if = "Option::is_none")]
    pub provider_metadata: Option<SharedProviderMetadata>,
}

/// Internal reasoning content from advanced reasoning models.
///
/// Some specialized language models (such as o1) expose their internal reasoning process
/// as structured content. This part contains the model's step-by-step reasoning before
/// providing its final answer. Useful for understanding model behavior and debugging.
///
/// Note: Not all models support reasoning content. It will only be present when using
/// models that are specifically designed for reasoning tasks.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ReasoningPart {
    /// The reasoning text describing the model's internal thought process
    pub reasoning: String,

    /// Optional provider-specific metadata
    #[serde(skip_serializing_if = "Option::is_none")]
    pub provider_metadata: Option<SharedProviderMetadata>,
}

/// File or media content part from a language model response.
///
/// Represents binary files, images, audio, video, or other media content generated or
/// referenced by the model. The content can be provided as raw binary data or as a URL
/// pointing to the file location.
///
/// # Example Use Cases
///
/// - Images generated by vision models
/// - Audio files from speech synthesis models
/// - Documents or archives created by processing models
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FilePart {
    /// File data, either as raw binary bytes or as a URL
    pub data: super::FileData,

    /// MIME type identifier (e.g., "image/jpeg", "audio/mp3", "application/pdf")
    pub media_type: String,

    /// Optional provider-specific metadata
    #[serde(skip_serializing_if = "Option::is_none")]
    pub provider_metadata: Option<SharedProviderMetadata>,
}

/// Citation or reference to an external source document.
///
/// When a model retrieves or references external sources (e.g., from a knowledge base,
/// search results, or document repository), it includes source citations in the response.
/// These allow you to trace the origins of information and verify facts used by the model.
///
/// # Fields
///
/// * `source_type` - The category of source (URL-based or document-based)
/// * `id` - Unique identifier for the source within the response
/// * `url` - Optional direct link to access the source
/// * `title` - Optional human-readable title or name of the source
/// * `provider_metadata` - Optional provider-specific details about the source
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SourcePart {
    /// Categorizes the source as either URL-based or document-based
    pub source_type: SourceType,
    /// Unique identifier for this source citation
    pub id: String,

    /// Optional URL pointing directly to the source material
    #[serde(skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,

    /// Optional descriptive title or name of the source
    #[serde(skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,

    /// Optional provider-specific metadata about the source
    #[serde(skip_serializing_if = "Option::is_none")]
    pub provider_metadata: Option<SharedProviderMetadata>,
}

/// Categorizes the type of source being cited.
///
/// Distinguishes between different source origins to help determine how to access
/// or display the referenced material.
///
/// # Variants
///
/// * `Url` - Source is accessible via a direct HTTP/HTTPS URL
/// * `Document` - Source is a document stored in a knowledge base or document repository
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum SourceType {
    /// Source is accessible via a direct HTTP/HTTPS URL
    Url,
    /// Source is a document stored in a knowledge base or document repository
    Document,
}

/// A request from the language model to invoke an external tool or function.
///
/// When a model detects that it needs to call a tool to accomplish a task, it emits
/// a tool call with the tool name and arguments. The application is responsible for
/// executing the tool and returning the results via a ToolResultPart.
///
/// # Fields
///
/// * `tool_call_id` - Unique identifier for correlating this call with its result
/// * `tool_name` - Name of the tool to invoke (must match a provided tool definition)
/// * `input` - Stringified JSON containing the tool arguments
/// * `provider_executed` - If true, the provider automatically executed the tool
/// * `dynamic` - If true, indicates a dynamic or runtime-generated tool call
/// * `provider_metadata` - Optional provider-specific details
///
/// # Processing Tool Calls
///
/// When you receive a tool call, you should:
/// 1. Extract the tool name and arguments
/// 2. Locate the corresponding tool definition
/// 3. Execute the tool with the provided arguments
/// 4. Return a ToolResultPart with the results
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ToolCallPart {
    /// Unique identifier that correlates this tool call with its result
    pub tool_call_id: String,
    /// Name identifying which tool should be invoked
    pub tool_name: String,
    /// Stringified JSON containing the arguments for the tool
    pub input: String,

    /// Indicates whether the provider has already executed this tool
    #[serde(skip_serializing_if = "Option::is_none")]
    pub provider_executed: Option<bool>,

    /// Indicates whether this is a dynamic or runtime-generated tool call
    #[serde(skip_serializing_if = "Option::is_none")]
    pub dynamic: Option<bool>,

    /// Optional provider-specific metadata about the tool call
    #[serde(skip_serializing_if = "Option::is_none")]
    pub provider_metadata: Option<SharedProviderMetadata>,
}

/// The result of executing a tool or function in response to a model's tool call.
///
/// After the model requests a tool invocation via ToolCallPart, the results of that
/// execution are communicated back through this message type. It contains the output
/// from the tool execution, which may be text, structured data, or an error message.
///
/// # Fields
///
/// * `tool_call_id` - References the ToolCallPart this result corresponds to
/// * `tool_name` - Name of the tool that was executed
/// * `output` - The result from tool execution (text, structured, or error)
/// * `preliminary` - If true, this is a partial result; more results may follow
/// * `provider_metadata` - Optional provider-specific details about execution
///
/// # Including Tool Results in Messages
///
/// Tool results must be included in the message history when making subsequent
/// requests, so the model can see what happened and make appropriate follow-up decisions.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ToolResultPart {
    /// Identifier linking this result to the corresponding tool call
    pub tool_call_id: String,
    /// Name of the tool that was executed
    pub tool_name: String,
    /// The structured output or result from executing the tool
    pub output: ToolResultOutput,

    /// If true, this is a preliminary result and more results may be forthcoming
    #[serde(skip_serializing_if = "Option::is_none")]
    pub preliminary: Option<bool>,

    /// Optional provider-specific metadata about the tool execution
    #[serde(skip_serializing_if = "Option::is_none")]
    pub provider_metadata: Option<SharedProviderMetadata>,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_content_text_serialization() {
        let content = Content::Text(TextPart {
            text: "Hello".into(),
            provider_metadata: None,
        });
        let json = serde_json::to_value(&content).unwrap();
        assert_eq!(json["type"], "text");
        assert_eq!(json["text"], "Hello");
    }

    #[test]
    fn test_content_tool_call() {
        let content = Content::ToolCall(ToolCallPart {
            tool_call_id: "call-123".into(),
            tool_name: "search".into(),
            input: r#"{"query":"test"}"#.into(),
            provider_executed: None,
            dynamic: None,
            provider_metadata: None,
        });
        let json = serde_json::to_value(&content).unwrap();
        assert_eq!(json["type"], "tool-call");
        assert_eq!(json["toolCallId"], "call-123");
        assert_eq!(json["toolName"], "search");
    }

    #[test]
    fn test_content_reasoning() {
        let content = Content::Reasoning(ReasoningPart {
            reasoning: "Let me think...".into(),
            provider_metadata: None,
        });
        let json = serde_json::to_value(&content).unwrap();
        assert_eq!(json["type"], "reasoning");
        assert_eq!(json["reasoning"], "Let me think...");
    }

    #[test]
    fn test_source_type_serialization() {
        let source = SourcePart {
            source_type: SourceType::Url,
            id: "src-1".into(),
            url: Some("https://example.com".into()),
            title: None,
            provider_metadata: None,
        };
        let json = serde_json::to_value(&source).unwrap();
        assert_eq!(json["sourceType"], "url");
    }

    #[test]
    fn test_tool_result_text_output() {
        let result = ToolResultPart {
            tool_call_id: "call-123".into(),
            tool_name: "test_tool".into(),
            output: ToolResultOutput::Text {
                value: "success".into(),
                provider_metadata: None,
            },
            preliminary: None,
            provider_metadata: None,
        };
        let json = serde_json::to_value(&result).unwrap();
        assert_eq!(json["toolName"], "test_tool");
        assert_eq!(json["output"]["type"], "text");
        assert_eq!(json["output"]["value"], "success");
    }

    #[test]
    fn test_tool_result_error_output() {
        let result = ToolResultPart {
            tool_call_id: "call-123".into(),
            tool_name: "test_tool".into(),
            output: ToolResultOutput::ErrorText {
                value: "error occurred".into(),
                provider_metadata: None,
            },
            preliminary: None,
            provider_metadata: None,
        };
        let json = serde_json::to_value(&result).unwrap();
        assert_eq!(json["output"]["type"], "error-text");
        assert_eq!(json["output"]["value"], "error occurred");
        assert_eq!(json["toolName"], "test_tool");
    }
}