fix(llm): expand docstring and add reasoning_effort/response_format fallback coverage tests

Author: Hasnaathussain

lib/crewai/src/crewai/llm.py

@@ -2373,16 +2373,21 @@ def _get_custom_llm_provider(self) -> str | None:
         return None
 
     def _validate_call_params(self) -> None:
-        """
-        Validate parameters before making a call. Currently this only checks if
-        a response_format is provided and whether the model supports it.
-        The custom_llm_provider is dynamically determined from the model:
-          - E.g., "openrouter/deepseek/deepseek-chat" yields "openrouter"
-          - "gemini/gemini-1.5-pro" yields "gemini"
-          - If no slash is present, "openai" is assumed.
+        """Validate call parameters before executing a completion request.
+
+        Checks whether the requested ``response_format`` is supported by the
+        target model/provider via LiteLLM introspection.  When introspection
+        raises an exception (e.g. an unmapped custom model ID or proxy
+        endpoint), the failure is logged at DEBUG level and validation is
+        skipped so the request can proceed — this mirrors the permissive
+        fallback used in :meth:`supports_function_calling`.
+
+        When no ``response_format`` is configured (including when only
+        ``reasoning_effort`` or other parameters are set) this method returns
+        immediately without performing any checks.
 
         Note: This validation only applies to the litellm fallback path.
-        Native providers have their own validation.
+        Native providers perform their own parameter validation.
         """
         if self.response_format is None:
             return

lib/crewai/tests/test_llm.py

@@ -1169,6 +1169,7 @@ async def test_non_streaming_async_returns_tool_calls_when_text_also_present():
     response = _build_response_with_text_and_tool_calls()
 
     async def _ret(*args, **kwargs):
+        """Return the pre-built mock response."""
         return response
 
     with patch("crewai.llm.litellm.acompletion", side_effect=_ret):
@@ -1184,6 +1185,35 @@ def test_validate_call_params_handles_introspection_error():
     llm = LLM(model="custom/unsupported-model", is_litellm=True, response_format={"type": "json_object"})
 
     with patch("crewai.llm.supports_response_schema", side_effect=Exception("Introspection error")):
-        # Should not raise exception
+        # Should not raise exception — permissive fallback applies
         llm._validate_call_params()
 
+
+def test_validate_call_params_raises_for_confirmed_unsupported_model():
+    """Verify _validate_call_params still raises ValueError when introspection confirms no support.
+
+    This ensures the validation path is not silently skipped — only introspection
+    *errors* are swallowed; a clear ``False`` return still produces a ValueError.
+    """
+    llm = LLM(model="my-provider/my-model", is_litellm=True, response_format={"type": "json_object"})
+
+    with patch("crewai.llm.supports_response_schema", return_value=False):
+        with pytest.raises(ValueError, match="does not support response_format"):
+            llm._validate_call_params()
+
+
+def test_validate_call_params_skips_check_when_no_response_format():
+    """Verify _validate_call_params is a no-op when response_format is not set.
+
+    This covers scenarios where only ``reasoning_effort`` or other parameters
+    are configured: the method must return immediately so those parameters are
+    forwarded to the provider without interference.
+    """
+    llm = LLM(model="gpt-4o", is_litellm=True, reasoning_effort="medium")
+
+    # If supports_response_schema were called, patching it to raise would surface the bug
+    with patch("crewai.llm.supports_response_schema", side_effect=Exception("Should not be called")):
+        # No exception — response_format is None so introspection is never invoked
+        llm._validate_call_params()
+
+