Skip to main content

wabot_addon_chat_bot_deepseek/
lib.rs

1//! DeepSeek chat adapter — port of wabot-ts
2//! `addon/chat-bot/deepseek/DeepSeekChatAdapter.ts`.
3//!
4//! DeepSeek serves an **OpenAI-compatible Chat Completions API**
5//! (`POST /v1/chat/completions`) — same wire format as the legacy
6//! OpenAI completions endpoint. We could share the bytes with our
7//! OpenAI adapter, but the OpenAI adapter targets the newer Responses
8//! API which has a different schema; folding both into one adapter
9//! would muddle the abstraction. Two thin adapters stay clearer.
10//!
11//! Direct `reqwest` calls; no third-party SDK dependency, same
12//! reasoning as the other LLM adapters in wabot-rust.
13
14use std::sync::Arc;
15
16use async_trait::async_trait;
17use serde::Deserialize;
18use serde_json::Value;
19
20use wabot_feature_chat_bot::{
21    extract_chat_message_text, ChatAdapter, ChatAdapterError, ChatAdapterRequest,
22    ChatAdapterResponse, ChatItem, ChatMessage, FunctionCall, LanguageModelUsage, SupportedMedia,
23};
24
25pub const PROVIDER: &str = "deepseek";
26const DEFAULT_BASE_URL: &str = "https://api.deepseek.com";
27
28/// Configuration for the DeepSeek adapter.
29#[derive(Debug, Clone)]
30pub struct DeepSeekConfig {
31    pub api_key: String,
32    pub base_url: String,
33}
34
35impl DeepSeekConfig {
36    pub fn new(api_key: impl Into<String>) -> Self {
37        Self {
38            api_key: api_key.into(),
39            base_url: DEFAULT_BASE_URL.into(),
40        }
41    }
42
43    /// Load from `DEEPSEEK_API_KEY` (required) and `DEEPSEEK_BASE_URL`
44    /// (optional, defaults to <https://api.deepseek.com>).
45    pub fn from_env() -> Self {
46        let api_key = std::env::var("DEEPSEEK_API_KEY").expect("missing DEEPSEEK_API_KEY env var");
47        let mut cfg = Self::new(api_key);
48        if let Ok(base) = std::env::var("DEEPSEEK_BASE_URL") {
49            cfg.base_url = base;
50        }
51        cfg
52    }
53
54    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
55        self.base_url = base_url.into();
56        self
57    }
58}
59
60pub struct DeepSeekChatAdapter {
61    inner: Arc<Inner>,
62}
63
64struct Inner {
65    config: DeepSeekConfig,
66    http: reqwest::Client,
67}
68
69impl DeepSeekChatAdapter {
70    pub fn new(config: DeepSeekConfig) -> Self {
71        Self {
72            inner: Arc::new(Inner {
73                config,
74                http: reqwest::Client::builder()
75                    .build()
76                    .expect("reqwest client build"),
77            }),
78        }
79    }
80}
81
82impl wabot_core::injection::IsSingleton for DeepSeekChatAdapter {
83    fn register_in(c: &wabot_core::injection::Container) {
84        c.register_singleton_factory::<DeepSeekChatAdapter, _>(|c2| {
85            let cfg: Arc<DeepSeekConfig> = c2.resolve::<DeepSeekConfig>();
86            Arc::new(DeepSeekChatAdapter::new((*cfg).clone()))
87        });
88    }
89}
90
91#[async_trait]
92impl ChatAdapter for DeepSeekChatAdapter {
93    async fn next_items(
94        &self,
95        req: ChatAdapterRequest,
96    ) -> Result<ChatAdapterResponse, ChatAdapterError> {
97        let mut messages: Vec<Value> = Vec::with_capacity(req.prev_items.len() + 1);
98        messages.push(serde_json::json!({
99            "role": "system",
100            "content": req.system_prompt,
101        }));
102        for item in &req.prev_items {
103            push_chat_item(&mut messages, item);
104        }
105
106        let tools: Vec<Value> = req.tools.into_iter().map(map_tool_def).collect();
107
108        let mut last_err: Option<ChatAdapterError> = None;
109        for model in &req.models {
110            let mut body = serde_json::json!({
111                "model": model.model,
112                "messages": messages,
113            });
114            if !tools.is_empty() {
115                body["tools"] = Value::Array(tools.clone());
116                body["tool_choice"] = Value::String("auto".into());
117            }
118
119            tracing::debug!(
120                provider = PROVIDER,
121                model = %model.model,
122                messages = messages.len(),
123                tools = tools.len(),
124                "deepseek request"
125            );
126
127            let url = format!("{}/v1/chat/completions", self.inner.config.base_url);
128            let res = self
129                .inner
130                .http
131                .post(&url)
132                .bearer_auth(&self.inner.config.api_key)
133                .header("content-type", "application/json")
134                .json(&body)
135                .send()
136                .await
137                .map_err(|e| ChatAdapterError::Transport(e.to_string()))?;
138
139            let status = res.status();
140            let raw = res
141                .text()
142                .await
143                .map_err(|e| ChatAdapterError::Transport(e.to_string()))?;
144
145            if !status.is_success() {
146                let err = ChatAdapterError::Provider {
147                    provider: PROVIDER,
148                    status: status.as_u16(),
149                    body: raw,
150                };
151                if is_retryable_status(status.as_u16()) {
152                    tracing::warn!(error = %err, "deepseek retryable error; trying next model");
153                    last_err = Some(err);
154                    continue;
155                }
156                return Err(err);
157            }
158
159            let parsed: DeepSeekResponse = serde_json::from_str(&raw)
160                .map_err(|e| ChatAdapterError::InvalidResponse(e.to_string()))?;
161            return Ok(parsed.into_adapter_response(&model.model));
162        }
163
164        Err(last_err.unwrap_or(ChatAdapterError::NoModelAvailable))
165    }
166}
167
168fn is_retryable_status(status: u16) -> bool {
169    matches!(status, 408 | 429 | 500 | 502 | 503 | 504)
170}
171
172fn push_chat_item(messages: &mut Vec<Value>, item: &ChatItem) {
173    match item {
174        ChatItem::HumanMessage { human_message } => {
175            messages.push(map_human_message(human_message));
176        }
177        ChatItem::BotMessage { bot_message } => {
178            messages.push(map_bot_message(bot_message));
179        }
180        ChatItem::FunctionCall { function_call } => {
181            messages.extend(map_function_call(function_call));
182        }
183    }
184}
185
186/// DeepSeek's chat models are text-only, so **every** attachment is
187/// described and none is attached. That is not a gap: telling the
188/// model "a PDF was attached and I cannot read it" is the useful
189/// behaviour, where dropping it silently makes the bot answer as if
190/// nothing was sent.
191const SUPPORTED: SupportedMedia = SupportedMedia {
192    images: Some(&[]),
193    documents: Some(&[]),
194};
195
196fn map_human_message(m: &ChatMessage) -> Value {
197    serde_json::json!({
198        "role": "user",
199        "content": extract_chat_message_text(m, SUPPORTED),
200    })
201}
202
203fn map_bot_message(m: &ChatMessage) -> Value {
204    let text = m.text.clone().unwrap_or_default();
205    serde_json::json!({
206        "role": "assistant",
207        "content": text,
208    })
209}
210
211fn map_function_call(fc: &FunctionCall) -> Vec<Value> {
212    let args_json = fc.arguments.clone().unwrap_or_else(|| "{}".into());
213    let result = fc.result.clone().unwrap_or_else(|| "No result".into());
214    vec![
215        serde_json::json!({
216            "role": "assistant",
217            "tool_calls": [
218                {
219                    "id": fc.id,
220                    "type": "function",
221                    "function": {
222                        "name": fc.name,
223                        "arguments": args_json,
224                    }
225                }
226            ]
227        }),
228        serde_json::json!({
229            "role": "tool",
230            "tool_call_id": fc.id,
231            "content": result,
232        }),
233    ]
234}
235
236fn map_tool_def(t: wabot_feature_chat_bot::ToolDefinition) -> Value {
237    let properties: serde_json::Map<String, Value> = t
238        .parameters
239        .iter()
240        .map(|p| {
241            // An optional parameter is advertised as nullable rather
242            // than left out of `required`: the model then has to say
243            // `null` instead of silently omitting the field, and
244            // `normalize_optional_arguments` turns that back into an
245            // absent value on the way in.
246            let type_schema = if p.required {
247                Value::String(p.r#type.clone())
248            } else {
249                serde_json::json!([p.r#type, "null"])
250            };
251            (
252                p.name.clone(),
253                serde_json::json!({
254                    "type": type_schema,
255                    "description": p.description,
256                }),
257            )
258        })
259        .collect();
260    // Every parameter, including the optional ones — see above.
261    let required: Vec<String> = t.parameters.iter().map(|p| p.name.clone()).collect();
262    serde_json::json!({
263        "type": "function",
264        "function": {
265            "name": t.name,
266            "description": t.description,
267            "parameters": {
268                "type": "object",
269                "properties": properties,
270                "required": required,
271                "additionalProperties": false,
272            }
273        }
274    })
275}
276
277// ----- wire-format response types --------------------------------------
278
279#[derive(Debug, Deserialize)]
280struct DeepSeekResponse {
281    #[serde(default)]
282    choices: Vec<DeepSeekChoice>,
283    #[serde(default)]
284    model: Option<String>,
285    usage: Option<DeepSeekUsage>,
286}
287
288#[derive(Debug, Deserialize)]
289struct DeepSeekChoice {
290    message: DeepSeekChoiceMessage,
291}
292
293#[derive(Debug, Deserialize)]
294struct DeepSeekChoiceMessage {
295    #[serde(default)]
296    content: Option<String>,
297    #[serde(default)]
298    tool_calls: Option<Vec<DeepSeekToolCall>>,
299}
300
301#[derive(Debug, Deserialize)]
302struct DeepSeekToolCall {
303    id: String,
304    #[serde(rename = "type")]
305    kind: String,
306    function: DeepSeekToolCallFunction,
307}
308
309#[derive(Debug, Deserialize)]
310struct DeepSeekToolCallFunction {
311    name: String,
312    arguments: String,
313}
314
315#[derive(Debug, Deserialize)]
316struct DeepSeekUsage {
317    prompt_tokens: u64,
318    completion_tokens: u64,
319    /// DeepSeek-specific — not in stock OpenAI's usage shape. Counted
320    /// as cache reads in our normalized [`LanguageModelUsage`].
321    #[serde(default)]
322    prompt_cache_hit_tokens: Option<u64>,
323}
324
325impl DeepSeekResponse {
326    fn into_adapter_response(self, requested_model: &str) -> ChatAdapterResponse {
327        let usage = self.usage.map(|u| {
328            let cache_read = u.prompt_cache_hit_tokens.unwrap_or(0);
329            LanguageModelUsage {
330                input_tokens: u.prompt_tokens,
331                output_tokens: u.completion_tokens,
332                cache_read_tokens: (cache_read > 0).then_some(cache_read),
333                cache_write_tokens: None,
334                cost_usd: None,
335                provider: Some(PROVIDER.into()),
336                model: self.model.clone().or_else(|| Some(requested_model.into())),
337            }
338        });
339
340        let mut next_items: Vec<ChatItem> = Vec::new();
341        if let Some(choice) = self.choices.into_iter().next() {
342            let msg = choice.message;
343            // Per the TS adapter: prefer content text; otherwise the
344            // first function tool_call. Don't emit both.
345            if let Some(text) = msg.content {
346                if !text.is_empty() {
347                    next_items.push(ChatItem::bot(ChatMessage::text(text)));
348                }
349            }
350            if next_items.is_empty() {
351                if let Some(calls) = msg.tool_calls {
352                    for c in calls {
353                        if c.kind == "function" {
354                            next_items.push(ChatItem::call(FunctionCall {
355                                id: c.id,
356                                name: c.function.name,
357                                arguments: Some(c.function.arguments),
358                                result: None,
359                                signature: None,
360                            }));
361                            break; // mirror TS: one function call per response
362                        }
363                    }
364                }
365            }
366        }
367
368        ChatAdapterResponse {
369            next_items,
370            usage: usage.unwrap_or_default(),
371        }
372    }
373}
374
375#[cfg(test)]
376mod tests {
377    use super::*;
378    use std::net::SocketAddr;
379    use std::sync::Mutex;
380
381    use axum::{extract::Json, http::HeaderMap, routing::post, Router};
382    use wabot_feature_chat_bot::{ChatItem, ChatMessage, ModelRef};
383
384    #[tokio::test]
385    async fn end_to_end_text_response() {
386        let received: Arc<Mutex<Option<serde_json::Value>>> = Arc::new(Mutex::new(None));
387        let headers_seen: Arc<Mutex<Option<HeaderMap>>> = Arc::new(Mutex::new(None));
388        let r = received.clone();
389        let h = headers_seen.clone();
390
391        let app = Router::new().route(
392            "/v1/chat/completions",
393            post(
394                move |hdrs: HeaderMap, Json(body): Json<serde_json::Value>| {
395                    let r = r.clone();
396                    let h = h.clone();
397                    async move {
398                        *r.lock().unwrap() = Some(body);
399                        *h.lock().unwrap() = Some(hdrs);
400                        Json(serde_json::json!({
401                            "id": "chatcmpl-test",
402                            "model": "deepseek-test",
403                            "choices": [
404                                {
405                                    "index": 0,
406                                    "message": {
407                                        "role": "assistant",
408                                        "content": "hello back"
409                                    },
410                                    "finish_reason": "stop"
411                                }
412                            ],
413                            "usage": {
414                                "prompt_tokens": 20,
415                                "completion_tokens": 5,
416                                "prompt_cache_hit_tokens": 4
417                            }
418                        }))
419                    }
420                },
421            ),
422        );
423
424        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
425        let addr: SocketAddr = listener.local_addr().unwrap();
426        let server = tokio::spawn(async move {
427            let _ = axum::serve(listener, app).await;
428        });
429
430        let adapter = DeepSeekChatAdapter::new(
431            DeepSeekConfig::new("sk-test").with_base_url(format!("http://{}", addr)),
432        );
433        let req = ChatAdapterRequest {
434            models: vec![ModelRef::model("deepseek-test")],
435            system_prompt: "you are a tester".into(),
436            tools: vec![],
437            prev_items: vec![ChatItem::human(ChatMessage::text("ping"))],
438        };
439        let res = adapter.next_items(req).await.expect("ok");
440
441        assert_eq!(res.next_items.len(), 1);
442        assert_eq!(
443            res.next_items[0].as_bot().and_then(|m| m.text.as_deref()),
444            Some("hello back")
445        );
446        // DeepSeek-specific: prompt_cache_hit_tokens → cache_read_tokens.
447        assert_eq!(res.usage.input_tokens, 20);
448        assert_eq!(res.usage.output_tokens, 5);
449        assert_eq!(res.usage.cache_read_tokens, Some(4));
450        assert_eq!(res.usage.provider.as_deref(), Some("deepseek"));
451
452        let hdrs = headers_seen.lock().unwrap().clone().expect("headers");
453        assert_eq!(
454            hdrs.get("authorization").and_then(|h| h.to_str().ok()),
455            Some("Bearer sk-test")
456        );
457        let body = received.lock().unwrap().clone().expect("body");
458        assert_eq!(body["model"], "deepseek-test");
459        assert_eq!(body["messages"][0]["role"], "system");
460        assert_eq!(body["messages"][0]["content"], "you are a tester");
461        assert_eq!(body["messages"][1]["role"], "user");
462        // The user turn is a JSON rendering of the whole message, not
463        // the bare text — that is what lets an attachment the provider
464        // cannot read still be reported to the model, and it is the
465        // shape wabot-ts sends so the two can share a chat history.
466        let user: serde_json::Value =
467            serde_json::from_str(body["messages"][1]["content"].as_str().unwrap()).unwrap();
468        assert_eq!(user["text"], "ping");
469        // No tools → field omitted.
470        assert!(body.get("tools").is_none());
471
472        server.abort();
473    }
474
475    #[tokio::test]
476    async fn function_call_response() {
477        // No content; tool_calls only — mirrors the TS branch.
478        let app = Router::new().route(
479            "/v1/chat/completions",
480            post(|Json(_body): Json<serde_json::Value>| async move {
481                Json(serde_json::json!({
482                    "id": "chatcmpl-test",
483                    "model": "deepseek-test",
484                    "choices": [
485                        {
486                            "index": 0,
487                            "message": {
488                                "role": "assistant",
489                                "content": null,
490                                "tool_calls": [
491                                    {
492                                        "id": "call_1",
493                                        "type": "function",
494                                        "function": {
495                                            "name": "ping",
496                                            "arguments": "{\"x\":1}"
497                                        }
498                                    }
499                                ]
500                            },
501                            "finish_reason": "tool_calls"
502                        }
503                    ],
504                    "usage": { "prompt_tokens": 10, "completion_tokens": 2 }
505                }))
506            }),
507        );
508        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
509        let addr: SocketAddr = listener.local_addr().unwrap();
510        let server = tokio::spawn(async move {
511            let _ = axum::serve(listener, app).await;
512        });
513
514        let adapter = DeepSeekChatAdapter::new(
515            DeepSeekConfig::new("sk-test").with_base_url(format!("http://{}", addr)),
516        );
517        let res = adapter
518            .next_items(ChatAdapterRequest {
519                models: vec![ModelRef::model("deepseek-test")],
520                system_prompt: "sys".into(),
521                tools: vec![],
522                prev_items: vec![ChatItem::human(ChatMessage::text("call ping"))],
523            })
524            .await
525            .expect("ok");
526        assert_eq!(res.next_items.len(), 1);
527        let fc = res.next_items[0].as_function_call().expect("fc");
528        assert_eq!(fc.name, "ping");
529        assert_eq!(fc.id, "call_1");
530        assert_eq!(fc.arguments.as_deref(), Some("{\"x\":1}"));
531        assert_eq!(res.usage.cache_read_tokens, None);
532        server.abort();
533    }
534
535    /// Optional arguments are advertised as required-but-nullable, so
536    /// the model has to answer them explicitly instead of quietly
537    /// omitting the field. `normalize_optional_arguments` on the way
538    /// back in is what makes that safe.
539    #[test]
540    fn optional_parameters_are_required_but_nullable() {
541        use wabot_feature_chat_bot::{ToolDefinition, ToolParameter};
542
543        let tool = ToolDefinition {
544            name: "search".into(),
545            description: "search things".into(),
546            language: "english".into(),
547            parameters: vec![
548                ToolParameter {
549                    name: "query".into(),
550                    r#type: "string".into(),
551                    description: "what to look for".into(),
552                    required: true,
553                },
554                ToolParameter {
555                    name: "timezone".into(),
556                    r#type: "string".into(),
557                    description: "optional tz".into(),
558                    required: false,
559                },
560            ],
561        };
562
563        let schema = map_tool_def(tool);
564        let params = &schema["function"]["parameters"];
565
566        let required: Vec<&str> = params["required"]
567            .as_array()
568            .expect("required")
569            .iter()
570            .map(|v| v.as_str().unwrap())
571            .collect();
572        assert_eq!(
573            required,
574            vec!["query", "timezone"],
575            "the model is asked for every parameter"
576        );
577        assert_eq!(params["properties"]["query"]["type"], "string");
578        assert_eq!(
579            params["properties"]["timezone"]["type"],
580            serde_json::json!(["string", "null"]),
581            "an optional parameter accepts null"
582        );
583    }
584}