Skip to main content

hyprstream_inference/runtime/
template_engine.rs

1//! Jinja2 template engine for chat templates using minijinja
2
3use anyhow::{anyhow, Result};
4use minijinja::{context, Environment, Value};
5use once_cell::sync::Lazy;
6use regex::Regex;
7use serde::{Deserialize, Serialize};
8use std::collections::HashMap;
9
10/// Chat message structure for template rendering.
11///
12/// Fields match what HuggingFace chat templates expect:
13/// - `content` is Optional (can be null for tool-call-only assistant messages)
14/// - `tool_calls` carries tool call objects on assistant messages
15/// - `tool_call_id` identifies which tool call a "tool" role message responds to
16#[derive(Debug, Clone, Default, Serialize, Deserialize)]
17pub struct ChatMessage {
18    pub role: String,
19    #[serde(default, skip_serializing_if = "Option::is_none")]
20    pub content: Option<String>,
21    #[serde(default, skip_serializing_if = "Option::is_none")]
22    pub tool_calls: Option<Vec<TemplatToolCall>>,
23    #[serde(default, skip_serializing_if = "Option::is_none")]
24    pub tool_call_id: Option<String>,
25}
26
27/// Tool call representation for template rendering.
28///
29/// Unlike the RPC/OpenAI `ToolCall` (where `arguments` is a JSON string),
30/// this type stores `arguments` as a `serde_json::Value` so that Jinja2
31/// templates can iterate with `|items` (e.g. Qwen3.5's template does
32/// `for args_name, args_value in tool_call.arguments|items`).
33#[derive(Debug, Clone, Serialize, Deserialize)]
34pub struct TemplatToolCall {
35    pub id: String,
36    #[serde(rename = "type", default)]
37    pub tool_type: String,
38    pub function: TemplateToolCallFunction,
39}
40
41/// Tool call function with parsed arguments.
42#[derive(Debug, Clone, Serialize, Deserialize)]
43pub struct TemplateToolCallFunction {
44    pub name: String,
45    /// Arguments as a structured JSON value (not a string).
46    /// Parsed from the RPC `ToolCallFunction.arguments` JSON string
47    /// at the ChatMessage conversion boundary.
48    pub arguments: serde_json::Value,
49}
50
51impl From<&hyprstream_rpc_std::inference_client::ToolCall> for TemplatToolCall {
52    fn from(tc: &hyprstream_rpc_std::inference_client::ToolCall) -> Self {
53        Self {
54            id: tc.id.clone(),
55            tool_type: tc.tool_type.clone(),
56            function: TemplateToolCallFunction {
57                name: tc.function.name.clone(),
58                arguments: serde_json::from_str(&tc.function.arguments)
59                    .unwrap_or_else(|_| serde_json::Value::Object(serde_json::Map::new())),
60            },
61        }
62    }
63}
64
65/// Template configuration loaded from tokenizer_config.json
66#[derive(Debug, Clone, Serialize, Deserialize)]
67pub struct TemplateConfig {
68    /// The Jinja2 chat template string
69    pub chat_template: Option<String>,
70    /// Special tokens mapping
71    pub special_tokens: HashMap<String, String>,
72    /// Whether to add generation prompt
73    pub add_generation_prompt: bool,
74    /// BOS token
75    pub bos_token: Option<String>,
76    /// EOS token
77    pub eos_token: Option<String>,
78    /// PAD token
79    pub pad_token: Option<String>,
80    /// UNK token
81    pub unk_token: Option<String>,
82    /// SEP token
83    pub sep_token: Option<String>,
84    /// CLS token
85    pub cls_token: Option<String>,
86    /// Additional tokens
87    pub additional_special_tokens: Vec<String>,
88}
89
90impl Default for TemplateConfig {
91    fn default() -> Self {
92        Self {
93            chat_template: None,
94            special_tokens: HashMap::new(),
95            add_generation_prompt: true,
96            bos_token: None,
97            eos_token: None,
98            pad_token: None,
99            unk_token: None,
100            sep_token: None,
101            cls_token: None,
102            additional_special_tokens: Vec::new(),
103        }
104    }
105}
106
107/// Template engine for rendering chat templates
108pub struct TemplateEngine {
109    env: Environment<'static>,
110    config: TemplateConfig,
111}
112
113impl TemplateEngine {
114    /// Create a new template engine with the given configuration
115    pub fn new(config: TemplateConfig) -> Result<Self> {
116        let mut env = Environment::new();
117
118        // Register common filters that HuggingFace templates might use
119        env.add_filter("length", length_filter);
120        env.add_filter("tojson", tojson_filter);
121        env.add_filter("strip", strip_filter);
122        env.add_filter("rstrip", rstrip_filter);
123        env.add_filter("lstrip", lstrip_filter);
124        env.add_filter("split_first", split_first_filter);
125        env.add_filter("split_last", split_last_filter);
126
127        // Add custom tests for string operations
128        // These can be used as: {% if value is startswith("prefix") %}
129        env.add_test("startswith", |value: &str, prefix: &str| -> bool {
130            value.starts_with(prefix)
131        });
132        env.add_test("endswith", |value: &str, suffix: &str| -> bool {
133            value.ends_with(suffix)
134        });
135
136        // Also add as filters for compatibility: {{ value|startswith("prefix") }}
137        env.add_filter("startswith", |value: &str, prefix: &str| -> bool {
138            value.starts_with(prefix)
139        });
140        env.add_filter("endswith", |value: &str, suffix: &str| -> bool {
141            value.ends_with(suffix)
142        });
143
144        // Register raise_exception() — used by Mistral templates for validation
145        env.add_function("raise_exception", raise_exception_fn);
146
147        // We'll add the template dynamically when applying it
148        // to avoid lifetime issues
149
150        Ok(Self { env, config })
151    }
152
153    /// Apply chat template to messages.
154    ///
155    /// `tools` is an optional JSON value (array of tool definitions) that will be
156    /// passed to the template as the `tools` variable. HuggingFace chat templates
157    /// for tool-calling models (Qwen3, Llama 3.1, Mistral, etc.) use this variable
158    /// to format tool descriptions natively.
159    pub fn apply_chat_template(
160        &self,
161        messages: &[ChatMessage],
162        add_generation_prompt: Option<bool>,
163        tools: Option<&serde_json::Value>,
164    ) -> Result<String> {
165        self.apply_chat_template_with_vars(messages, add_generation_prompt, tools, None, None)
166    }
167
168    pub fn apply_chat_template_with_vars(
169        &self,
170        messages: &[ChatMessage],
171        add_generation_prompt: Option<bool>,
172        tools: Option<&serde_json::Value>,
173        enable_thinking: Option<bool>,
174        template_vars_json: Option<&str>,
175    ) -> Result<String> {
176        // Use provided template or fall back to a default
177        let template_str = self
178            .config
179            .chat_template
180            .as_ref()
181            .ok_or_else(|| anyhow!("No chat template configured"))?;
182
183        // Transform Python-style method calls to minijinja syntax if needed
184        // HuggingFace templates use Python/Jinja2 syntax but minijinja uses test syntax
185        let transformed = template_str
186            .replace(".startswith(", " is startswith(")
187            .replace(".endswith(", " is endswith(");
188
189        // Transform .split('sep')[0] → |split_first('sep') and .split('sep')[-1] → |split_last('sep')
190        // Must use regex because the pattern includes a subscript index after the call.
191        let transformed = transform_split_calls(&transformed);
192        // Transform .strip(...), .rstrip(...), .lstrip(...) → filter syntax
193        // Must do .strip( before .rstrip(/.lstrip( since the latter contain "strip("
194        let transformed = transform_strip_calls(&transformed);
195
196        // Compile the template
197        let tmpl = self.env.template_from_str(&transformed)
198            .map_err(|e| anyhow!("Template compilation failed: {}. Original template may use unsupported Python syntax.", e))?;
199
200        // Prepare context with all special tokens and variables
201        let add_gen = add_generation_prompt.unwrap_or(self.config.add_generation_prompt);
202
203        // Convert tools to minijinja Value (or undefined if None)
204        let tools_value = match tools {
205            Some(t) => Value::from_serialize(t),
206            None => Value::UNDEFINED,
207        };
208
209        // enable_thinking: pass as Value so None → UNDEFINED (template uses its own default)
210        let thinking_value = match enable_thinking {
211            Some(v) => Value::from(v),
212            None => Value::UNDEFINED,
213        };
214
215        // Build base context
216        let mut ctx = context! {
217            messages => messages,
218            tools => tools_value,
219            bos_token => self.config.bos_token.as_deref().unwrap_or(""),
220            eos_token => self.config.eos_token.as_deref().unwrap_or(""),
221            pad_token => self.config.pad_token.as_deref().unwrap_or(""),
222            unk_token => self.config.unk_token.as_deref().unwrap_or(""),
223            sep_token => self.config.sep_token.as_deref().unwrap_or(""),
224            cls_token => self.config.cls_token.as_deref().unwrap_or(""),
225            additional_special_tokens => &self.config.additional_special_tokens,
226            add_generation_prompt => add_gen,
227            enable_thinking => thinking_value,
228        };
229
230        // Merge additional template variables from JSON into context.
231        // minijinja's context! macro doesn't support dynamic keys, so we
232        // build a BTreeMap and merge via from_serialize.
233        if let Some(vars_json) = template_vars_json {
234            if !vars_json.is_empty() {
235                if let Ok(vars) = serde_json::from_str::<serde_json::Value>(vars_json) {
236                    ctx = context! { ..ctx, ..Value::from_serialize(&vars) };
237                }
238            }
239        }
240
241        // Render the template
242        let rendered = tmpl.render(ctx)?;
243
244        Ok(rendered)
245    }
246
247    /// Get a fallback template for common model architectures
248    pub fn get_fallback_template(model_type: &str) -> String {
249        match model_type.to_lowercase().as_str() {
250            "llama" | "llama2" | "llama3" => {
251                // Llama-style template
252                r#"{% for message in messages %}
253{% if message['role'] == 'system' %}{{ message['content'] }}
254
255{% elif message['role'] == 'user' %}### Human: {{ message['content'] }}
256
257{% elif message['role'] == 'assistant' %}### Assistant: {{ message['content'] }}
258
259{% endif %}{% endfor %}{% if add_generation_prompt %}### Assistant: {% endif %}"#
260                    .to_owned()
261            }
262            "qwen" | "qwen2" => {
263                // Qwen2-style template with special tokens
264                r#"{% for message in messages %}
265{%- if message['role'] == 'system' -%}
266<|im_start|>system
267{{ message['content'] }}<|im_end|>
268{% elif message['role'] == 'user' %}
269<|im_start|>user
270{{ message['content'] }}<|im_end|>
271{% elif message['role'] == 'assistant' %}
272<|im_start|>assistant
273{{ message['content'] }}<|im_end|>
274{% endif %}
275{% endfor %}
276{% if add_generation_prompt %}<|im_start|>assistant
277{% endif %}"#
278                    .to_owned()
279            }
280            "mistral" | "mixtral" => {
281                // Mistral/Mixtral template
282                r#"{% for message in messages %}
283{% if message['role'] == 'user' %}[INST] {{ message['content'] }} [/INST]
284{% elif message['role'] == 'assistant' %}{{ message['content'] }}</s>
285{% endif %}{% endfor %}"#
286                    .to_owned()
287            }
288            "gemma" | "gemma2" => {
289                // Gemma-style template
290                r#"{% for message in messages %}
291{% if message['role'] == 'user' %}<start_of_turn>user
292{{ message['content'] }}<end_of_turn>
293{% elif message['role'] == 'assistant' %}<start_of_turn>model
294{{ message['content'] }}<end_of_turn>
295{% endif %}{% endfor %}
296{% if add_generation_prompt %}<start_of_turn>model
297{% endif %}"#
298                    .to_owned()
299            }
300            "chatml" | "chatgpt" => {
301                // ChatML format (GPT-style)
302                r#"{% for message in messages %}
303<|im_start|>{{ message['role'] }}
304{{ message['content'] }}<|im_end|>
305{% endfor %}
306{% if add_generation_prompt %}<|im_start|>assistant
307{% endif %}"#
308                    .to_owned()
309            }
310            "janus" | "janus-1.3b" | "janus-pro" => {
311                // DeepSeek/Janus format - simple User:/Assistant: format
312                r#"{% for message in messages %}
313{% if message['role'] == 'user' %}User: {{ message['content'] }}
314{% elif message['role'] == 'assistant' %}Assistant: {{ message['content'] }}
315{% endif %}{% endfor %}
316{% if add_generation_prompt %}Assistant: {% endif %}"#
317                    .to_owned()
318            }
319            _ => {
320                // Default simple template
321                r#"{% for message in messages %}
322{{ message['role'] }}: {{ message['content'] }}
323{% endfor %}
324{% if add_generation_prompt %}assistant: {% endif %}"#
325                    .to_owned()
326            }
327        }
328    }
329
330    /// Parse template configuration from tokenizer_config.json
331    pub fn from_tokenizer_config(config_json: &serde_json::Value) -> Result<TemplateConfig> {
332        let mut template_config = TemplateConfig::default();
333
334        // Extract chat template
335        if let Some(template) = config_json.get("chat_template").and_then(|v| v.as_str()) {
336            template_config.chat_template = Some(template.to_owned());
337        }
338
339        // Extract special tokens
340        if let Some(bos) = config_json.get("bos_token") {
341            template_config.bos_token = extract_token_value(bos);
342        }
343        if let Some(eos) = config_json.get("eos_token") {
344            template_config.eos_token = extract_token_value(eos);
345        }
346        if let Some(pad) = config_json.get("pad_token") {
347            template_config.pad_token = extract_token_value(pad);
348        }
349        if let Some(unk) = config_json.get("unk_token") {
350            template_config.unk_token = extract_token_value(unk);
351        }
352        if let Some(sep) = config_json.get("sep_token") {
353            template_config.sep_token = extract_token_value(sep);
354        }
355        if let Some(cls) = config_json.get("cls_token") {
356            template_config.cls_token = extract_token_value(cls);
357        }
358
359        // Extract additional special tokens
360        if let Some(additional) = config_json.get("additional_special_tokens") {
361            if let Some(arr) = additional.as_array() {
362                for token in arr {
363                    if let Some(token_str) = extract_token_value(token) {
364                        template_config.additional_special_tokens.push(token_str);
365                    }
366                }
367            }
368        }
369
370        // Check for add_generation_prompt setting
371        if let Some(add_gen) = config_json
372            .get("add_generation_prompt")
373            .and_then(serde_json::Value::as_bool)
374        {
375            template_config.add_generation_prompt = add_gen;
376        }
377
378        // Build special tokens map for convenience
379        if let Some(ref bos) = template_config.bos_token {
380            template_config
381                .special_tokens
382                .insert("bos_token".to_owned(), bos.clone());
383        }
384        if let Some(ref eos) = template_config.eos_token {
385            template_config
386                .special_tokens
387                .insert("eos_token".to_owned(), eos.clone());
388        }
389
390        Ok(template_config)
391    }
392}
393
394/// Extract token value from JSON (handles both string and object formats)
395fn extract_token_value(value: &serde_json::Value) -> Option<String> {
396    if let Some(s) = value.as_str() {
397        Some(s.to_owned())
398    } else if let Some(obj) = value.as_object() {
399        obj.get("content")
400            .and_then(|v| v.as_str())
401            .map(std::borrow::ToOwned::to_owned)
402    } else {
403        None
404    }
405}
406
407/// Custom filter for getting length
408fn length_filter(value: &Value) -> Result<Value, minijinja::Error> {
409    // In minijinja 2.12.0, try_iter returns a Result
410    if let Ok(iter) = value.try_iter() {
411        Ok(Value::from(iter.count()))
412    } else if let Some(s) = value.as_str() {
413        // Use char count instead of byte length for proper Unicode support
414        Ok(Value::from(s.chars().count()))
415    } else {
416        Ok(Value::from(0))
417    }
418}
419
420/// Custom filter for JSON serialization.
421///
422/// Supports optional `indent` keyword argument for pretty-printing, matching
423/// Jinja2's `tojson(indent=4)` syntax used by Llama 3.1 templates.
424fn tojson_filter(
425    value: &Value,
426    kwargs: minijinja::value::Kwargs,
427) -> Result<Value, minijinja::Error> {
428    let indent: Option<usize> = kwargs.get("indent")?;
429    kwargs.assert_all_used()?;
430
431    let json_str = if let Some(n) = indent {
432        // Pretty-print with the requested indentation
433        let v: serde_json::Value =
434            serde_json::from_str(&serde_json::to_string(&value).map_err(|e| {
435                minijinja::Error::new(
436                    minijinja::ErrorKind::InvalidOperation,
437                    format!("Failed to serialize to JSON: {e}"),
438                )
439            })?)
440            .map_err(|e| {
441                minijinja::Error::new(
442                    minijinja::ErrorKind::InvalidOperation,
443                    format!("Failed to re-parse JSON for indentation: {e}"),
444                )
445            })?;
446        let indent_bytes = b" ".repeat(n);
447        let formatter = serde_json::ser::PrettyFormatter::with_indent(&indent_bytes);
448        let mut buf = Vec::new();
449        let mut ser = serde_json::Serializer::with_formatter(&mut buf, formatter);
450        serde::Serialize::serialize(&v, &mut ser).map_err(|e| {
451            minijinja::Error::new(
452                minijinja::ErrorKind::InvalidOperation,
453                format!("Failed to pretty-print JSON: {e}"),
454            )
455        })?;
456        String::from_utf8(buf).unwrap_or_default()
457    } else {
458        serde_json::to_string(&value).map_err(|e| {
459            minijinja::Error::new(
460                minijinja::ErrorKind::InvalidOperation,
461                format!("Failed to serialize to JSON: {e}"),
462            )
463        })?
464    };
465    Ok(Value::from(json_str))
466}
467
468/// Custom function: `raise_exception(message)` — used by Mistral templates for validation.
469fn raise_exception_fn(msg: String) -> Result<Value, minijinja::Error> {
470    Err(minijinja::Error::new(
471        minijinja::ErrorKind::InvalidOperation,
472        msg,
473    ))
474}
475
476/// Custom filter for Python's .strip() / .strip(chars)
477fn strip_filter(value: &Value, chars: Option<&str>) -> Result<Value, minijinja::Error> {
478    if let Some(s) = value.as_str() {
479        match chars {
480            Some(c) => {
481                let char_list: Vec<char> = c.chars().collect();
482                Ok(Value::from(s.trim_matches(char_list.as_slice())))
483            }
484            None => Ok(Value::from(s.trim())),
485        }
486    } else {
487        Ok(value.clone())
488    }
489}
490
491/// Custom filter for Python's .rstrip(chars)
492fn rstrip_filter(value: &Value, chars: &str) -> Result<Value, minijinja::Error> {
493    if let Some(s) = value.as_str() {
494        let char_list: Vec<char> = chars.chars().collect();
495        Ok(Value::from(s.trim_end_matches(char_list.as_slice())))
496    } else {
497        Ok(value.clone())
498    }
499}
500
501/// Custom filter for Python's .lstrip(chars)
502fn lstrip_filter(value: &Value, chars: &str) -> Result<Value, minijinja::Error> {
503    if let Some(s) = value.as_str() {
504        let char_list: Vec<char> = chars.chars().collect();
505        Ok(Value::from(s.trim_start_matches(char_list.as_slice())))
506    } else {
507        Ok(value.clone())
508    }
509}
510
511/// Custom filter: equivalent to Python's .split(sep)[0]
512fn split_first_filter(value: &Value, sep: &str) -> Result<Value, minijinja::Error> {
513    if let Some(s) = value.as_str() {
514        Ok(Value::from(s.split(sep).next().unwrap_or("")))
515    } else {
516        Ok(value.clone())
517    }
518}
519
520/// Custom filter: equivalent to Python's .split(sep)[-1]
521fn split_last_filter(value: &Value, sep: &str) -> Result<Value, minijinja::Error> {
522    if let Some(s) = value.as_str() {
523        Ok(Value::from(s.rsplit(sep).next().unwrap_or("")))
524    } else {
525        Ok(value.clone())
526    }
527}
528
529/// Transform Python `.split('sep')[idx]` calls to minijinja filter syntax.
530///
531/// - `.split('sep')[0]`  → `|split_first('sep')`
532/// - `.split('sep')[-1]` → `|split_last('sep')`
533fn transform_split_calls(template: &str) -> String {
534    // Rust regex doesn't support backreferences, so handle single and double quotes separately
535    static RE_SINGLE: Lazy<Regex> = Lazy::new(|| {
536        #[allow(clippy::expect_used)]
537        Regex::new(r"\.split\('([^']*)'\)\[(-?\d+)\]").expect("valid regex")
538    });
539    static RE_DOUBLE: Lazy<Regex> = Lazy::new(|| {
540        #[allow(clippy::expect_used)]
541        Regex::new(r#"\.split\("([^"]*)"\)\[(-?\d+)\]"#).expect("valid regex")
542    });
543    let re_single = &*RE_SINGLE;
544    let re_double = &*RE_DOUBLE;
545
546    let result = re_single.replace_all(template, |caps: &regex::Captures| {
547        split_replacement(&caps[1], &caps[2])
548    });
549    let result = re_double.replace_all(&result, |caps: &regex::Captures| {
550        split_replacement(&caps[1], &caps[2])
551    });
552    result.into_owned()
553}
554
555/// Transform Python `.strip(...)`, `.rstrip(...)`, `.lstrip(...)` calls to filter syntax.
556///
557/// Handles both no-arg (`.strip()`) and parameterized (`.strip('\n')`) forms.
558/// Must be applied carefully: `.rstrip(` and `.lstrip(` are handled first to avoid
559/// the `.strip(` replacement matching the suffix of `.rstrip(` / `.lstrip(`.
560fn transform_strip_calls(template: &str) -> String {
561    // Order matters: replace .rstrip/.lstrip before .strip to avoid partial matches
562    template
563        .replace(".rstrip(", "|rstrip(")
564        .replace(".lstrip(", "|lstrip(")
565        .replace(".strip(", "|strip(")
566}
567
568fn split_replacement(sep: &str, idx_str: &str) -> String {
569    let idx: i64 = idx_str.parse().unwrap_or(0);
570    match idx {
571        0 => format!("|split_first('{sep}')"),
572        -1 => format!("|split_last('{sep}')"),
573        _ => format!(".split('{sep}')[{idx}]"), // leave unsupported indices unchanged
574    }
575}
576
577#[cfg(test)]
578#[allow(clippy::unwrap_used, clippy::expect_used)]
579mod tests {
580    use super::*;
581
582    #[test]
583    fn test_qwen_template() -> Result<()> {
584        let config = TemplateConfig {
585            chat_template: Some(
586                r#"{% for message in messages %}{{'<|im_start|>' + message['role'] + '
587' + message['content'] + '<|im_end|>' + '
588'}}{% endfor %}{% if add_generation_prompt %}{{ '<|im_start|>assistant
589' }}{% endif %}"#
590                    .to_owned(),
591            ),
592            ..Default::default()
593        };
594
595        let engine = TemplateEngine::new(config)?;
596        let messages = vec![ChatMessage {
597            role: "user".into(),
598            content: Some("Hello".into()),
599            ..Default::default()
600        }];
601
602        let result = engine.apply_chat_template(&messages, Some(true), None)?;
603        assert!(result.contains("<|im_start|>user"));
604        assert!(result.contains("Hello"));
605        assert!(result.contains("<|im_start|>assistant"));
606        Ok(())
607    }
608
609    #[test]
610    fn test_fallback_templates() {
611        for model_type in &["llama", "qwen", "mistral", "gemma", "chatml"] {
612            let template = TemplateEngine::get_fallback_template(model_type);
613            assert!(!template.is_empty());
614        }
615    }
616
617    #[test]
618    fn test_huggingface_template_with_python_methods() -> Result<()> {
619        // Real HuggingFace template that uses Python-style .startswith() method
620        let config = TemplateConfig {
621            chat_template: Some(
622                r#"{% for message in messages %}
623{% if message['role'].startswith('sys') %}System: {{ message['content'] }}
624{% elif message['role'].endswith('er') %}User: {{ message['content'] }}
625{% elif message['role'].startswith('assist') %}Assistant: {{ message['content'] }}
626{% endif %}{% endfor %}{% if add_generation_prompt %}Assistant: {% endif %}"#
627                    .to_owned(),
628            ),
629            ..Default::default()
630        };
631
632        let engine = TemplateEngine::new(config)?;
633        let messages = vec![
634            ChatMessage {
635                role: "system".into(),
636                content: Some("You are a helpful assistant.".into()),
637                ..Default::default()
638            },
639            ChatMessage {
640                role: "user".into(),
641                content: Some("Hello!".into()),
642                ..Default::default()
643            },
644            ChatMessage {
645                role: "assistant".into(),
646                content: Some("Hi there!".into()),
647                ..Default::default()
648            },
649        ];
650
651        let result = engine.apply_chat_template(&messages, Some(true), None)?;
652
653        // Verify the template was processed correctly
654        assert!(result.contains("System: You are a helpful assistant."));
655        assert!(result.contains("User: Hello!"));
656        assert!(result.contains("Assistant: Hi there!"));
657        assert!(result.ends_with("Assistant: "));
658        Ok(())
659    }
660
661    #[test]
662    fn test_complex_template_with_conditions() -> Result<()> {
663        // Complex template with nested conditions and multiple Python methods
664        let config = TemplateConfig {
665            chat_template: Some(
666                r#"{% for message in messages %}
667{% if message['role'].startswith('sys') and message['content'] != 'test' %}
668[SYSTEM] {{ message['content'] }}
669{% elif message['role'].startswith('u') %}
670[USER] {{ message['content'] }}
671{% elif message['role'].endswith('ant') %}
672[ASSISTANT] {{ message['content'] }}
673{% endif %}
674{% endfor %}"#
675                    .to_owned(),
676            ),
677            ..Default::default()
678        };
679
680        let engine = TemplateEngine::new(config)?;
681        let messages = vec![
682            ChatMessage {
683                role: "system".into(),
684                content: Some("Configure the model".into()),
685                ..Default::default()
686            },
687            ChatMessage {
688                role: "user".into(),
689                content: Some("What's 2+2?".into()),
690                ..Default::default()
691            },
692            ChatMessage {
693                role: "assistant".into(),
694                content: Some("4".into()),
695                ..Default::default()
696            },
697        ];
698
699        let result = engine.apply_chat_template(&messages, Some(false), None)?;
700        assert!(result.contains("[SYSTEM] Configure the model"));
701        assert!(result.contains("[USER] What's 2+2?"));
702        assert!(result.contains("[ASSISTANT] 4"));
703        Ok(())
704    }
705
706    #[test]
707    fn test_strip_filter() -> Result<()> {
708        // Test template with .strip() method (Python-style)
709        let config = TemplateConfig {
710            chat_template: Some(
711                r#"{% for message in messages %}
712{{ message['content'].strip() }}
713{% endfor %}"#
714                    .to_owned(),
715            ),
716            ..Default::default()
717        };
718
719        let engine = TemplateEngine::new(config)?;
720        let messages = vec![ChatMessage {
721            role: "user".into(),
722            content: Some("  Hello World  ".into()),
723            ..Default::default()
724        }];
725
726        let result = engine.apply_chat_template(&messages, Some(false), None)?;
727        assert!(result.contains("Hello World"));
728        assert!(!result.contains("  Hello World  "));
729        Ok(())
730    }
731
732    #[test]
733    fn test_split_and_strip_transforms() {
734        // Simulates the Qwen3 template's <think> tag extraction:
735        //   content.split('</think>')[0].rstrip('\n').split('<think>')[-1].lstrip('\n')
736        //   content.split('</think>')[-1].lstrip('\n')
737        let config = TemplateConfig {
738            chat_template: Some(
739                r#"{%- for message in messages -%}
740{%- set content = message['content'] -%}
741{%- if '</think>' in content -%}
742{%- set reasoning = content.split('</think>')[0].rstrip('\n').split('<think>')[-1].lstrip('\n') -%}
743{%- set content = content.split('</think>')[-1].lstrip('\n') -%}
744THINK:{{ reasoning }}
745CONTENT:{{ content }}
746{%- else -%}
747CONTENT:{{ content }}
748{%- endif -%}
749{%- endfor -%}"#
750                    .to_owned(),
751            ),
752            ..Default::default()
753        };
754
755        let engine = TemplateEngine::new(config).expect("test: create template engine");
756
757        // Message with think tags
758        let messages = vec![ChatMessage {
759            role: "assistant".into(),
760            content: Some("<think>\nI should search.\n</think>\nHere is the answer.".into()),
761            ..Default::default()
762        }];
763
764        let result = engine
765            .apply_chat_template(&messages, Some(false), None)
766            .expect("test: apply template");
767        assert!(result.contains("THINK:I should search."));
768        assert!(result.contains("CONTENT:Here is the answer."));
769
770        // Message without think tags
771        let messages_no_think = vec![ChatMessage {
772            role: "user".into(),
773            content: Some("Hello".into()),
774            ..Default::default()
775        }];
776
777        let result = engine
778            .apply_chat_template(&messages_no_think, Some(false), None)
779            .expect("test: apply no-think");
780        assert!(result.contains("CONTENT:Hello"));
781    }
782
783    #[test]
784    fn test_transform_split_calls() {
785        assert_eq!(
786            transform_split_calls("x.split('</think>')[0]"),
787            "x|split_first('</think>')"
788        );
789        assert_eq!(
790            transform_split_calls("x.split('<think>')[-1]"),
791            "x|split_last('<think>')"
792        );
793        assert_eq!(
794            transform_split_calls(r#"x.split("sep")[0]"#),
795            "x|split_first('sep')"
796        );
797    }
798
799    // ========================================================================
800    // Multi-turn and tool use tests
801    // ========================================================================
802
803    /// Simple ChatML template that handles all roles including tool
804    const CHATML_TEMPLATE: &str = r#"{% for message in messages %}{{'<|im_start|>' + message['role'] + '
805' + message['content'] + '<|im_end|>' + '
806'}}{% endfor %}{% if add_generation_prompt %}{{ '<|im_start|>assistant
807' }}{% endif %}"#;
808
809    /// ChatML template with tools support (simplified Qwen3-style)
810    const CHATML_WITH_TOOLS_TEMPLATE: &str = r#"{% if tools %}
811<|im_start|>system
812You are a helpful assistant with access to the following tools:
813
814{{ tools | tojson }}
815
816When you need to use a tool, respond with a tool_call block.<|im_end|>
817{% endif %}{% for message in messages %}{{'<|im_start|>' + message['role'] + '
818' + message['content'] + '<|im_end|>' + '
819'}}{% endfor %}{% if add_generation_prompt %}{{ '<|im_start|>assistant
820' }}{% endif %}"#;
821
822    fn make_tool(name: &str, description: &str) -> serde_json::Value {
823        serde_json::json!({
824            "type": "function",
825            "function": {
826                "name": name,
827                "description": description,
828                "parameters": {
829                    "type": "object",
830                    "properties": {
831                        "location": { "type": "string", "description": "City name" }
832                    },
833                    "required": ["location"]
834                }
835            }
836        })
837    }
838
839    #[test]
840    fn test_qwen3_template_with_tools() -> Result<()> {
841        let config = TemplateConfig {
842            chat_template: Some(CHATML_WITH_TOOLS_TEMPLATE.to_owned()),
843            ..Default::default()
844        };
845        let engine = TemplateEngine::new(config)?;
846
847        let messages = vec![ChatMessage {
848            role: "user".into(),
849            content: Some("What's the weather?".into()),
850            ..Default::default()
851        }];
852        let tools = serde_json::json!([make_tool("get_weather", "Get current weather")]);
853
854        let result = engine.apply_chat_template(&messages, Some(true), Some(&tools))?;
855
856        // Tool definitions should appear in system message
857        assert!(result.contains("get_weather"), "should contain tool name");
858        assert!(
859            result.contains("Get current weather"),
860            "should contain tool description"
861        );
862        // User message present
863        assert!(result.contains("What's the weather?"));
864        // Generation prompt present
865        assert!(result.contains("<|im_start|>assistant"));
866
867        Ok(())
868    }
869
870    #[test]
871    fn test_multi_turn_template_rendering() -> Result<()> {
872        let config = TemplateConfig {
873            chat_template: Some(CHATML_TEMPLATE.to_owned()),
874            ..Default::default()
875        };
876        let engine = TemplateEngine::new(config)?;
877
878        let messages = vec![
879            ChatMessage {
880                role: "system".into(),
881                content: Some("You are helpful.".into()),
882                ..Default::default()
883            },
884            ChatMessage {
885                role: "user".into(),
886                content: Some("Hello".into()),
887                ..Default::default()
888            },
889            ChatMessage {
890                role: "assistant".into(),
891                content: Some("Hi! How can I help?".into()),
892                ..Default::default()
893            },
894            ChatMessage {
895                role: "user".into(),
896                content: Some("Tell me a joke.".into()),
897                ..Default::default()
898            },
899        ];
900
901        let result = engine.apply_chat_template(&messages, Some(true), None)?;
902
903        // All messages in order
904        assert!(result.contains("You are helpful."));
905        assert!(result.contains("Hello"));
906        assert!(result.contains("Hi! How can I help?"));
907        assert!(result.contains("Tell me a joke."));
908
909        // Verify ordering: system before user, assistant before second user
910        let sys_pos = result.find("You are helpful.").unwrap();
911        let user1_pos = result.find("Hello").unwrap();
912        let asst_pos = result.find("Hi! How can I help?").unwrap();
913        let user2_pos = result.find("Tell me a joke.").unwrap();
914        assert!(sys_pos < user1_pos);
915        assert!(user1_pos < asst_pos);
916        assert!(asst_pos < user2_pos);
917
918        // Generation prompt at the end
919        let gen_pos = result.rfind("<|im_start|>assistant").unwrap();
920        assert!(
921            gen_pos > user2_pos,
922            "generation prompt should be after last user message"
923        );
924
925        Ok(())
926    }
927
928    #[test]
929    fn test_template_with_tool_call_history() -> Result<()> {
930        let config = TemplateConfig {
931            chat_template: Some(CHATML_TEMPLATE.to_owned()),
932            ..Default::default()
933        };
934        let engine = TemplateEngine::new(config)?;
935
936        // Full tool use conversation: user asks → assistant calls tool → tool responds → user follows up
937        let messages = vec![
938            ChatMessage { role: "user".into(), content: Some("What's the weather in NYC?".into()), ..Default::default() },
939            ChatMessage {
940                role: "assistant".into(),
941                content: Some(r#"<tool_call>{"name": "get_weather", "arguments": {"location": "NYC"}}</tool_call>"#.into()),
942                ..Default::default()
943            },
944            ChatMessage {
945                role: "tool".into(),
946                content: Some(r#"{"temperature": 72, "condition": "sunny"}"#.into()),
947                tool_call_id: Some("call_123".into()),
948                ..Default::default()
949            },
950            ChatMessage { role: "user".into(), content: Some("And in LA?".into()), ..Default::default() },
951        ];
952
953        let result = engine.apply_chat_template(&messages, Some(true), None)?;
954
955        // All roles rendered
956        assert!(result.contains("<|im_start|>user"));
957        assert!(result.contains("<|im_start|>assistant"));
958        assert!(result.contains("<|im_start|>tool"));
959
960        // Content preserved
961        assert!(result.contains("What's the weather in NYC?"));
962        assert!(result.contains("get_weather"));
963        assert!(result.contains("temperature"));
964        assert!(result.contains("And in LA?"));
965
966        // Proper ordering
967        let tool_call_pos = result.find("get_weather").unwrap();
968        let tool_resp_pos = result.find("temperature").unwrap();
969        let followup_pos = result.find("And in LA?").unwrap();
970        assert!(tool_call_pos < tool_resp_pos);
971        assert!(tool_resp_pos < followup_pos);
972
973        Ok(())
974    }
975
976    #[test]
977    fn test_template_tool_response_message() -> Result<()> {
978        let config = TemplateConfig {
979            chat_template: Some(CHATML_TEMPLATE.to_owned()),
980            ..Default::default()
981        };
982        let engine = TemplateEngine::new(config)?;
983
984        let messages = vec![ChatMessage {
985            role: "tool".into(),
986            content: Some(r#"{"result": "success"}"#.into()),
987            tool_call_id: Some("call_abc".into()),
988            ..Default::default()
989        }];
990
991        let result = engine.apply_chat_template(&messages, Some(false), None)?;
992
993        // Tool role rendered distinctly
994        assert!(result.contains("<|im_start|>tool"));
995        assert!(result.contains(r#"{"result": "success"}"#));
996        // No generation prompt (add_generation_prompt = false)
997        assert!(!result.contains("<|im_start|>assistant"));
998
999        Ok(())
1000    }
1001}