feat: map LiteLLM finish_reason strings to FinishReason enum

Maps LiteLLM finish_reason string values to proper FinishReason enum
for type consistency with Gemini native responses.

Changes:
- Add _FINISH_REASON_MAPPING dictionary for string->enum conversion
  - "length" -> FinishReason.MAX_TOKENS
  - "stop" -> FinishReason.STOP
  - "tool_calls"/"function_call" -> FinishReason.STOP
  - "content_filter" -> FinishReason.SAFETY
  - Unknown values -> FinishReason.OTHER (fallback)

- Update finish_reason type hint to Optional[FinishReason] (no Union needed)

- Update telemetry tracing to use .name for enum serialization

- Add explanatory comments:
  - Why tool_calls maps to STOP (no TOOL_CALL enum exists)
  - Docstring clarifies mapping applies to all model providers

Tests:
- test_finish_reason_propagation: verifies enum mapping for all values
- test_finish_reason_unknown_maps_to_other: verifies fallback behavior

Benefits:
- Type consistency: finish_reason is always FinishReason enum
- No runtime warnings from mixed types
- Enables proper isinstance() checks in callbacks
- Dictionary mapping improves maintainability
- Better integration with ADK telemetry

Author: aperepel

src/google/adk/models/lite_llm.py

@@ -64,6 +64,19 @@
 _NEW_LINE = "\n"
 _EXCLUDED_PART_FIELD = {"inline_data": {"data"}}
 
+# Mapping of LiteLLM finish_reason strings to FinishReason enum values
+# Note: tool_calls/function_call map to STOP because:
+# 1. FinishReason.TOOL_CALL enum does not exist (as of google-genai 0.8.0)
+# 2. Tool calls represent normal completion (model stopped to invoke tools)
+# 3. Gemini native responses use STOP for tool calls (see lite_llm.py:910)
+_FINISH_REASON_MAPPING = {
+    "length": types.FinishReason.MAX_TOKENS,
+    "stop": types.FinishReason.STOP,
+    "tool_calls": types.FinishReason.STOP,  # Normal completion with tool invocation
+    "function_call": types.FinishReason.STOP,  # Legacy function call variant
+    "content_filter": types.FinishReason.SAFETY,
+}
+
 
 class ChatCompletionFileUrlObject(TypedDict, total=False):
   file_data: str
@@ -508,18 +521,9 @@ def _model_response_to_generate_content_response(
     # Map LiteLLM finish_reason strings to FinishReason enum
     # This provides type consistency with Gemini native responses and avoids warnings
     finish_reason_str = str(finish_reason).lower()
-    if finish_reason_str == "length":
-      llm_response.finish_reason = types.FinishReason.MAX_TOKENS
-    elif finish_reason_str == "stop":
-      llm_response.finish_reason = types.FinishReason.STOP
-    elif "tool" in finish_reason_str or "function" in finish_reason_str:
-      # Handle tool_calls, function_call variants
-      llm_response.finish_reason = types.FinishReason.STOP
-    elif finish_reason_str == "content_filter":
-      llm_response.finish_reason = types.FinishReason.SAFETY
-    else:
-      # For unknown reasons, use OTHER
-      llm_response.finish_reason = types.FinishReason.OTHER
+    llm_response.finish_reason = _FINISH_REASON_MAPPING.get(
+        finish_reason_str, types.FinishReason.OTHER
+    )
   if response.get("usage", None):
     llm_response.usage_metadata = types.GenerateContentResponseUsageMetadata(
         prompt_token_count=response["usage"].get("prompt_tokens", 0),

src/google/adk/models/llm_response.py

@@ -78,10 +78,11 @@ class LlmResponse(BaseModel):
   Only used for streaming mode.
   """
 
-  finish_reason: Optional[Union[types.FinishReason, str]] = None
+  finish_reason: Optional[types.FinishReason] = None
   """The finish reason of the response.
 
-  Can be either a types.FinishReason enum (from Gemini) or a string (from LiteLLM).
+  Always a types.FinishReason enum. String values from underlying model providers
+  are mapped to corresponding enum values (with fallback to OTHER for unknown values).
   """
 
   error_code: Optional[str] = None

src/google/adk/telemetry/tracing.py

@@ -306,7 +306,7 @@ def trace_call_llm(
     if isinstance(llm_response.finish_reason, types.FinishReason):
       finish_reason_str = llm_response.finish_reason.name.lower()
     else:
-      # Fallback for string values (should not occur with LiteLLM after enum mapping)
+      # Defensive fallback for string values (should never occur - all values mapped to enum)
       finish_reason_str = str(llm_response.finish_reason).lower()
     span.set_attribute(
         'gen_ai.response.finish_reasons',