bunsen-tool 0.43.0

bunsen's models on the command line: speech to text (Parakeet, Qwen3-ASR, Voxtral Realtime, Whisper) and who spoke when (Sortformer), text to speech (ZONOS3, Qwen3-TTS), chat (Qwen3, Qwen3.5, Gemma, nanochat) and typed decisions (Laya). The chat driver is also a library, `bunsen_tool::chat`.
Documentation
//! nanochat's conversation layout: a conversation as the ids its model reads.
use bunsen::{
    errors::{
        BunsenError,
        BunsenResult,
    },
    kits::support::tokens::Tokenizer,
};

use crate::chat::ChatMessage;

/// nanochat's conversation layout, as upstream's tokenizer renders one
/// (`render_conversation`, and `render_for_completion` for the assistant's
/// next turn): `<|bos|>`, then each user turn between `<|user_start|>` and
/// `<|user_end|>` and each assistant turn between `<|assistant_start|>` and
/// `<|assistant_end|>`, the turns alternating from a user's; a system
/// message is folded into the first user turn, `system + "\n\n" + user`.
/// The markers are their special tokens, and a message's text is encoded as
/// text, a special token's spelling included
/// ([`encode_plain`](Tokenizer::encode_plain)).
///
/// Upstream's own tool calls (`<|python_start|>` and the calculator's
/// `<|output_start|>`) are its engine's, not the layout's: a reply that
/// opens one shows it as text.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct NanoChatLayout {
    /// `<|bos|>`: the conversation's first token, and a reply's end.
    pub bos: i64,
    /// `<|user_start|>`.
    pub user_start: i64,
    /// `<|user_end|>`.
    pub user_end: i64,
    /// `<|assistant_start|>`: the next turn's prompt ends with it.
    pub assistant_start: i64,
    /// `<|assistant_end|>`: a reply's end.
    pub assistant_end: i64,
}

impl NanoChatLayout {
    /// The layout of `tokenizer`'s special tokens.
    ///
    /// # Errors
    /// [`InvalidResource`](bunsen::errors::BunsenErrorKind::InvalidResource)
    /// naming a special token the tokenizer lacks.
    pub fn from_tokenizer(tokenizer: &dyn Tokenizer) -> BunsenResult<Self> {
        let special = |name: &str| {
            tokenizer.token_id(name).ok_or_else(|| {
                BunsenError::invalid_resource(format!("a nanochat tokenizer without {name}"))
            })
        };
        Ok(Self {
            bos: special("<|bos|>")?,
            user_start: special("<|user_start|>")?,
            user_end: special("<|user_end|>")?,
            assistant_start: special("<|assistant_start|>")?,
            assistant_end: special("<|assistant_end|>")?,
        })
    }

    /// The tokens that end a reply, as upstream's engine stops one:
    /// `<|assistant_end|>`, then `<|bos|>`.
    pub fn stop_ids(&self) -> Vec<i64> {
        vec![self.assistant_end, self.bos]
    }

    /// `messages` as the prompt of the assistant's next turn: upstream's
    /// `render_for_completion` of them.
    ///
    /// # Errors
    /// [`Illegal`](bunsen::errors::BunsenErrorKind::Illegal) when the
    /// conversation is empty, does not alternate from a user's turn (a system
    /// message first aside), or ends with the assistant's; as the tokenizer.
    pub fn render(
        &self,
        tokenizer: &dyn Tokenizer,
        messages: &[ChatMessage],
    ) -> BunsenResult<Vec<i64>> {
        let folded;
        let messages = match messages {
            [system, user, rest @ ..] if system.role == "system" => {
                if user.role != "user" {
                    return Err(BunsenError::illegal(
                        "a nanochat conversation's system message must be followed by a user's",
                    ));
                }
                folded = std::iter::once(ChatMessage::user(format!(
                    "{}\n\n{}",
                    system.content, user.content
                )))
                .chain(rest.iter().cloned())
                .collect::<Vec<_>>();
                folded.as_slice()
            }
            [system] if system.role == "system" => {
                return Err(BunsenError::illegal(
                    "a nanochat conversation's system message must be followed by a user's",
                ));
            }
            _ => messages,
        };
        match messages.last() {
            None => return Err(BunsenError::illegal("an empty nanochat conversation")),
            Some(last) if last.role != "user" => {
                return Err(BunsenError::illegal(
                    "a nanochat conversation to reply to ends with a user's turn",
                ));
            }
            Some(_) => {}
        }
        let mut ids = vec![self.bos];
        for (i, message) in messages.iter().enumerate() {
            let (role, start, end) = if i % 2 == 0 {
                ("user", self.user_start, self.user_end)
            } else {
                ("assistant", self.assistant_start, self.assistant_end)
            };
            if message.role != role {
                return Err(BunsenError::illegal(format!(
                    "a nanochat conversation's turn {i} is the {}'s, where it alternates to the {role}'s",
                    message.role
                )));
            }
            ids.push(start);
            ids.extend(tokenizer.encode_plain(&message.content)?);
            ids.push(end);
        }
        ids.push(self.assistant_start);
        Ok(ids)
    }
}

#[cfg(test)]
mod tests {
    use bunsen::{
        errors::{
            BunsenErrorKind,
            testing::ErrorMatcher,
        },
        kits::support::tokens::{
            BunsenTokenizer,
            testing::toy_tiktoken_pickle,
        },
    };

    use super::*;

    fn toy() -> (BunsenTokenizer, NanoChatLayout) {
        let tok = BunsenTokenizer::from_tiktoken_pickle(&toy_tiktoken_pickle()).unwrap();
        let layout = NanoChatLayout::from_tokenizer(&tok).unwrap();
        (tok, layout)
    }

    #[test]
    fn test_render() {
        let (tok, layout) = toy();
        assert_eq!(layout.stop_ids(), [264, 260]);
        let hello = 259;
        let ids = layout
            .render(
                &tok,
                &[
                    ChatMessage::user("hello"),
                    ChatMessage::assistant("hello"),
                    ChatMessage::user("hello"),
                ],
            )
            .unwrap();
        assert_eq!(
            ids,
            [260, 261, hello, 262, 263, hello, 264, 261, hello, 262, 263]
        );
    }

    /// A system message is folded into the first user turn.
    #[test]
    fn test_system_message_folds_into_the_first_turn() {
        let (tok, layout) = toy();
        let folded = layout
            .render(
                &tok,
                &[ChatMessage::system("hello"), ChatMessage::user("hello")],
            )
            .unwrap();
        let joined = layout
            .render(&tok, &[ChatMessage::user("hello\n\nhello")])
            .unwrap();
        assert_eq!(folded, joined);
    }

    #[test]
    fn test_refuses_what_upstream_cannot_render() {
        let (tok, layout) = toy();
        let illegal = ErrorMatcher::kind(BunsenErrorKind::Illegal);
        illegal.assert_err(&layout.render(&tok, &[]));
        illegal.assert_err(&layout.render(&tok, &[ChatMessage::system("hello")]));
        illegal.assert_err(&layout.render(&tok, &[ChatMessage::assistant("hello")]));
        illegal.assert_err(&layout.render(
            &tok,
            &[ChatMessage::user("hello"), ChatMessage::assistant("hello")],
        ));
        illegal.assert_err(&layout.render(
            &tok,
            &[ChatMessage::user("hello"), ChatMessage::user("hello")],
        ));
    }
}