Skip to main content

dynamo_renderer/deepseek/
v41.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Text and image prompt encoding for DeepSeek V4.1.
5
6use anyhow::{Context, Result, ensure};
7use serde_json::Value;
8
9use super::common::{ThinkingMode, resolve_thinking_mode, to_json};
10use super::v4::{Encoding, encode_owned_messages as encode_v4_messages};
11
12const IMAGE_PLACEHOLDER: &str = "<|deepseek_image|>";
13
14fn validate_text(text: &str) -> Result<&str> {
15    ensure!(
16        !text.contains(IMAGE_PLACEHOLDER),
17        "Images must be supplied as image content blocks, not literal image placeholders"
18    );
19    Ok(text)
20}
21
22/// Mid-conversation system messages count as user turns. As in the reference
23/// encoder, user messages containing only tool results do not start a new turn.
24pub(super) fn find_last_user_index(messages: &[Value]) -> Option<usize> {
25    messages.iter().enumerate().rposition(|(index, message)| {
26        let role = message.get("role").and_then(Value::as_str);
27        if !(role == Some("user") || (role == Some("system") && index > 0)) {
28            return false;
29        }
30        match message.get("content_blocks").and_then(Value::as_array) {
31            Some(blocks) if !blocks.is_empty() => blocks.iter().any(|block| {
32                matches!(
33                    block.get("type").and_then(Value::as_str),
34                    Some("text" | "image" | "image_url")
35                )
36            }),
37            _ => true,
38        }
39    })
40}
41
42pub(super) fn drop_thinking_messages(mut messages: Vec<Value>) -> Vec<Value> {
43    if let Some(last_user) = find_last_user_index(&messages) {
44        for message in &mut messages[..last_user] {
45            if message.get("role").and_then(Value::as_str) == Some("assistant") {
46                message.as_object_mut().unwrap().remove("reasoning_content");
47            }
48        }
49    }
50    messages
51}
52
53pub(super) fn encode_arguments(tool_call: &Value) -> Result<String> {
54    let original = tool_call
55        .get("arguments")
56        .context("Missing tool arguments")?;
57    let mut arguments = original.clone();
58    for _ in 0..2 {
59        let Some(text) = arguments.as_str() else {
60            break;
61        };
62        let Ok(decoded) = serde_json::from_str(text) else {
63            break;
64        };
65        arguments = decoded;
66    }
67    if !arguments.is_object() {
68        arguments = serde_json::json!({"arguments": original});
69    }
70    let parameters = arguments
71        .as_object()
72        .unwrap()
73        .iter()
74        .map(|(name, value)| {
75            let content = value
76                .as_str()
77                .map(str::to_owned)
78                .unwrap_or_else(|| to_json(value));
79            format!(
80                "<|DSML| parameter name=\"{name}\" string=\"{}\">{content}</|DSML| parameter>",
81                value.is_string()
82            )
83        })
84        .collect::<Vec<_>>();
85    Ok(parameters.join("\n"))
86}
87
88enum OrderMessage<'a> {
89    Assistant(Option<Vec<&'a str>>),
90    User { has_task: bool },
91    Tool(&'a str),
92    Boundary,
93}
94
95// Both raw encoding and typed media collection use this order. Boundaries end
96// the sortable group but retain call ranks, matching the reference encoder.
97fn message_order<'a>(messages: impl Iterator<Item = OrderMessage<'a>>) -> Vec<usize> {
98    let mut order = Vec::new();
99    let mut calls = std::collections::HashMap::new();
100    let mut slots = Vec::new();
101    let mut group_has_task = false;
102    let mut in_group = false;
103    fn flush(order: &mut [usize], slots: &mut Vec<(usize, usize)>) {
104        let mut sorted = slots.clone();
105        sorted.sort_by_key(|&(_, rank)| rank);
106        for ((target, _), (source, _)) in slots.drain(..).zip(sorted) {
107            order[target] = source;
108        }
109    }
110    for (index, message) in messages.enumerate() {
111        order.push(index);
112        match message {
113            OrderMessage::Tool(id) => {
114                slots.push((index, *calls.get(id).unwrap_or(&0)));
115                in_group = true;
116            }
117            OrderMessage::User { has_task } => {
118                // A task stays on the merged group until the next user starts a new one.
119                if group_has_task {
120                    flush(&mut order, &mut slots);
121                    in_group = false;
122                }
123                // A user merged into the group drops its task, as in the reference.
124                if !in_group {
125                    group_has_task = has_task;
126                }
127                in_group = true;
128            }
129            boundary => {
130                flush(&mut order, &mut slots);
131                group_has_task = false;
132                in_group = false;
133                // As in the reference, an empty tool_calls list keeps the previous ranks.
134                if let OrderMessage::Assistant(Some(ids)) = boundary
135                    && !ids.is_empty()
136                {
137                    calls.clear();
138                    for (rank, id) in ids.into_iter().enumerate() {
139                        if !id.is_empty() {
140                            calls.insert(id, rank);
141                        }
142                    }
143                }
144            }
145        }
146    }
147    flush(&mut order, &mut slots);
148    order
149}
150
151fn raw_message_order(messages: &[Value]) -> Vec<usize> {
152    message_order(
153        messages
154            .iter()
155            .map(|message| match message["role"].as_str() {
156                Some("assistant") => {
157                    OrderMessage::Assistant(message["tool_calls"].as_array().map(|calls| {
158                        calls
159                            .iter()
160                            .map(|call| {
161                                call["id"]
162                                    .as_str()
163                                    .or_else(|| call["function"]["id"].as_str())
164                                    .unwrap_or("")
165                            })
166                            .collect()
167                    }))
168                }
169                Some("user") => OrderMessage::User {
170                    has_task: !message["task"].is_null(),
171                },
172                Some("tool") => OrderMessage::Tool(message["tool_call_id"].as_str().unwrap_or("")),
173                _ => OrderMessage::Boundary,
174            }),
175    )
176}
177
178fn normalize_content(messages: &mut [Value]) -> Result<()> {
179    for message in messages {
180        for field in ["tools", "tool_calls"] {
181            for tool in message
182                .get(field)
183                .and_then(Value::as_array)
184                .into_iter()
185                .flatten()
186            {
187                ensure!(
188                    tool.get("namespace").is_none_or(Value::is_null)
189                        && tool
190                            .get("function")
191                            .and_then(|function| function.get("namespace"))
192                            .is_none_or(Value::is_null),
193                    "DeepSeek V4.1 native formatter does not support explicit tool namespaces; use a qualified function name"
194                );
195            }
196        }
197        ensure!(
198            message.get("content_blocks").is_none(),
199            "DeepSeek V4.1 expects OpenAI content blocks in content"
200        );
201        ensure!(
202            !message
203                .get("reasoning_content")
204                .and_then(Value::as_str)
205                .is_some_and(|text| text.contains(IMAGE_PLACEHOLDER)),
206            "Images must be supplied as image content blocks, not literal image placeholders"
207        );
208        if message.get("role").and_then(Value::as_str) == Some("developer") {
209            message["role"] = Value::String("system".into());
210        }
211        if let Some(content) = message.get("content") {
212            let text = match content {
213                Value::Null => String::new(),
214                Value::String(text) => {
215                    validate_text(text)?;
216                    continue;
217                }
218                Value::Array(blocks) => {
219                    let mut texts = Vec::with_capacity(blocks.len());
220                    for block in blocks {
221                        match block.get("type").and_then(Value::as_str) {
222                            Some("text") => texts.push(validate_text(
223                                block
224                                    .get("text")
225                                    .and_then(Value::as_str)
226                                    .context("Text block requires text")?,
227                            )?),
228                            Some("image_url") => {
229                                let source = &block["image_url"];
230                                let url = source.as_str().or_else(|| source["url"].as_str());
231                                ensure!(
232                                    url.is_some_and(|url| !url.is_empty())
233                                        || block["uuid"]
234                                            .as_str()
235                                            .is_some_and(|uuid| !uuid.is_empty()),
236                                    "Image block does not contain a valid source"
237                                );
238                                // The official encoder replaces each image in order.
239                                // Normalize only this rendering copy: Dynamo's media
240                                // collector still needs the original URLs/data URLs.
241                                texts.push(IMAGE_PLACEHOLDER);
242                            }
243                            _ => anyhow::bail!(
244                                "DeepSeek V4.1 native formatter supports text and image_url content only"
245                            ),
246                        }
247                    }
248                    texts.join("\n\n")
249                }
250                _ => anyhow::bail!("DeepSeek V4.1 message content must be text or content blocks"),
251            };
252            message["content"] = Value::String(text);
253        }
254    }
255    Ok(())
256}
257
258/// Encode text/image messages with the model's numeric reasoning effort (1–100).
259pub fn encode_messages(
260    messages: &[Value],
261    thinking_mode: ThinkingMode,
262    drop_thinking: bool,
263    reasoning_effort: u8,
264) -> Result<String> {
265    ensure!(
266        (1..=100).contains(&reasoning_effort),
267        "DeepSeek V4.1 reasoning effort must be within 1–100"
268    );
269    encode_owned_messages(
270        messages.to_vec(),
271        thinking_mode,
272        drop_thinking,
273        reasoning_effort,
274        true,
275    )
276}
277
278fn encode_owned_messages(
279    mut messages: Vec<Value>,
280    thinking_mode: ThinkingMode,
281    drop_thinking: bool,
282    reasoning_effort: u8,
283    add_generation_prompt: bool,
284) -> Result<String> {
285    ensure!(
286        (1..=100).contains(&reasoning_effort),
287        "DeepSeek V4.1 reasoning effort must be within 1–100"
288    );
289    normalize_content(&mut messages)?;
290    if messages.iter().any(|message| message["role"] == "tool") {
291        let order = raw_message_order(&messages);
292        messages = order
293            .into_iter()
294            .map(|index| std::mem::take(&mut messages[index]))
295            .collect();
296    }
297    encode_v4_messages(
298        messages,
299        thinking_mode,
300        true,
301        drop_thinking,
302        Encoding::V41 {
303            effort: reasoning_effort,
304            add_generation_prompt,
305        },
306    )
307}
308
309/// Native text/image formatter with OpenAI reasoning-effort names mapped as in the
310/// DeepSeek V4.1 reference encoder.
311#[derive(Debug, Default)]
312pub struct DeepSeekV41Formatter;
313
314impl crate::OAIPromptFormatter for DeepSeekV41Formatter {
315    fn supports_add_generation_prompt(&self) -> bool {
316        true
317    }
318
319    fn media_message_order(&self, request: &dyn crate::OAIChatLikeRequest) -> Option<Vec<usize>> {
320        use dynamo_protocols::types::ChatCompletionRequestMessage as Message;
321        let Some(messages) = request.typed_messages() else {
322            // Custom requests may expose only the same raw view used by render.
323            // Invalid raw messages are rejected by render before media collection.
324            let messages = serde_json::to_value(request.messages()).ok()?;
325            let messages = messages.as_array()?;
326            return messages
327                .iter()
328                .any(|message| message["role"] == "tool")
329                .then(|| raw_message_order(messages));
330        };
331        if !messages
332            .iter()
333            .any(|message| matches!(message, Message::Tool(_)))
334        {
335            return None;
336        }
337        Some(message_order(messages.iter().map(|message| {
338            match message {
339                Message::Assistant(assistant) => OrderMessage::Assistant(
340                    assistant
341                        .tool_calls
342                        .as_ref()
343                        .map(|calls| calls.iter().map(|call| call.id.as_str()).collect()),
344                ),
345                Message::User(_) => OrderMessage::User { has_task: false },
346                Message::Tool(tool) => OrderMessage::Tool(tool.tool_call_id.as_str()),
347                _ => OrderMessage::Boundary,
348            }
349        })))
350    }
351
352    fn render(&self, req: &dyn crate::OAIChatLikeRequest) -> Result<String> {
353        let messages_json = crate::messages_to_json(req)?;
354        crate::reject_unsupported_partial_assistant(&messages_json)?;
355        crate::reject_unsupported_message_tools(&messages_json, &["developer"])?;
356
357        let args = req.chat_template_args();
358        let effort = req
359            .reasoning_effort()
360            .map(|value| serde_json::to_value(value).context("Serialize reasoning effort"))
361            .transpose()?
362            .or_else(|| args.and_then(|args| args.get("reasoning_effort").cloned()));
363        let mut thinking_mode = resolve_thinking_mode(args, ThinkingMode::Thinking);
364        let budget = match effort.as_ref() {
365            None | Some(Value::Null) => 75,
366            Some(value) => match value.as_str() {
367                Some("none") => {
368                    thinking_mode = ThinkingMode::Chat;
369                    75
370                }
371                Some("low") => 50,
372                Some("medium") => 62,
373                Some("high") => 75,
374                Some("max") => 100,
375                _ => value
376                    .as_u64()
377                    .filter(|v| (1..=100).contains(v))
378                    .context("DeepSeek V4.1 reasoning effort must be low, medium, high, max, none, or an integer within 1–100")?
379                    as u8,
380            },
381        };
382        let drop_thinking = match args.and_then(|args| args.get("drop_thinking")) {
383            None => true,
384            Some(value) => value.as_bool().context("drop_thinking must be a boolean")?,
385        };
386        let Value::Array(mut messages) = messages_json else {
387            anyhow::bail!("Messages is not an array");
388        };
389        let tools_enabled =
390            req.tool_choice().as_ref().and_then(|value| value.as_str()) != Some("none");
391        let tools = req
392            .tools()
393            .filter(|tools| tools_enabled && tools.len().is_some_and(|length| length > 0))
394            .map(serde_json::to_value)
395            .transpose()?;
396        let response_format = req
397            .response_format()
398            .map(serde_json::to_value)
399            .transpose()?;
400        if tools.is_some() || response_format.is_some() {
401            let developer_tools_would_be_overwritten = tools.is_some()
402                && messages.first().is_some_and(|message| {
403                    message.get("role").and_then(Value::as_str) == Some("developer")
404                        && message.get("tools").is_some_and(|tools| {
405                            !tools.is_null() && !tools.as_array().is_some_and(Vec::is_empty)
406                        })
407                });
408            if developer_tools_would_be_overwritten
409                || !matches!(
410                    messages
411                        .first()
412                        .and_then(|m| m.get("role"))
413                        .and_then(Value::as_str),
414                    Some("system" | "developer")
415                )
416            {
417                messages.insert(0, serde_json::json!({"role": "system", "content": ""}));
418            }
419            if let Some(tools) = tools {
420                messages[0]["tools"] = tools;
421            }
422            if let Some(response_format) = response_format {
423                messages[0]["response_format"] = response_format;
424            }
425        }
426        encode_owned_messages(
427            messages,
428            thinking_mode,
429            drop_thinking,
430            budget,
431            req.should_add_generation_prompt(),
432        )
433    }
434}