fix(langchain): handle unrecognized FinishReason enum gracefully

[bcmaymonegalvao]

Description

This PR fixes an unhandled exception that occurs when the Gemini API returns a FinishReason enum value that is not recognized by the current version of the google.generativeai library.

Previously, this caused the ChatGoogleGenerativeAI.with_structured_output() method to raise:

AttributeError: 'int' object has no attribute 'name'

This fix adds a safeguard that gracefully handles unknown enum values by defaulting to a string representation, rather than raising an exception. As a result, structured output parsing remains stable even when the Gemini API introduces new or experimental FinishReason codes.

A dedicated unit test has been added for ChatGoogleGemini to ensure graceful handling of unrecognized FinishReason enum values. The test uses a fully mocked Gemini API response to simulate an unknown finish reason (12) and verifies that the model safely returns "UNKNOWN(12)" without raising an exception.

Rationale

The Gemini API recently started returning a new FinishReason code (12) that is not yet covered in the existing enum definitions. This change prevents downstream crashes by:

• Handling unknown FinishReason codes defensively.
• Maintaining backwards compatibility with all existing models and integrations.
• Allowing users to inspect the raw finish reason safely if needed.

How to Reproduce (Before Fix)

from langchain_google_genai import ChatGoogleGenerativeAI
from pydantic import BaseModel
from typing import Literal

class RouteDecision(BaseModel):
    intent: Literal["action", "conversational"]
    reasoning: str

llm = ChatGoogleGenerativeAI(model="gemini-1.5-flash", temperature=0)
structured = llm.with_structured_output(RouteDecision)
structured.invoke({"user_query": "What is the weather in San Francisco?"})

Result (Before):

AttributeError: 'int' object has no attribute 'name'

Result (After):

RouteDecision(intent='conversational', reasoning='...')  # handled gracefully

Changes

1. Added defensive handling for unknown FinishReason values in google_gemini.py.
2. Added fix-handle-unknown-finish-reason.rst changelog entry.

Tested with

• langchain-core==0.3.79
• langchain-google-genai==2.0.10
• Python 3.13.0 (Windows 11)

Notes

• This patch ensures stability across evolving Gemini API updates.
• No breaking changes were introduced.
• One unrelated test failed in libs/core (test_runnable_lambda_context_config).
  This is a known intermittent issue with the FakeTracer callback when run under pytest-xdist (see cli: fix typo in doc-string #31284 and fix: azure OpenAIrResponses API fallback for unsupported endpoints #32077), and is not related to this change. All community and partner tests pass successfully.

Fixes:

Unrecognized FinishReason enum value: 12 from Gemini API causes crash in ChatGoogleGenerativeAI #33444

[ccurme]

ChatGoogleGenerativeAI is maintained in https://github.com/langchain-ai/langchain-google.