molo 0.2.2

//! Conversation messages.
//!
//! The message data model implements serde serialization / deserialization:
//! session persistence and cross-process transport (tool definitions and
//! messages) serialize these types directly, no manual mapping needed.
//!
//! A full conversation history is expressed as a [`Message`] sequence; each
//! message consists of [content blocks](ContentBlock), currently text only.
//! The structured entry point of the content model is [`ContentBlock`] — to
//! add multimodal content (images / files), add a variant there; the shape
//! of [`Message`] stays unchanged, and consumers just match the new variant.

use serde::{Deserialize, Serialize};

/// A tool call requested by the model.
///
/// The model requests a tool call via the `tool_calls` field of
/// [`Message::Assistant`]; after the agent loop executes it, the result is
/// passed back as a [`Message::ToolResult`] message right after, paired
/// with this call by `id` (which disambiguates multiple calls to the
/// same-named tool in one turn).
///
/// # Example
///
/// Construct a tool request and pair it with the returned execution result
/// (in real flows the request is generated by the model and passed back
/// automatically after the loop executes it):
///
/// ```
/// use molo::{Message, ToolCall};
///
/// let request = Message::Assistant {
///     content: String::new(),
///     reasoning: None,
///     tool_calls: vec![ToolCall {
///         id: "call_1".into(),
///         name: "weather".into(),
///         arguments: r#"{"city":"Beijing"}"#.into(),
///     }],
/// };
/// let result = Message::tool_result("call_1", "Sunny, 23°C");
///
/// let Message::Assistant { tool_calls, .. } = &request else {
///     panic!("expected an assistant message");
/// };
/// assert_eq!(tool_calls[0].id, "call_1");
/// assert_eq!(result, Message::tool_result("call_1", "Sunny, 23°C"));
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ToolCall {
    /// Unique id of this call; the execution result is paired with it via
    /// the `id` of [`Message::ToolResult`].
    pub id: String,
    /// Tool name, matching the `name` of the tool definition
    /// [`Tool::schema`](crate::Tool::schema).
    pub name: String,
    /// Model-generated arguments (JSON text), parsed by the agent loop and
    /// handed to the tool for execution.
    pub arguments: String,
}

/// A single message in a conversation.
///
/// This type carries context uniformly between Provider / Memory / Agent:
/// what Memory stores and returns, and what Provider sends and receives,
/// are all [`Message`] sequences; Provider implementations map them to the
/// vendor's wire format.
///
/// Note: the model may request several tools in one turn, and these requests
/// **must stay in a single [`Message::Assistant`] message** — splitting them
/// across messages breaks vendor wire validation (some vendors require tool
/// results to immediately follow the assistant message carrying them, e.g.
/// DeepSeek).
///
/// # Example
///
/// Organize a conversation history with the convenience constructors (in
/// real scenarios the agent loop and Memory do this automatically):
///
/// ```
/// use molo::Message;
///
/// let history = vec![
///     Message::system("You are a helpful assistant"),
///     Message::user("How is the weather in Beijing today?"),
///     Message::assistant("Let me check the weather."),
///     Message::tool_result("call_1", "Sunny, 23°C"),
/// ];
///
/// assert_eq!(history.len(), 4);
/// assert_eq!(history[1], Message::user("How is the weather in Beijing today?"));
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum Message {
    /// System instruction describing the agent's role and behavior
    /// constraints.
    System(String),
    /// User input, made of content blocks (currently text only; multimodal
    /// blocks are added as real needs arise).
    User(Vec<ContentBlock>),
    /// Assistant reply: text + reasoning + requested tool calls (multiple
    /// requests in one turn stay together).
    Assistant {
        /// Reply text.
        content: String,
        /// The model's reasoning; provided by thinking models (e.g.
        /// DeepSeek / Qwen3), `None` for other models.
        ///
        /// This field is a vendor extension and **must be passed back
        /// verbatim when sending the conversation history**, otherwise the
        /// API rejects the request (e.g. DeepSeek reports
        /// "The reasoning_content in the thinking mode must be passed back to the API.").
        reasoning: Option<String>,
        /// Tools requested by the model with this reply; execution results
        /// are passed back right after as [`Message::ToolResult`] messages.
        tool_calls: Vec<ToolCall>,
    },
    /// Tool execution result, passed back to the model.
    ToolResult {
        /// The id corresponding to [`ToolCall::id`].
        id: String,
        /// Text of the execution result (on failure, the error text; the
        /// model decides what to do next).
        content: String,
    },
}

/// A content block within a message.
///
/// The structured entry point of the content model: currently text only; to
/// add multimodal content (images / files), add a variant here — the shape
/// of [`Message`] stays unchanged, and consumers just match the new variant.
///
/// # Example
///
/// ```
/// use molo::{ContentBlock, Message};
///
/// let msg = Message::user_blocks(vec![
///     ContentBlock::Text("How is the weather in Beijing today?".into()),
/// ]);
///
/// assert_eq!(msg, Message::user("How is the weather in Beijing today?"));
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum ContentBlock {
    /// A text block.
    Text(String),
}

impl Message {
    /// A system instruction message.
    pub fn system(content: impl Into<String>) -> Self {
        Self::System(content.into())
    }

    /// A plain-text user message (a single text block, equivalent to
    /// `user_blocks(vec![ContentBlock::Text(content)])`).
    pub fn user(content: impl Into<String>) -> Self {
        Self::User(vec![ContentBlock::Text(content.into())])
    }

    /// User input made of content blocks (currently text only; multimodal
    /// blocks are added as real needs arise).
    pub fn user_blocks(blocks: Vec<ContentBlock>) -> Self {
        Self::User(blocks)
    }

    /// An assistant reply message (no reasoning, no tool requests).
    pub fn assistant(content: impl Into<String>) -> Self {
        Self::Assistant {
            content: content.into(),
            reasoning: None,
            tool_calls: Vec::new(),
        }
    }

    /// An assistant reply with reasoning (for thinking models; pass
    /// `reasoning` back verbatim when sending history, otherwise the API
    /// rejects the request).
    pub fn assistant_with_reasoning(
        content: impl Into<String>,
        reasoning: impl Into<String>,
    ) -> Self {
        Self::Assistant {
            content: content.into(),
            reasoning: Some(reasoning.into()),
            tool_calls: Vec::new(),
        }
    }

    /// A tool execution result passed back to the model; `id` corresponds to
    /// the [`ToolCall::id`] in the [`Message::Assistant`] message that
    /// carried the request.
    ///
    /// # Example
    ///
    /// ```
    /// use molo::Message;
    ///
    /// let result = Message::tool_result("call_1", "Sunny, 23°C");
    /// assert_eq!(result, Message::ToolResult {
    ///     id: "call_1".into(),
    ///     content: "Sunny, 23°C".into(),
    /// });
    /// ```
    pub fn tool_result(id: impl Into<String>, content: impl Into<String>) -> Self {
        Self::ToolResult {
            id: id.into(),
            content: content.into(),
        }
    }
}