docs: add CJK language limitation warning for Gemini 2.5 models (#2134)

codegen_instructions.md

@@ -85,6 +85,16 @@ client = genai.Client()
     -   **Gemini 2.0 Series**: `gemini-2.0-flash`, `gemini-2.0-flash-lite`
     -   **Gemini 2.5 Series**: `gemini-2.5-flash`, `gemini-2.5-pro`
 
+> **⚠️ Known limitation — Gemini 2.5 series (CJK languages):** All Gemini 2.5
+> models (`gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-2.5-flash-lite`)
+> currently fail to correctly process CJK (Japanese, Chinese, Korean) text
+> input via the REST API. The model may interpret valid UTF-8 CJK characters as
+> garbled/corrupted text. Google Search Grounding is also affected —
+> `webSearchQueries` returns empty `[]` for CJK input on these models.
+> **If your application requires CJK language input, use `gemini-3-pro-preview`
+> or another Gemini 3.x model as a workaround until this is resolved.**
+> See [issue #2134](https://github.com/googleapis/python-genai/issues/2134).
+
 -   Do not use the following deprecated models (or their variants like
     `gemini-1.5-flash-latest`):
     -   **Prohibited:** `gemini-1.5-flash`
@@ -597,6 +607,49 @@ for n, generated_video in enumerate(operation.response.generated_videos):
     generated_video.video.save(f'video{n}.mp4')  # saves the video
 ```
 
+### Search Grounding
+
+Google Search can be used as a tool for grounding queries that with up to date
+information from the web.
+
+**Correct**
+
+```python
+from google import genai
+from google.genai import types
+
+client = genai.Client()
+
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents='What was the score of the latest Olympique Lyonais game?',
+    config=types.GenerateContentConfig(
+        tools=[
+            types.Tool(google_search=types.GoogleSearch())
+        ]
+    ),
+)
+
+# Response
+print(f'Response:\n {response.text}')
+# Search details
+print(f'Search Query: {response.candidates[0].grounding_metadata.web_search_queries}')
+# Urls used for grounding
+print(f"Search Pages: {', '.join([site.web.title for site in response.candidates[0].grounding_metadata.grounding_chunks])}")
+```
+
+The output `response.text` will likely not be in JSON format, do not attempt to
+parse it as JSON.
+
+> **⚠️ Known limitation — CJK languages with Gemini 2.5:** Search Grounding
+> does not work correctly with CJK (Japanese, Chinese, Korean) input on any
+> Gemini 2.5 model. `webSearchQueries` returns an empty list `[]` and the model
+> treats the input as garbled text. English input on the same models works
+> correctly. **Use a Gemini 3.x model (e.g. `gemini-3-pro-preview`) for Search
+> Grounding with CJK queries.**
+> See [issue #2134](https://github.com/googleapis/python-genai/issues/2134).
+
+### Content and Part Hierarchy
 ## Content and Part Hierarchy
 
 While the simpler API call is often sufficient, you may run into scenarios where