Skip to main content

wabot_addon_chat_bot_google/
lib.rs

1//! Google Gemini chat adapter — port of wabot-ts
2//! `addon/chat-bot/google/GoogleChatAdapter.ts`.
3//!
4//! Talks to `generativelanguage.googleapis.com` directly via `reqwest`;
5//! no `@google/genai` equivalent in our dep graph. Endpoint:
6//!
7//! ```text
8//! POST /v1beta/models/{model}:generateContent
9//! ```
10//!
11//! Authentication uses the `x-goog-api-key` header (Google also
12//! accepts `?key=`; the header form keeps the URL clean and lets
13//! reqwest's client manage headers per-request).
14//!
15//! Phase 4c is text-only. Vision/file mime-type mappings exist in the
16//! TS version but require fetching public URLs to base64 (Google
17//! doesn't accept arbitrary URLs except its own GCS / native file
18//! URIs). We'll port that path once multiple adapters need it.
19
20use std::sync::Arc;
21
22use async_trait::async_trait;
23use serde::Deserialize;
24use serde_json::Value;
25use uuid::Uuid;
26
27use wabot_feature_chat_bot::{
28    analyzable_documents, analyzable_images, extract_chat_message_text, ChatAdapter,
29    ChatAdapterError, ChatAdapterRequest, ChatAdapterResponse, ChatItem, ChatMessage, FunctionCall,
30    LanguageModelUsage, SupportedMedia,
31};
32
33pub const PROVIDER: &str = "google";
34const DEFAULT_BASE_URL: &str = "https://generativelanguage.googleapis.com";
35const DEFAULT_API_VERSION: &str = "v1beta";
36
37/// Configuration for the Google Gemini adapter.
38#[derive(Debug, Clone)]
39pub struct GoogleConfig {
40    pub api_key: String,
41    pub base_url: String,
42    pub api_version: String,
43}
44
45impl GoogleConfig {
46    pub fn new(api_key: impl Into<String>) -> Self {
47        Self {
48            api_key: api_key.into(),
49            base_url: DEFAULT_BASE_URL.into(),
50            api_version: DEFAULT_API_VERSION.into(),
51        }
52    }
53
54    pub fn from_env(var: &str) -> Self {
55        let key =
56            std::env::var(var).unwrap_or_else(|_| panic!("missing Google API key env var: {var}"));
57        Self::new(key)
58    }
59
60    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
61        self.base_url = base_url.into();
62        self
63    }
64
65    pub fn with_api_version(mut self, version: impl Into<String>) -> Self {
66        self.api_version = version.into();
67        self
68    }
69}
70
71pub struct GoogleChatAdapter {
72    inner: Arc<Inner>,
73}
74
75struct Inner {
76    config: GoogleConfig,
77    http: reqwest::Client,
78}
79
80impl GoogleChatAdapter {
81    pub fn new(config: GoogleConfig) -> Self {
82        Self {
83            inner: Arc::new(Inner {
84                config,
85                http: reqwest::Client::builder()
86                    .build()
87                    .expect("reqwest client build"),
88            }),
89        }
90    }
91}
92
93impl wabot_core::injection::IsSingleton for GoogleChatAdapter {
94    fn register_in(c: &wabot_core::injection::Container) {
95        c.register_singleton_factory::<GoogleChatAdapter, _>(|c2| {
96            let cfg: Arc<GoogleConfig> = c2.resolve::<GoogleConfig>();
97            Arc::new(GoogleChatAdapter::new((*cfg).clone()))
98        });
99    }
100}
101
102#[async_trait]
103impl ChatAdapter for GoogleChatAdapter {
104    async fn next_items(
105        &self,
106        req: ChatAdapterRequest,
107    ) -> Result<ChatAdapterResponse, ChatAdapterError> {
108        // Build `contents`. Google has no separate `system` field on
109        // the v1beta endpoint — the TS adapter passes the system
110        // prompt as the first user-role content. Mirror that here.
111        let mut contents: Vec<Value> = Vec::with_capacity(req.prev_items.len() + 1);
112        contents.push(serde_json::json!({
113            "role": "user",
114            "parts": [{ "text": req.system_prompt }]
115        }));
116        for item in &req.prev_items {
117            push_chat_item(&mut contents, item);
118        }
119
120        let function_declarations: Vec<Value> = req.tools.into_iter().map(map_tool_def).collect();
121        let mut tools: Vec<Value> = Vec::new();
122        if !function_declarations.is_empty() {
123            tools.push(serde_json::json!({
124                "functionDeclarations": function_declarations,
125            }));
126        }
127
128        // If any prior function call lacks a thought-signature, set
129        // thinkingBudget=0 to skip the model's reasoning step — matches
130        // the TS adapter's `hasUnsignedFunctionCall` guard.
131        let has_unsigned_function_call = req.prev_items.iter().any(|it| {
132            it.as_function_call()
133                .is_some_and(|fc| fc.signature.is_none())
134        });
135
136        let mut last_err: Option<ChatAdapterError> = None;
137        for model in &req.models {
138            let mut config = serde_json::json!({});
139            if !tools.is_empty() {
140                config["tools"] = Value::Array(tools.clone());
141            }
142            if has_unsigned_function_call {
143                config["thinkingConfig"] = serde_json::json!({ "thinkingBudget": 0 });
144            }
145            let body = serde_json::json!({
146                "contents": contents,
147                "generationConfig": config,
148            });
149
150            tracing::debug!(
151                provider = PROVIDER,
152                model = %model.model,
153                contents = contents.len(),
154                tools = function_declarations.len(),
155                "google request"
156            );
157
158            let url = format!(
159                "{}/{}/models/{}:generateContent",
160                self.inner.config.base_url, self.inner.config.api_version, model.model
161            );
162            let res = self
163                .inner
164                .http
165                .post(&url)
166                .header("x-goog-api-key", &self.inner.config.api_key)
167                .header("content-type", "application/json")
168                .json(&body)
169                .send()
170                .await
171                .map_err(|e| ChatAdapterError::Transport(e.to_string()))?;
172
173            let status = res.status();
174            let raw = res
175                .text()
176                .await
177                .map_err(|e| ChatAdapterError::Transport(e.to_string()))?;
178
179            if !status.is_success() {
180                let err = ChatAdapterError::Provider {
181                    provider: PROVIDER,
182                    status: status.as_u16(),
183                    body: raw,
184                };
185                if is_retryable_status(status.as_u16()) {
186                    tracing::warn!(error = %err, "google retryable error; trying next model");
187                    last_err = Some(err);
188                    continue;
189                }
190                return Err(err);
191            }
192
193            let parsed: GoogleResponse = serde_json::from_str(&raw)
194                .map_err(|e| ChatAdapterError::InvalidResponse(e.to_string()))?;
195            return Ok(parsed.into_adapter_response(&model.model));
196        }
197
198        Err(last_err.unwrap_or(ChatAdapterError::NoModelAvailable))
199    }
200}
201
202fn is_retryable_status(status: u16) -> bool {
203    matches!(status, 408 | 429 | 500 | 502 | 503 | 504)
204}
205
206fn push_chat_item(contents: &mut Vec<Value>, item: &ChatItem) {
207    match item {
208        ChatItem::HumanMessage { human_message } => {
209            contents.push(map_human_message(human_message));
210        }
211        ChatItem::BotMessage { bot_message } => {
212            contents.push(map_bot_message(bot_message));
213        }
214        ChatItem::FunctionCall { function_call } => {
215            contents.extend(map_function_call(function_call));
216        }
217    }
218}
219
220const SUPPORTED: SupportedMedia = SupportedMedia {
221    images: Some(&[
222        "image/png",
223        "image/jpeg",
224        "image/webp",
225        "image/heic",
226        "image/heif",
227    ]),
228    documents: Some(&["application/pdf"]),
229};
230
231/// Gemini names its two forms `inlineData` and `fileData`, and unlike
232/// the others it wants the mime type on both.
233fn media_part(file: &wabot_feature_chat_bot::ChatMessageFile) -> Option<Value> {
234    if let Some(url) = &file.public_url {
235        return Some(serde_json::json!({
236            "fileData": { "mimeType": file.mime_type, "fileUri": url }
237        }));
238    }
239    let data = file.base64_url.as_deref()?;
240    let payload = data
241        .split_once("base64,")
242        .map(|(_, rest)| rest)
243        .unwrap_or(data);
244    Some(serde_json::json!({
245        "inlineData": { "mimeType": file.mime_type, "data": payload }
246    }))
247}
248
249fn map_human_message(m: &ChatMessage) -> Value {
250    let mut parts = vec![serde_json::json!({
251        "text": extract_chat_message_text(m, SUPPORTED),
252    })];
253    for file in analyzable_images(m, SUPPORTED)
254        .into_iter()
255        .chain(analyzable_documents(m, SUPPORTED))
256    {
257        if let Some(part) = media_part(file) {
258            parts.push(part);
259        }
260    }
261    serde_json::json!({ "role": "user", "parts": parts })
262}
263
264fn map_bot_message(m: &ChatMessage) -> Value {
265    let text = m.text.clone().unwrap_or_default();
266    serde_json::json!({
267        "role": "model",
268        "parts": [{ "text": text }]
269    })
270}
271
272fn map_function_call(fc: &FunctionCall) -> Vec<Value> {
273    let args = fc
274        .arguments
275        .as_deref()
276        .and_then(|s| serde_json::from_str::<Value>(s).ok())
277        .unwrap_or_else(|| serde_json::json!({}));
278    let mut call_part = serde_json::json!({
279        "functionCall": {
280            "id": fc.id,
281            "name": fc.name,
282            "args": args,
283        }
284    });
285    if let Some(sig) = &fc.signature {
286        call_part["thoughtSignature"] = Value::String(sig.clone());
287    }
288    let result = fc.result.clone().unwrap_or_default();
289    vec![
290        serde_json::json!({
291            "role": "model",
292            "parts": [call_part]
293        }),
294        serde_json::json!({
295            "role": "function",
296            "parts": [
297                {
298                    "functionResponse": {
299                        "id": fc.id,
300                        "name": fc.name,
301                        "response": { "output": result }
302                    }
303                }
304            ]
305        }),
306    ]
307}
308
309fn map_tool_def(t: wabot_feature_chat_bot::ToolDefinition) -> Value {
310    let properties: serde_json::Map<String, Value> = t
311        .parameters
312        .iter()
313        .map(|p| {
314            // Same trade as the other adapters — the model must answer
315            // every parameter, and `null` is how it says "no value" —
316            // but Gemini's schema spells nullability with a flag
317            // rather than a type union.
318            (
319                p.name.clone(),
320                serde_json::json!({
321                    "type": p.r#type,
322                    "description": p.description,
323                    "nullable": !p.required,
324                }),
325            )
326        })
327        .collect();
328    // Every parameter, including the optional ones — see above.
329    let required: Vec<String> = t.parameters.iter().map(|p| p.name.clone()).collect();
330    serde_json::json!({
331        "name": t.name,
332        "description": t.description,
333        "parametersJsonSchema": {
334            "type": "object",
335            "properties": properties,
336            "required": required,
337            "additionalProperties": false,
338        }
339    })
340}
341
342// ----- wire-format response types --------------------------------------
343
344#[derive(Debug, Deserialize)]
345struct GoogleResponse {
346    #[serde(default)]
347    candidates: Vec<GoogleCandidate>,
348    #[serde(rename = "modelVersion", default)]
349    model_version: Option<String>,
350    #[serde(rename = "usageMetadata")]
351    usage_metadata: Option<GoogleUsageMetadata>,
352}
353
354#[derive(Debug, Deserialize)]
355struct GoogleCandidate {
356    #[serde(default)]
357    content: Option<GoogleContent>,
358}
359
360#[derive(Debug, Deserialize)]
361struct GoogleContent {
362    #[serde(default)]
363    parts: Vec<GooglePart>,
364}
365
366#[derive(Debug, Deserialize)]
367struct GooglePart {
368    #[serde(default)]
369    text: Option<String>,
370    #[serde(rename = "functionCall", default)]
371    function_call: Option<GoogleFunctionCall>,
372    #[serde(rename = "thoughtSignature", default)]
373    thought_signature: Option<String>,
374}
375
376#[derive(Debug, Deserialize)]
377struct GoogleFunctionCall {
378    #[serde(default)]
379    id: Option<String>,
380    name: String,
381    #[serde(default)]
382    args: Option<Value>,
383}
384
385#[derive(Debug, Deserialize)]
386struct GoogleUsageMetadata {
387    #[serde(rename = "promptTokenCount", default)]
388    prompt_token_count: u64,
389    #[serde(rename = "candidatesTokenCount", default)]
390    candidates_token_count: u64,
391    #[serde(rename = "cachedContentTokenCount", default)]
392    cached_content_token_count: Option<u64>,
393}
394
395impl GoogleResponse {
396    fn into_adapter_response(self, requested_model: &str) -> ChatAdapterResponse {
397        let usage = self.usage_metadata.map(|u| {
398            let cache_read = u.cached_content_token_count.unwrap_or(0);
399            LanguageModelUsage {
400                input_tokens: u.prompt_token_count,
401                output_tokens: u.candidates_token_count,
402                cache_read_tokens: (cache_read > 0).then_some(cache_read),
403                cache_write_tokens: None,
404                cost_usd: None,
405                provider: Some(PROVIDER.into()),
406                model: self
407                    .model_version
408                    .clone()
409                    .or_else(|| Some(requested_model.into())),
410            }
411        });
412
413        let mut next_items: Vec<ChatItem> = Vec::new();
414        if let Some(candidate) = self.candidates.into_iter().find(|c| c.content.is_some()) {
415            if let Some(content) = candidate.content {
416                for part in content.parts {
417                    if let Some(text) = part.text.filter(|t| !t.is_empty()) {
418                        next_items.push(ChatItem::bot(ChatMessage::text(text)));
419                    }
420                    if let Some(fc) = part.function_call {
421                        // Google sometimes omits the function-call id —
422                        // mint one so downstream tool-result pairing
423                        // still works (mirrors the TS Random.alphaNumeric).
424                        let id = fc.id.unwrap_or_else(short_id);
425                        let args_json = fc
426                            .args
427                            .map(|v| v.to_string())
428                            .unwrap_or_else(|| "{}".into());
429                        next_items.push(ChatItem::call(FunctionCall {
430                            id,
431                            name: fc.name,
432                            arguments: Some(args_json),
433                            result: None,
434                            signature: part.thought_signature,
435                        }));
436                    }
437                }
438            }
439        }
440
441        ChatAdapterResponse {
442            next_items,
443            usage: usage.unwrap_or_default(),
444        }
445    }
446}
447
448fn short_id() -> String {
449    // 10-char prefix of a UUID v4 — same idea as TS's
450    // Random.alphaNumericLowerCase(10).
451    let s = Uuid::new_v4().simple().to_string();
452    s.chars().take(10).collect()
453}
454
455#[cfg(test)]
456mod tests {
457    use super::*;
458    use std::net::SocketAddr;
459    use std::sync::Mutex;
460
461    use axum::{extract::Json, http::HeaderMap, routing::post, Router};
462    use wabot_feature_chat_bot::{ChatItem, ChatMessage, ModelRef};
463
464    #[tokio::test]
465    async fn end_to_end_text_and_function_call() {
466        let received: Arc<Mutex<Option<serde_json::Value>>> = Arc::new(Mutex::new(None));
467        let headers_seen: Arc<Mutex<Option<HeaderMap>>> = Arc::new(Mutex::new(None));
468        let r = received.clone();
469        let h = headers_seen.clone();
470
471        // generateContent endpoint includes the model name in the path.
472        let app = Router::new().route(
473            "/v1beta/models/gemini-test-1:generateContent",
474            post(
475                move |hdrs: HeaderMap, Json(body): Json<serde_json::Value>| {
476                    let r = r.clone();
477                    let h = h.clone();
478                    async move {
479                        *r.lock().unwrap() = Some(body);
480                        *h.lock().unwrap() = Some(hdrs);
481                        Json(serde_json::json!({
482                            "candidates": [
483                                {
484                                    "content": {
485                                        "role": "model",
486                                        "parts": [
487                                            { "text": "hello back" },
488                                            {
489                                                "functionCall": {
490                                                    "name": "ping",
491                                                    "args": { "x": 1 }
492                                                },
493                                                "thoughtSignature": "sig-1"
494                                            }
495                                        ]
496                                    }
497                                }
498                            ],
499                            "usageMetadata": {
500                                "promptTokenCount": 18,
501                                "candidatesTokenCount": 6,
502                                "cachedContentTokenCount": 2
503                            },
504                            "modelVersion": "gemini-test-1-001"
505                        }))
506                    }
507                },
508            ),
509        );
510
511        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
512        let addr: SocketAddr = listener.local_addr().unwrap();
513        let server = tokio::spawn(async move {
514            let _ = axum::serve(listener, app).await;
515        });
516
517        let adapter = GoogleChatAdapter::new(
518            GoogleConfig::new("test-key").with_base_url(format!("http://{}", addr)),
519        );
520        let res = adapter
521            .next_items(ChatAdapterRequest {
522                models: vec![ModelRef::model("gemini-test-1")],
523                system_prompt: "you are a tester".into(),
524                tools: vec![],
525                prev_items: vec![ChatItem::human(ChatMessage::text("ping"))],
526            })
527            .await
528            .expect("ok");
529
530        // Response: text first, then function call (with assigned id +
531        // captured signature).
532        assert_eq!(res.next_items.len(), 2);
533        assert_eq!(
534            res.next_items[0].as_bot().and_then(|m| m.text.as_deref()),
535            Some("hello back")
536        );
537        let fc = res.next_items[1].as_function_call().expect("fc");
538        assert_eq!(fc.name, "ping");
539        assert!(!fc.id.is_empty()); // minted because the server omitted one
540        assert_eq!(fc.signature.as_deref(), Some("sig-1"));
541        assert_eq!(fc.arguments.as_deref(), Some("{\"x\":1}"));
542
543        // Usage: cachedContentTokenCount → cache_read_tokens;
544        // modelVersion wins.
545        assert_eq!(res.usage.input_tokens, 18);
546        assert_eq!(res.usage.output_tokens, 6);
547        assert_eq!(res.usage.cache_read_tokens, Some(2));
548        assert_eq!(res.usage.model.as_deref(), Some("gemini-test-1-001"));
549        assert_eq!(res.usage.provider.as_deref(), Some("google"));
550
551        // Request: x-goog-api-key header + body shape.
552        let hdrs = headers_seen.lock().unwrap().clone().expect("headers");
553        assert_eq!(
554            hdrs.get("x-goog-api-key").and_then(|h| h.to_str().ok()),
555            Some("test-key")
556        );
557        let body = received.lock().unwrap().clone().expect("body");
558        // System prompt rides as the first content item with role=user.
559        assert_eq!(body["contents"][0]["role"], "user");
560        assert_eq!(body["contents"][0]["parts"][0]["text"], "you are a tester");
561        // Actual human message becomes the second content.
562        assert_eq!(body["contents"][1]["role"], "user");
563        // The user turn is a JSON rendering of the whole message, not
564        // the bare text: an attachment the provider cannot read is
565        // still reported to the model, and the shape matches what
566        // wabot-ts sends so the two can share a chat history.
567        let user: serde_json::Value =
568            serde_json::from_str(body["contents"][1]["parts"][0]["text"].as_str().unwrap())
569                .unwrap();
570        assert_eq!(user["text"], "ping");
571
572        server.abort();
573    }
574
575    /// Optional arguments are advertised as required-but-nullable, so
576    /// the model has to answer them explicitly instead of quietly
577    /// omitting the field. `normalize_optional_arguments` on the way
578    /// back in is what makes that safe.
579    #[test]
580    fn optional_parameters_are_required_but_nullable() {
581        use wabot_feature_chat_bot::{ToolDefinition, ToolParameter};
582
583        let tool = ToolDefinition {
584            name: "search".into(),
585            description: "search things".into(),
586            language: "english".into(),
587            parameters: vec![
588                ToolParameter {
589                    name: "query".into(),
590                    r#type: "string".into(),
591                    description: "what to look for".into(),
592                    required: true,
593                },
594                ToolParameter {
595                    name: "timezone".into(),
596                    r#type: "string".into(),
597                    description: "optional tz".into(),
598                    required: false,
599                },
600            ],
601        };
602
603        let schema = map_tool_def(tool);
604        let params = &schema["parametersJsonSchema"];
605
606        let required: Vec<&str> = params["required"]
607            .as_array()
608            .expect("required")
609            .iter()
610            .map(|v| v.as_str().unwrap())
611            .collect();
612        assert_eq!(
613            required,
614            vec!["query", "timezone"],
615            "the model is asked for every parameter"
616        );
617        assert_eq!(params["properties"]["query"]["type"], "string");
618        assert_eq!(params["properties"]["query"]["nullable"], false);
619        assert_eq!(
620            params["properties"]["timezone"]["nullable"], true,
621            "an optional parameter accepts null"
622        );
623    }
624}