add support for REASONING_EFFORT environment variable (#809)

Author: aantn

docs/ai-providers/openai.md

@@ -27,13 +27,43 @@ holmes ask "what pods are failing?" --api-key="your-api-key"
 ## Available Models
 
 ```bash
-# GPT-4o (default, recommended)
+# GPT-4o (default)
 holmes ask "what pods are failing?"
 
 # GPT-4o mini (faster, but results are not as accurate)
 holmes ask "what pods are failing?" --model="gpt-4o-mini"
+
+# GPT-5
+holmes ask "what pods are failing?" --model="gpt-5"
 ```
 
+## GPT-5 Reasoning Effort
+
+When using GPT-5 models, you can control the reasoning effort level by setting the `REASONING_EFFORT` environment variable. This allows you to balance between response quality and processing time/cost.
+
+```bash
+# Use minimal reasoning effort for faster responses
+export REASONING_EFFORT="minimal"
+holmes ask "what pods are failing?" --model="gpt-5"
+
+# Use default reasoning effort
+export REASONING_EFFORT="medium"
+holmes ask "what pods are failing?" --model="gpt-5"
+
+# Use high reasoning effort for complex investigations
+export REASONING_EFFORT="high"
+holmes ask "what pods are failing?" --model="gpt-5"
+```
+
+Available reasoning effort levels:
+
+- `minimal` - Fastest responses, suitable for simple queries
+- `low` - Balance between speed and quality
+- `medium` - Standard reasoning depth (default)
+- `high` - Deeper reasoning for complex problems
+
+For more details on reasoning effort levels, refer to the [OpenAI documentation](https://platform.openai.com/docs/).
+
 ## Additional Resources
 
 HolmesGPT uses the LiteLLM API to support OpenAI provider. Refer to [LiteLLM OpenAI docs](https://litellm.vercel.app/docs/providers/openai){:target="_blank"} for more details.

docs/installation/cli-installation.md

@@ -94,7 +94,11 @@ After installation, choose your AI provider and follow the steps below. See supp
 
     3. **Ask your first question**:
         ```bash
+        # Uses gpt-4o by default
         holmes ask "what is wrong with the user-profile-import pod?"
+
+        # Or specify a different model
+        holmes ask "what is wrong with the user-profile-import pod?" --model="gpt-5"
         ```
 
 === "Azure OpenAI"

holmes/common/env_vars.py

@@ -37,6 +37,7 @@ def load_bool(env_var, default: Optional[bool]) -> Optional[bool]:
 SENTRY_TRACES_SAMPLE_RATE = float(os.environ.get("SENTRY_TRACES_SAMPLE_RATE", "0.0"))
 
 THINKING = os.environ.get("THINKING", "")
+REASONING_EFFORT = os.environ.get("REASONING_EFFORT", "").strip().lower()
 TEMPERATURE = float(os.environ.get("TEMPERATURE", "0.00000001"))
 
 STREAM_CHUNKS_PER_PARSE = int(

holmes/core/llm.py

@@ -11,6 +11,7 @@
 import litellm
 import os
 from holmes.common.env_vars import (
+    REASONING_EFFORT,
     THINKING,
 )
 
@@ -207,6 +208,8 @@ def completion(
         stream: Optional[bool] = None,
     ) -> Union[ModelResponse, CustomStreamWrapper]:
         tools_args = {}
+        allowed_openai_params = None
+
         if tools and len(tools) > 0 and tool_choice == "auto":
             tools_args["tools"] = tools
             tools_args["tool_choice"] = tool_choice  # type: ignore
@@ -217,6 +220,12 @@ def completion(
         if self.args.get("thinking", None):
             litellm.modify_params = True
 
+        if REASONING_EFFORT:
+            self.args.setdefault("reasoning_effort", REASONING_EFFORT)
+            allowed_openai_params = [
+                "reasoning_effort"
+            ]  # can be removed after next litelm version
+
         self.args.setdefault("temperature", temperature)
         # Get the litellm module to use (wrapped or unwrapped)
         litellm_to_use = self.tracer.wrap_llm(litellm) if self.tracer else litellm
@@ -227,6 +236,7 @@ def completion(
             messages=messages,
             response_format=response_format,
             drop_params=drop_params,
+            allowed_openai_params=allowed_openai_params,
             stream=stream,
             **tools_args,
             **self.args,

tests/llm/conftest.py

@@ -236,10 +236,10 @@ def check_llm_api_with_test_call():
         )
 
         if azure_base:
-            error_msg = f"Tried to use AzureAI (model: {classifier_model}) because AZURE_API_BASE was set - and failed. Check AZURE_API_BASE, AZURE_API_KEY, AZURE_API_VERSION, or unset them to use OpenAI. Exception: {type(e).__name__}: {str(e)}"
+            error_msg = f"Exception: {type(e).__name__}: {str(e)} - Tried to use AzureAI (model: {classifier_model}) because AZURE_API_BASE was set. Check AZURE_API_BASE, AZURE_API_KEY, AZURE_API_VERSION, or unset them to use OpenAI."
 
         else:
-            error_msg = f"Tried to use OpenAI (model: {classifier_model}) Check OPENAI_API_KEY or set AZURE_API_BASE to use Azure AI. Exception: {type(e).__name__}: {str(e)}"
+            error_msg = f"Exception: {type(e).__name__}: {str(e)} - Tried to use OpenAI (model: {classifier_model}). Check OPENAI_API_KEY or set AZURE_API_BASE to use Azure AI."
 
         return False, error_msg