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, reasoning_text, 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            !reasoning_text(message.get("reasoning_content")).contains(IMAGE_PLACEHOLDER),
203            "Images must be supplied as image content blocks, not literal image placeholders"
204        );
205        if message.get("role").and_then(Value::as_str) == Some("developer") {
206            message["role"] = Value::String("system".into());
207        }
208        if let Some(content) = message.get("content") {
209            let text = match content {
210                Value::Null => String::new(),
211                Value::String(text) => {
212                    validate_text(text)?;
213                    continue;
214                }
215                Value::Array(blocks) => {
216                    let mut texts = Vec::with_capacity(blocks.len());
217                    for block in blocks {
218                        match block.get("type").and_then(Value::as_str) {
219                            Some("text") => texts.push(validate_text(
220                                block
221                                    .get("text")
222                                    .and_then(Value::as_str)
223                                    .context("Text block requires text")?,
224                            )?),
225                            Some("image_url") => {
226                                let source = &block["image_url"];
227                                let url = source.as_str().or_else(|| source["url"].as_str());
228                                ensure!(
229                                    url.is_some_and(|url| !url.is_empty())
230                                        || block["uuid"]
231                                            .as_str()
232                                            .is_some_and(|uuid| !uuid.is_empty()),
233                                    "Image block does not contain a valid source"
234                                );
235                                // The official encoder replaces each image in order.
236                                // Normalize only this rendering copy: Dynamo's media
237                                // collector still needs the original URLs/data URLs.
238                                texts.push(IMAGE_PLACEHOLDER);
239                            }
240                            _ => anyhow::bail!(
241                                "DeepSeek V4.1 native formatter supports text and image_url content only"
242                            ),
243                        }
244                    }
245                    texts.join("\n\n")
246                }
247                _ => anyhow::bail!("DeepSeek V4.1 message content must be text or content blocks"),
248            };
249            message["content"] = Value::String(text);
250        }
251    }
252    Ok(())
253}
254
255/// Encode text/image messages with the model's numeric reasoning effort (1–100).
256pub fn encode_messages(
257    messages: &[Value],
258    thinking_mode: ThinkingMode,
259    drop_thinking: bool,
260    reasoning_effort: u8,
261) -> Result<String> {
262    ensure!(
263        (1..=100).contains(&reasoning_effort),
264        "DeepSeek V4.1 reasoning effort must be within 1–100"
265    );
266    encode_owned_messages(
267        messages.to_vec(),
268        thinking_mode,
269        drop_thinking,
270        reasoning_effort,
271        true,
272    )
273}
274
275fn encode_owned_messages(
276    mut messages: Vec<Value>,
277    thinking_mode: ThinkingMode,
278    drop_thinking: bool,
279    reasoning_effort: u8,
280    add_generation_prompt: bool,
281) -> Result<String> {
282    ensure!(
283        (1..=100).contains(&reasoning_effort),
284        "DeepSeek V4.1 reasoning effort must be within 1–100"
285    );
286    normalize_content(&mut messages)?;
287    if messages.iter().any(|message| message["role"] == "tool") {
288        let order = raw_message_order(&messages);
289        messages = order
290            .into_iter()
291            .map(|index| std::mem::take(&mut messages[index]))
292            .collect();
293    }
294    encode_v4_messages(
295        messages,
296        thinking_mode,
297        true,
298        drop_thinking,
299        Encoding::V41 {
300            effort: reasoning_effort,
301            add_generation_prompt,
302        },
303    )
304}
305
306/// Native text/image formatter with OpenAI reasoning-effort names mapped as in the
307/// DeepSeek V4.1 reference encoder.
308#[derive(Debug, Default)]
309pub struct DeepSeekV41Formatter;
310
311impl crate::OAIPromptFormatter for DeepSeekV41Formatter {
312    fn supports_add_generation_prompt(&self) -> bool {
313        true
314    }
315
316    fn media_message_order(&self, request: &dyn crate::OAIChatLikeRequest) -> Option<Vec<usize>> {
317        use dynamo_protocols::types::ChatCompletionRequestMessage as Message;
318        let Some(messages) = request.typed_messages() else {
319            // Custom requests may expose only the same raw view used by render.
320            // Invalid raw messages are rejected by render before media collection.
321            let messages = serde_json::to_value(request.messages()).ok()?;
322            let messages = messages.as_array()?;
323            return messages
324                .iter()
325                .any(|message| message["role"] == "tool")
326                .then(|| raw_message_order(messages));
327        };
328        if !messages
329            .iter()
330            .any(|message| matches!(message, Message::Tool(_)))
331        {
332            return None;
333        }
334        Some(message_order(messages.iter().map(|message| {
335            match message {
336                Message::Assistant(assistant) => OrderMessage::Assistant(
337                    assistant
338                        .tool_calls
339                        .as_ref()
340                        .map(|calls| calls.iter().map(|call| call.id.as_str()).collect()),
341                ),
342                Message::User(_) => OrderMessage::User { has_task: false },
343                Message::Tool(tool) => OrderMessage::Tool(tool.tool_call_id.as_str()),
344                _ => OrderMessage::Boundary,
345            }
346        })))
347    }
348
349    fn render(&self, req: &dyn crate::OAIChatLikeRequest) -> Result<String> {
350        let messages_json = crate::messages_to_json(req)?;
351        crate::reject_unsupported_partial_assistant(&messages_json)?;
352        crate::reject_unsupported_message_tools(&messages_json, &["developer"])?;
353
354        let args = req.chat_template_args();
355        let effort = req
356            .reasoning_effort()
357            .map(|value| serde_json::to_value(value).context("Serialize reasoning effort"))
358            .transpose()?
359            .or_else(|| args.and_then(|args| args.get("reasoning_effort").cloned()));
360        let mut thinking_mode = resolve_thinking_mode(args, ThinkingMode::Thinking);
361        let budget = match effort.as_ref() {
362            None | Some(Value::Null) => 75,
363            Some(value) => match value.as_str() {
364                Some("none") => {
365                    thinking_mode = ThinkingMode::Chat;
366                    75
367                }
368                Some("low") => 50,
369                Some("medium") => 62,
370                Some("high") => 75,
371                Some("max") => 100,
372                _ => value
373                    .as_u64()
374                    .filter(|v| (1..=100).contains(v))
375                    .context("DeepSeek V4.1 reasoning effort must be low, medium, high, max, none, or an integer within 1–100")?
376                    as u8,
377            },
378        };
379        let drop_thinking = match args.and_then(|args| args.get("drop_thinking")) {
380            None => true,
381            Some(value) => value.as_bool().context("drop_thinking must be a boolean")?,
382        };
383        let Value::Array(mut messages) = messages_json else {
384            anyhow::bail!("Messages is not an array");
385        };
386        let tools_enabled =
387            req.tool_choice().as_ref().and_then(|value| value.as_str()) != Some("none");
388        let tools = req
389            .tools()
390            .filter(|tools| tools_enabled && tools.len().is_some_and(|length| length > 0))
391            .map(serde_json::to_value)
392            .transpose()?;
393        let response_format = req
394            .response_format()
395            .map(serde_json::to_value)
396            .transpose()?;
397        if tools.is_some() || response_format.is_some() {
398            let developer_tools_would_be_overwritten = tools.is_some()
399                && messages.first().is_some_and(|message| {
400                    message.get("role").and_then(Value::as_str) == Some("developer")
401                        && message.get("tools").is_some_and(|tools| {
402                            !tools.is_null() && !tools.as_array().is_some_and(Vec::is_empty)
403                        })
404                });
405            if developer_tools_would_be_overwritten
406                || !matches!(
407                    messages
408                        .first()
409                        .and_then(|m| m.get("role"))
410                        .and_then(Value::as_str),
411                    Some("system" | "developer")
412                )
413            {
414                messages.insert(0, serde_json::json!({"role": "system", "content": ""}));
415            }
416            if let Some(tools) = tools {
417                messages[0]["tools"] = tools;
418            }
419            if let Some(response_format) = response_format {
420                messages[0]["response_format"] = response_format;
421            }
422        }
423        encode_owned_messages(
424            messages,
425            thinking_mode,
426            drop_thinking,
427            budget,
428            req.should_add_generation_prompt(),
429        )
430    }
431}