feat(openai): minimal and verbosity (#32455)

Author: mdrxy

libs/langchain/tests/unit_tests/chat_models/test_base.py

@@ -68,6 +68,32 @@ def test_init_unknown_provider() -> None:
     clear=True,
 )
 def test_configurable() -> None:
+    """Test configurable chat model behavior without default parameters.
+
+    Verifies that a configurable chat model initialized without default parameters:
+    - Has access to all standard runnable methods (``invoke``, ``stream``, etc.)
+    - Blocks access to non-configurable methods until configuration is provided
+    - Supports declarative operations (``bind_tools``) without mutating original model
+    - Can chain declarative operations and configuration to access full functionality
+    - Properly resolves to the configured model type when parameters are provided
+
+    Example:
+
+    .. python::
+
+        # This creates a configurable model without specifying which model
+        model = init_chat_model()
+
+        # This will FAIL - no model specified yet
+        model.get_num_tokens("hello")  # AttributeError!
+
+        # This works - provides model at runtime
+        response = model.invoke(
+            "Hello",
+            config={"configurable": {"model": "gpt-4o"}}
+        )
+
+    """
     model = init_chat_model()
 
     for method in (
@@ -125,6 +151,7 @@ def test_configurable() -> None:
             "presence_penalty": None,
             "reasoning": None,
             "reasoning_effort": None,
+            "verbosity": None,
             "frequency_penalty": None,
             "include": None,
             "seed": None,
@@ -170,6 +197,32 @@ def test_configurable() -> None:
     clear=True,
 )
 def test_configurable_with_default() -> None:
+    """Test configurable chat model behavior with default parameters.
+
+    Verifies that a configurable chat model initialized with default parameters:
+    - Has access to all standard runnable methods (``invoke``, ``stream``, etc.)
+    - Provides immediate access to non-configurable methods (e.g. ``get_num_tokens``)
+    - Supports model switching through runtime configuration using ``config_prefix``
+    - Maintains proper model identity and attributes when reconfigured
+    - Can be used in chains with different model providers via configuration
+
+    Example:
+
+    .. python::
+
+        # This creates a configurable model with default parameters (model)
+        model = init_chat_model("gpt-4o", configurable_fields="any", config_prefix="bar")
+
+        # This works immediately - uses default gpt-4o
+        tokens = model.get_num_tokens("hello")
+
+        # This also works - switches to Claude at runtime
+        response = model.invoke(
+            "Hello",
+            config={"configurable": {"my_model_model": "claude-3-sonnet-20240229"}}
+        )
+
+    """  # noqa: E501
     model = init_chat_model("gpt-4o", configurable_fields="any", config_prefix="bar")
     for method in (
         "invoke",

libs/langchain_v1/tests/unit_tests/chat_models/test_chat_models.py

@@ -68,6 +68,32 @@ def test_init_unknown_provider() -> None:
     clear=True,
 )
 def test_configurable() -> None:
+    """Test configurable chat model behavior without default parameters.
+
+    Verifies that a configurable chat model initialized without default parameters:
+    - Has access to all standard runnable methods (``invoke``, ``stream``, etc.)
+    - Blocks access to non-configurable methods until configuration is provided
+    - Supports declarative operations (``bind_tools``) without mutating original model
+    - Can chain declarative operations and configuration to access full functionality
+    - Properly resolves to the configured model type when parameters are provided
+
+    Example:
+
+    .. python::
+
+        # This creates a configurable model without specifying which model
+        model = init_chat_model()
+
+        # This will FAIL - no model specified yet
+        model.get_num_tokens("hello")  # AttributeError!
+
+        # This works - provides model at runtime
+        response = model.invoke(
+            "Hello",
+            config={"configurable": {"model": "gpt-4o"}}
+        )
+
+    """
     model = init_chat_model()
 
     for method in (
@@ -125,6 +151,7 @@ def test_configurable() -> None:
             "presence_penalty": None,
             "reasoning": None,
             "reasoning_effort": None,
+            "verbosity": None,
             "frequency_penalty": None,
             "include": None,
             "seed": None,
@@ -170,6 +197,32 @@ def test_configurable() -> None:
     clear=True,
 )
 def test_configurable_with_default() -> None:
+    """Test configurable chat model behavior with default parameters.
+
+    Verifies that a configurable chat model initialized with default parameters:
+    - Has access to all standard runnable methods (``invoke``, ``stream``, etc.)
+    - Provides immediate access to non-configurable methods (e.g. ``get_num_tokens``)
+    - Supports model switching through runtime configuration using ``config_prefix``
+    - Maintains proper model identity and attributes when reconfigured
+    - Can be used in chains with different model providers via configuration
+
+    Example:
+
+    .. python::
+
+        # This creates a configurable model with default parameters (model)
+        model = init_chat_model("gpt-4o", configurable_fields="any", config_prefix="bar")
+
+        # This works immediately - uses default gpt-4o
+        tokens = model.get_num_tokens("hello")
+
+        # This also works - switches to Claude at runtime
+        response = model.invoke(
+            "Hello",
+            config={"configurable": {"my_model_model": "claude-3-sonnet-20240229"}}
+        )
+
+    """  # noqa: E501
     model = init_chat_model("gpt-4o", configurable_fields="any", config_prefix="bar")
     for method in (
         "invoke",

libs/partners/openai/langchain_openai/chat_models/base.py

@@ -458,8 +458,7 @@ class BaseChatOpenAI(BaseChatModel):
         alias="api_key", default_factory=secret_from_env("OPENAI_API_KEY", default=None)
     )
     openai_api_base: Optional[str] = Field(default=None, alias="base_url")
-    """Base URL path for API requests, leave blank if not using a proxy or service
-        emulator."""
+    """Base URL path for API requests, leave blank if not using a proxy or service emulator."""  # noqa: E501
     openai_organization: Optional[str] = Field(default=None, alias="organization")
     """Automatically inferred from env var ``OPENAI_ORG_ID`` if not provided."""
     # to support explicit proxy for OpenAI
@@ -507,8 +506,9 @@ class BaseChatOpenAI(BaseChatModel):
 
     Reasoning models only, like OpenAI o1, o3, and o4-mini.
 
-    Currently supported values are low, medium, and high. Reducing reasoning effort
-    can result in faster responses and fewer tokens used on reasoning in a response.
+    Currently supported values are ``'minimal'``, ``'low'``, ``'medium'``, and
+    ``'high'``. Reducing reasoning effort can result in faster responses and fewer
+    tokens used on reasoning in a response.
 
     .. versionadded:: 0.2.14
     """
@@ -527,6 +527,17 @@ class BaseChatOpenAI(BaseChatModel):
 
     .. versionadded:: 0.3.24
 
+    """
+    verbosity: Optional[str] = None
+    """Controls the verbosity level of responses for reasoning models. For use with the
+    Responses API.
+
+    Currently supported values are ``'low'``, ``'medium'``, and ``'high'``.
+
+    Controls how detailed the model's responses are.
+
+    .. versionadded:: 0.3.28
+
     """
     tiktoken_model_name: Optional[str] = None
     """The model name to pass to tiktoken when using this class.
@@ -654,6 +665,7 @@ class BaseChatOpenAI(BaseChatModel):
         llm = ChatOpenAI(
             model="o4-mini",
             use_responses_api=True,
+            output_version="responses/v1",
         )
         llm.invoke([HumanMessage("How are you?")], previous_response_id="resp_123")
 
@@ -701,10 +713,24 @@ def build_extra(cls, values: dict[str, Any]) -> Any:
     @model_validator(mode="before")
     @classmethod
     def validate_temperature(cls, values: dict[str, Any]) -> Any:
-        """Currently o1 models only allow temperature=1."""
+        """Validate temperature parameter for different models.
+
+        - o1 models only allow temperature=1
+        - gpt-5 models only allow temperature=1 or unset (defaults to 1)
+        """
         model = values.get("model_name") or values.get("model") or ""
+
+        # For o1 models, set temperature=1 if not provided
         if model.startswith("o1") and "temperature" not in values:
             values["temperature"] = 1
+
+        # For gpt-5 models, handle temperature restrictions
+        if model.startswith("gpt-5"):
+            temperature = values.get("temperature")
+            if temperature is not None and temperature != 1:
+                # For gpt-5, only temperature=1 is supported, so remove non-defaults
+                values.pop("temperature", None)
+
         return values
 
     @model_validator(mode="after")
@@ -805,6 +831,7 @@ def _default_params(self) -> dict[str, Any]:
             "temperature": self.temperature,
             "reasoning_effort": self.reasoning_effort,
             "reasoning": self.reasoning,
+            "verbosity": self.verbosity,
             "include": self.include,
             "service_tier": self.service_tier,
             "truncation": self.truncation,
@@ -1178,6 +1205,7 @@ def _get_request_payload(
             kwargs["stop"] = stop
 
         payload = {**self._default_params, **kwargs}
+
         if self._use_responses_api(payload):
             if self.use_previous_response_id:
                 last_messages, previous_response_id = _get_last_messages(messages)
@@ -2366,7 +2394,11 @@ class GetPopulation(BaseModel):
 
             from langchain_openai import ChatOpenAI
 
-            llm = ChatOpenAI(model="gpt-4.1-mini", use_responses_api=True)
+            llm = ChatOpenAI(
+                model="gpt-4.1-mini",
+                use_responses_api=True,
+                output_version="responses/v1",
+            )
             response = llm.invoke("Hi, I'm Bob.")
             response.text()
 
@@ -3486,6 +3518,11 @@ def _construct_responses_api_payload(
     if "reasoning_effort" in payload and "reasoning" not in payload:
         payload["reasoning"] = {"effort": payload.pop("reasoning_effort")}
 
+    # Remove temperature parameter for models that don't support it in responses API
+    model = payload.get("model", "")
+    if model.startswith("gpt-5"):
+        payload.pop("temperature", None)
+
     payload["input"] = _construct_responses_api_input(messages)
     if tools := payload.pop("tools", None):
         new_tools: list = []