fix(litellm): parse DeepSeek-V3 proprietary inline tool-call tokens

Merge #5654

Closes #5024

## Problem

DeepSeek-V3 emits tool calls using proprietary special tokens embedded in the content field:

```
<｜tool▁calls▁begin｜><｜tool▁call▁begin｜>function<｜tool▁sep｜>analysis_input
```json
{"work_dir_name":"..."}
```<｜tool▁call▁end｜><｜tool▁calls▁end｜>
```

When LiteLLM does not translate these into structured `tool_calls` (intermittent), ADK's fallback JSON parser finds the JSON object but rejects it because the function name (`analysis_input`) is embedded in the tokens (`<｜tool▁sep｜>analysis_input`) rather than as a `name` key inside the JSON payload.

**Result:** tool call is silently dropped and the raw tokens appear as text content.

## Solution

- Added `_parse_deepseek_tool_calls_from_text` — detects the proprietary token format, extracts function name + arguments, and emits standard `ChatCompletionMessageToolCall` objects
- Added `_extract_json_from_deepseek_args` helper — handles optional Markdown code fences (```` ```json ``` ````) around the arguments payload
- Integrated into the existing `_parse_tool_calls_from_text` as the first-pass parser, with fallback to generic inline JSON parsing
- Supports: single tool calls, multi-tool calls, code-fenced JSON, bare JSON, surrounding text, mixed formats

## Testing Plan

**Unit Tests:** Added 8 new tests covering:
- Single tool call with code-fenced JSON args
- Multiple tool calls in a single wrapped block
- Bare JSON args (no code fences)
- Tool call embedded in surrounding text
- Text without DeepSeek tokens (no false positives)
- Empty/whitespace-only text
- Integration test via `_parse_tool_calls_from_text`
- Mixed formats (DeepSeek tokens + standard inline JSON)

**Regression:** Full `test_litellm.py`: **264 passed, 0 failed**

## Files Changed

| File | Changes |
|------|--------|
| `src/google/adk/models/lite_llm.py` | +147 lines (2 new functions + integration) |
| `tests/unittests/models/test_litellm.py` | +124 lines (8 new test functions) |

Co-authored-by: George Weale <gweale@google.com>
COPYBARA_INTEGRATE_REVIEW=#5654 from fuchun1010:fix/deepseek-tool-call-parsing 44ca518
PiperOrigin-RevId: 940608071

Author: 2 people

src/google/adk/models/lite_llm.py

@@ -1494,6 +1494,152 @@ def _build_tool_call_from_json_dict(
   return tool_call
 
 
+# DeepSeek models may emit tool calls as inline text using proprietary
+# special tokens. See https://api-docs.deepseek.com/guides/function_calling
+# for the full specification. LiteLLM usually translates these into
+# structured `tool_calls` but when it doesn't (intermittent), the raw
+# tokens land in the `content` field and must be parsed here.
+_DS_TCALLS_BEGIN = "\u003c\uff5ctool\u2581calls\u2581begin\uff5c\u003e"
+_DS_TCALLS_END = "\u003c\uff5ctool\u2581calls\u2581end\uff5c\u003e"
+_DS_TCALL_BEGIN = "\u003c\uff5ctool\u2581call\u2581begin\uff5c\u003e"
+_DS_TCALL_END = "\u003c\uff5ctool\u2581call\u2581end\uff5c\u003e"
+_DS_TSEP = "\u003c\uff5ctool\u2581sep\uff5c\u003e"
+
+# Pattern: <｜tool▁call▁begin｜>function<｜tool▁sep｜>NAME \n ARGS <｜tool▁call▁end｜>
+_DS_TOOL_CALL_RE = re.compile(
+    re.escape(_DS_TCALL_BEGIN)
+    + r"function"
+    + re.escape(_DS_TSEP)
+    + r"([^\n\r]+?)\s*?\n(.*?)"
+    + re.escape(_DS_TCALL_END),
+    re.DOTALL,
+)
+
+
+def _extract_json_from_deepseek_args(args_text: str) -> Optional[str]:
+  """Extracts a JSON string from DeepSeek arguments text.
+
+  Args:
+    args_text: Raw text containing the function arguments, possibly
+      wrapped in Markdown-style code fences.
+
+  Returns:
+    The JSON string, or None if no valid JSON object could be found.
+  """
+  if not args_text:
+    return None
+  # Strip optional Markdown code fences (```json ... ``` or ``` ... ```).
+  fence_match = re.search(r"```(?:json)?\s*(\{[\s\S]*?\})\s*```", args_text)
+  if fence_match:
+    candidate = fence_match.group(1).strip()
+    try:
+      json.loads(candidate)
+      return candidate
+    except json.JSONDecodeError:
+      pass
+  # Fall back to the first balanced { … } block.
+  open_brace = args_text.find("{")
+  if open_brace == -1:
+    return None
+  try:
+    candidate, _ = _JSON_DECODER.raw_decode(args_text, open_brace)
+    return json.dumps(candidate, ensure_ascii=False)
+  except json.JSONDecodeError:
+    return None
+
+
+def _parse_deepseek_tool_calls_from_text(
+    text_block: str,
+) -> tuple[list[ChatCompletionMessageToolCall], Optional[str]]:
+  """Parses DeepSeek proprietary inline tool-call tokens from text.
+
+  When LiteLLM does not translate DeepSeek's special tokens into
+  structured ``tool_calls``, the raw tokens appear inside the ``content``
+  field.  This function extracts them and returns standard
+  ``ChatCompletionMessageToolCall`` objects.
+
+  Token reference
+    ``<｜tool▁calls▁begin｜>`` … ``<｜tool▁calls▁end｜>``  → outer wrapper
+    ``<｜tool▁call▁begin｜>function<｜tool▁sep｜>NAME``  → single call start
+    ``<｜tool▁call▁end｜>``                             → single call end
+
+  Args:
+    text_block: The raw text that may contain DeepSeek tokens.
+
+  Returns:
+    A tuple of ``(tool_calls, remainder)`` where ``remainder`` is the
+    original text with all DeepSeek token regions removed.
+  """
+  _ensure_litellm_imported()
+
+  tool_calls: list[ChatCompletionMessageToolCall] = []
+  if not text_block:
+    return tool_calls, None
+
+  # Quick guard: only invoke the regex if the outer tokens are present.
+  if _DS_TCALLS_BEGIN not in text_block and _DS_TCALL_BEGIN not in text_block:
+    return tool_calls, None
+
+  remainder_parts: list[str] = []
+  cursor = 0
+
+  # Outer loop — wrapped <｜tool▁calls▁begin｜> blocks and unwrapped
+  # <｜tool▁call▁begin｜> tokens may interleave, so process whichever
+  # token appears first.
+  while True:
+    calls_idx = text_block.find(_DS_TCALLS_BEGIN, cursor)
+    call_idx = text_block.find(_DS_TCALL_BEGIN, cursor)
+    if calls_idx == -1 and call_idx == -1:
+      remainder_parts.append(text_block[cursor:])
+      break
+
+    if calls_idx != -1 and (call_idx == -1 or calls_idx < call_idx):
+      begin_idx = calls_idx
+      in_wrapped_block = True
+    else:
+      begin_idx = call_idx
+      in_wrapped_block = False
+
+    # Everything before the token becomes remainder.
+    if begin_idx > cursor:
+      remainder_parts.append(text_block[cursor:begin_idx])
+
+    if in_wrapped_block:
+      end_idx = text_block.find(
+          _DS_TCALLS_END, begin_idx + len(_DS_TCALLS_BEGIN)
+      )
+      if end_idx == -1:
+        remainder_parts.append(text_block[begin_idx:])
+        break
+      block = text_block[begin_idx + len(_DS_TCALLS_BEGIN) : end_idx]
+      cursor = end_idx + len(_DS_TCALLS_END)
+    else:
+      # Unwrapped call token — scan for a matching end token.
+      end_idx = text_block.find(_DS_TCALL_END, begin_idx + len(_DS_TCALL_BEGIN))
+      if end_idx == -1:
+        remainder_parts.append(text_block[begin_idx:])
+        break
+      block = text_block[begin_idx : end_idx + len(_DS_TCALL_END)]
+      cursor = end_idx + len(_DS_TCALL_END)
+
+    # Parse individual tool calls inside the block.
+    for match in _DS_TOOL_CALL_RE.finditer(block):
+      func_name = match.group(1).strip()
+      args_raw = match.group(2).strip()
+      args_json = _extract_json_from_deepseek_args(args_raw)
+      if not func_name or not args_json:
+        continue
+      tool_call = _build_tool_call_from_json_dict(
+          {"name": func_name, "arguments": args_json},
+          index=len(tool_calls),
+      )
+      if tool_call:
+        tool_calls.append(tool_call)
+
+  remainder = "".join(p for p in remainder_parts if p).strip()
+  return tool_calls, remainder or None
+
+
 def _parse_tool_calls_from_text(
     text_block: str,
 ) -> tuple[list[ChatCompletionMessageToolCall], Optional[str]]:
@@ -1504,6 +1650,17 @@ def _parse_tool_calls_from_text(
 
   _ensure_litellm_imported()
 
+  # Try DeepSeek proprietary format first, then fall back to generic JSON.
+  ds_tool_calls, ds_remainder = _parse_deepseek_tool_calls_from_text(text_block)
+  if ds_tool_calls:
+    # If the remainder still contains content, re-parse it for
+    # additional generic inline JSON tool calls (mixed formats).
+    if ds_remainder:
+      extra_calls, extra_remainder = _parse_tool_calls_from_text(ds_remainder)
+      tool_calls = ds_tool_calls + (extra_calls or [])
+      return tool_calls, extra_remainder
+    return ds_tool_calls, None
+
   remainder_segments = []
   cursor = 0
   text_length = len(text_block)

tests/unittests/models/test_litellm.py

@@ -31,6 +31,7 @@
 from google.adk.models.lite_llm import _content_to_message_param
 from google.adk.models.lite_llm import _convert_reasoning_value_to_parts
 from google.adk.models.lite_llm import _enforce_strict_openai_schema
+from google.adk.models.lite_llm import _extract_json_from_deepseek_args
 from google.adk.models.lite_llm import _extract_reasoning_value
 from google.adk.models.lite_llm import _extract_thought_signature_from_tool_call
 from google.adk.models.lite_llm import _FILE_ID_REQUIRED_PROVIDERS
@@ -47,6 +48,7 @@
 from google.adk.models.lite_llm import _MISSING_TOOL_RESULT_MESSAGE
 from google.adk.models.lite_llm import _model_response_to_chunk
 from google.adk.models.lite_llm import _model_response_to_generate_content_response
+from google.adk.models.lite_llm import _parse_deepseek_tool_calls_from_text
 from google.adk.models.lite_llm import _parse_tool_calls_from_text
 from google.adk.models.lite_llm import _redact_file_uri_for_log
 from google.adk.models.lite_llm import _redirect_litellm_loggers_to_stdout
@@ -2911,6 +2913,145 @@ def test_parse_tool_calls_from_text_invalid_json_returns_remainder():
   assert remainder == 'Leading {"unused": "payload"} trailing text'
 
 
+# ---------------------------------------------------------------------------
+# DeepSeek proprietary inline tool-call format tests
+# ---------------------------------------------------------------------------
+
+_DS_BEGIN_CALLS = "\u003c\uff5ctool\u2581calls\u2581begin\uff5c\u003e"
+_DS_END_CALLS = "\u003c\uff5ctool\u2581calls\u2581end\uff5c\u003e"
+_DS_BEGIN_CALL = "\u003c\uff5ctool\u2581call\u2581begin\uff5c\u003e"
+_DS_END_CALL = "\u003c\uff5ctool\u2581call\u2581end\uff5c\u003e"
+_DS_SEP = "\u003c\uff5ctool\u2581sep\uff5c\u003e"
+
+
+def _ds_tool_call(name: str, args_json: str) -> str:
+  """Build a single DeepSeek-style tool-call block."""
+  return (
+      f"{_DS_BEGIN_CALL}function{_DS_SEP}{name}\n"
+      f"```json\n{args_json}\n```"
+      f"{_DS_END_CALL}"
+  )
+
+
+def _ds_wrapped(inner: str) -> str:
+  """Wrap content in <｜tool▁calls▁begin｜>...<｜tool▁calls▁end｜>."""
+  return f"{_DS_BEGIN_CALLS}{inner}{_DS_END_CALLS}"
+
+
+def test_parse_deepseek_single_tool_call():
+  """Single DeepSeek tool call with code-fenced JSON args."""
+  text = _ds_wrapped(
+      _ds_tool_call("get_weather", '{"city": "Beijing", "unit": "celsius"}')
+  )
+  tool_calls, remainder = _parse_deepseek_tool_calls_from_text(text)
+  assert len(tool_calls) == 1
+  assert tool_calls[0].function.name == "get_weather"
+  assert json.loads(tool_calls[0].function.arguments) == {
+      "city": "Beijing",
+      "unit": "celsius",
+  }
+  assert remainder is None
+
+
+def test_parse_deepseek_multi_tool_call():
+  """Multiple DeepSeek tool calls in a single wrapped block."""
+  inner = _ds_tool_call("func_a", '{"x": 1}') + _ds_tool_call(
+      "func_b", '{"y": 2}'
+  )
+  text = _ds_wrapped(inner)
+  tool_calls, remainder = _parse_deepseek_tool_calls_from_text(text)
+  assert len(tool_calls) == 2
+  assert tool_calls[0].function.name == "func_a"
+  assert json.loads(tool_calls[0].function.arguments) == {"x": 1}
+  assert tool_calls[1].function.name == "func_b"
+  assert json.loads(tool_calls[1].function.arguments) == {"y": 2}
+  assert remainder is None
+
+
+def test_parse_deepseek_plain_json_args():
+  """DeepSeek tool call without Markdown code fences around args."""
+  inner = (
+      f"{_DS_BEGIN_CALL}function{_DS_SEP}search\n"
+      f'{{"query": "天气"}}'
+      f"{_DS_END_CALL}"
+  )
+  text = _ds_wrapped(inner)
+  tool_calls, remainder = _parse_deepseek_tool_calls_from_text(text)
+  assert len(tool_calls) == 1
+  assert tool_calls[0].function.name == "search"
+  assert json.loads(tool_calls[0].function.arguments) == {"query": "天气"}
+
+
+def test_parse_deepseek_with_surrounding_text():
+  """DeepSeek tool call embedded in surrounding non-tool text."""
+  prefix = "Let me think about this.\n"
+  suffix = "\nI'll proceed now."
+  inner = _ds_tool_call("calculate", '{"expr": "2+2"}')
+  text = prefix + _ds_wrapped(inner) + suffix
+  tool_calls, remainder = _parse_deepseek_tool_calls_from_text(text)
+  assert len(tool_calls) == 1
+  assert tool_calls[0].function.name == "calculate"
+  assert remainder == "Let me think about this.\n\nI'll proceed now."
+
+
+def test_parse_deepseek_no_tokens_returns_empty():
+  """Text without DeepSeek tokens returns no tool calls and None remainder."""
+  text = "Just a regular response, no special tokens here."
+  tool_calls, remainder = _parse_deepseek_tool_calls_from_text(text)
+  assert tool_calls == []
+  assert remainder is None
+
+
+def test_parse_tool_calls_from_text_handles_deepseek_format():
+  """Integration: the generic parser delegates to the DeepSeek parser."""
+  text = _ds_wrapped(
+      _ds_tool_call("fetch_page", '{"url": "https://example.com"}')
+  )
+  tool_calls, remainder = _parse_tool_calls_from_text(text)
+  assert len(tool_calls) == 1
+  assert tool_calls[0].function.name == "fetch_page"
+  assert json.loads(tool_calls[0].function.arguments) == {
+      "url": "https://example.com"
+  }
+  assert remainder is None
+
+
+def test_parse_tool_calls_from_text_mixed_formats():
+  """DeepSeek tokens + standard inline JSON in the same text."""
+  ds_part = _ds_wrapped(_ds_tool_call("ds_func", '{"a": 1}'))
+  standard_part = '{"name": "std_func", "arguments": {"b": 2}}'
+  text = ds_part + " some text " + standard_part
+  tool_calls, remainder = _parse_tool_calls_from_text(text)
+  assert len(tool_calls) == 2
+  assert tool_calls[0].function.name == "ds_func"
+  assert tool_calls[1].function.name == "std_func"
+  assert remainder == "some text"
+
+
+def test_parse_deepseek_empty_text():
+  """Empty or whitespace-only text returns no tool calls."""
+  for text in ("", "   ", "\n\n"):
+    tool_calls, remainder = _parse_deepseek_tool_calls_from_text(text)
+    assert tool_calls == []
+    assert remainder is None
+
+
+def test_parse_deepseek_unwrapped_call_before_wrapped_block():
+  """Unwrapped call preceding a wrapped block is not dropped."""
+  unwrapped = _ds_tool_call("first", '{"x": 1}')
+  wrapped = _ds_wrapped(_ds_tool_call("second", '{"y": 2}'))
+  tool_calls, remainder = _parse_deepseek_tool_calls_from_text(
+      unwrapped + wrapped
+  )
+  assert [tc.function.name for tc in tool_calls] == ["first", "second"]
+  assert remainder is None
+
+
+def test_extract_json_from_deepseek_args_invalid_fence_returns_none():
+  """Invalid JSON inside a code fence is rejected rather than returned."""
+  assert _extract_json_from_deepseek_args('```json\n{"a": 1,}\n```') is None
+
+
 def test_split_message_content_and_tool_calls_inline_text():
   message = {
       "role": "assistant",