fix(genai): update json_mode to json_schema for structured output methods (#1188)

Author: mdrxy

libs/genai/langchain_google_genai/chat_models.py

@@ -1219,8 +1219,8 @@ class Joke(BaseModel):
             # Default method uses function calling
             structured_llm = llm.with_structured_output(Joke)
 
-            # For more reliable output, use json_mode with native responseSchema
-            structured_llm_json = llm.with_structured_output(Joke, method="json_mode")
+            # For more reliable output, use json_schema with native responseSchema
+            structured_llm_json = llm.with_structured_output(Joke, method="json_schema")
             structured_llm_json.invoke("Tell me a joke about cats")
 
         .. code-block:: python
@@ -1235,12 +1235,13 @@ class Joke(BaseModel):
 
         * ``method="function_calling"`` (default): Uses tool calling to extract
         structured data. Compatible with all models.
-        * ``method="json_mode"``: Uses Gemini's native structured output with
+        * ``method="json_schema"``: Uses Gemini's native structured output with
         responseSchema. More reliable but requires Gemini 1.5+ models.
+        ``method="json_mode"`` also works for backwards compatibility but is a misnomer.
 
-        The ``json_mode`` method is recommended for better reliability as it constrains
-        the model's generation process directly rather than relying on post-processing
-        tool calls.
+        The ``json_schema`` method is recommended for better reliability as it
+        constrains the model's generation process directly rather than relying on
+        post-processing tool calls.
 
     Image input:
         .. code-block:: python
@@ -2103,7 +2104,9 @@ def get_num_tokens(self, text: str) -> int:
     def with_structured_output(
         self,
         schema: Union[Dict, Type[BaseModel]],
-        method: Optional[Literal["function_calling", "json_mode"]] = "function_calling",
+        method: Optional[
+            Literal["function_calling", "json_mode", "json_schema"]
+        ] = "function_calling",
         *,
         include_raw: bool = False,
         **kwargs: Any,
@@ -2115,7 +2118,7 @@ def with_structured_output(
 
         parser: OutputParserLike
 
-        if method == "json_mode":
+        if method in ("json_mode", "json_schema"):  # `json_schema` preferred
             if isinstance(schema, type) and is_basemodel_subclass(schema):
                 if issubclass(schema, BaseModelV1):
                     schema_json = schema.schema()

libs/genai/tests/integration_tests/test_chat_models.py

@@ -724,11 +724,12 @@ def my_tool(name: str, age: int, likes: list[str]) -> None:
         (_MODEL, None),
         (_MODEL, "function_calling"),
         (_MODEL, "json_mode"),
+        (_MODEL, "json_schema"),
     ],
 )
 def test_chat_google_genai_with_structured_output(
     model_name: str,
-    method: Optional[Literal["function_calling", "json_mode"]],
+    method: Optional[Literal["function_calling", "json_mode", "json_schema"]],
 ) -> None:
     class MyModel(BaseModel):
         name: str
@@ -756,7 +757,8 @@ class MyModel(BaseModel):
     expected = {"name": "Erick", "age": 27}
     assert response == expected
 
-    if method is None:  # This won't work with json_schema as it expects an OpenAPI dict
+    # This won't work with json_schema/json_mode as it expects an OpenAPI dict
+    if method is None:
         model = llm.with_structured_output(
             {
                 "name": "MyModel",

libs/genai/tests/unit_tests/test_chat_models.py

@@ -1114,3 +1114,21 @@ async def test_max_retries_parameter_handling(
             assert call_kwargs_actual["max_retries"] == expected_max_retries
         else:
             assert "max_retries" not in call_kwargs_actual
+
+
+def test_with_structured_output_json_schema_alias() -> None:
+    """Test that json_schema method works as alias for json_mode."""
+    from pydantic import BaseModel
+
+    class TestModel(BaseModel):
+        name: str
+        age: int
+
+    llm = ChatGoogleGenerativeAI(model="gemini-pro", google_api_key="fake-key")
+
+    structured_llm = llm.with_structured_output(TestModel, method="json_schema")
+    assert structured_llm is not None
+
+    schema_dict = {"type": "object", "properties": {"name": {"type": "string"}}}
+    structured_llm_dict = llm.with_structured_output(schema_dict, method="json_schema")
+    assert structured_llm_dict is not None