holmesgpt 0.13.2__py3-none-any.whl → 0.18.4__py3-none-any.whl

holmes/plugins/toolsets/robusta/robusta.py

@@ -1,23 +1,29 @@
-import os
-
 import logging
+import os
+from typing import Any, Dict, List, Optional
 
-from typing import Optional, Dict, Any, List
-from holmes.core.supabase_dal import SupabaseDal
+from holmes.common.env_vars import load_bool
+from holmes.core.supabase_dal import FindingType, SupabaseDal
 from holmes.core.tools import (
     StaticPrerequisite,
+    StructuredToolResult,
+    StructuredToolResultStatus,
     Tool,
+    ToolInvokeContext,
     ToolParameter,
     Toolset,
     ToolsetTag,
 )
-from holmes.core.tools import StructuredToolResult, ToolResultStatus
+
+PULL_EXTERNAL_FINDINGS = load_bool("PULL_EXTERNAL_FINDINGS", False)
 
 PARAM_FINDING_ID = "id"
 START_TIME = "start_datetime"
 END_TIME = "end_datetime"
 NAMESPACE = "namespace"
 WORKLOAD = "workload"
+DEFAULT_LIMIT_CHANGE_ROWS = 100
+MAX_LIMIT_CHANGE_ROWS = 200
 
 
 class FetchRobustaFinding(Tool):
@@ -26,7 +32,7 @@ class FetchRobustaFinding(Tool):
     def __init__(self, dal: Optional[SupabaseDal]):
         super().__init__(
             name="fetch_finding_by_id",
-            description="Fetches a robusta finding. Findings are events, like a Prometheus alert or a deployment update",
+            description="Fetches a robusta finding. Findings are events, like a Prometheus alert or a deployment update and configuration change.",
             parameters={
                 PARAM_FINDING_ID: ToolParameter(
                     description="The id of the finding to fetch",
@@ -45,21 +51,19 @@ class FetchRobustaFinding(Tool):
             logging.error(error)
             return {"error": error}
 
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
         finding_id = params[PARAM_FINDING_ID]
         try:
             finding = self._fetch_finding(finding_id)
             if finding:
                 return StructuredToolResult(
-                    status=ToolResultStatus.SUCCESS,
+                    status=StructuredToolResultStatus.SUCCESS,
                     data=finding,
                     params=params,
                 )
             else:
                 return StructuredToolResult(
-                    status=ToolResultStatus.NO_DATA,
+                    status=StructuredToolResultStatus.NO_DATA,
                     data=f"Could not find a finding with finding_id={finding_id}",
                     params=params,
                 )
@@ -70,13 +74,13 @@ class FetchRobustaFinding(Tool):
             )
 
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 data=f"There was an internal error while fetching finding {finding_id}",
                 params=params,
             )
 
     def get_parameterized_one_liner(self, params: Dict) -> str:
-        return "Robusta: Fetch Alert Metadata"
+        return f"Robusta: Fetch finding data {params}"
 
 
 class FetchResourceRecommendation(Tool):
@@ -85,124 +89,285 @@ class FetchResourceRecommendation(Tool):
     def __init__(self, dal: Optional[SupabaseDal]):
         super().__init__(
             name="fetch_resource_recommendation",
-            description="Fetch workload recommendations for resources requests and limits. Returns the current configured resources, as well as recommendation based on actual historical usage.",
+            description=(
+                "Fetch KRR (Kubernetes Resource Recommendations) for CPU and memory optimization. "
+                "KRR provides AI-powered recommendations based on actual historical usage patterns for right-sizing workloads. "
+                "Supports two usage modes: "
+                "(1) Specific workload lookup - Use name_pattern with an exact name, namespace, and kind to get recommendations for a single workload. "
+                "(2) Discovery mode - Use limit and sort_by to get a ranked list of top optimization opportunities. Optionally filter by namespace, name_pattern (wildcards supported), kind, or container. "
+                "Returns current configured resources alongside recommended values. In discovery mode, results are sorted by potential savings."
+            ),
             parameters={
-                "name": ToolParameter(
-                    description="The name of the kubernetes workload.",
+                "limit": ToolParameter(
+                    description="Maximum number of recommendations to return (default: 10, max: 100).",
+                    type="integer",
+                    required=False,
+                ),
+                "sort_by": ToolParameter(
+                    description=(
+                        "Field to sort recommendations by potential savings. Options: "
+                        "'cpu_total' (default) - Total CPU savings (requests + limits), "
+                        "'memory_total' - Total memory savings (requests + limits), "
+                        "'cpu_requests' - CPU requests savings, "
+                        "'memory_requests' - Memory requests savings, "
+                        "'cpu_limits' - CPU limits savings, "
+                        "'memory_limits' - Memory limits savings, "
+                        "'priority' - Use scan priority field."
+                    ),
                     type="string",
-                    required=True,
+                    required=False,
                 ),
                 "namespace": ToolParameter(
-                    description="The namespace of the kubernetes resource.",
+                    description="Filter by Kubernetes namespace (exact match). Leave empty to search all namespaces.",
                     type="string",
-                    required=True,
+                    required=False,
+                ),
+                "name_pattern": ToolParameter(
+                    description=(
+                        "Filter by workload name pattern. Supports SQL LIKE patterns: "
+                        "Use '%' as wildcard (e.g., '%app%' matches any name containing 'app', "
+                        "'prod-%' matches names starting with 'prod-'). "
+                        "Leave empty to match all names."
+                    ),
+                    type="string",
+                    required=False,
                 ),
                 "kind": ToolParameter(
-                    description="The kind of the kubernetes resource. Must be one of: [Deployment, StatefulSet, DaemonSet, Job].",
+                    description=(
+                        "Filter by Kubernetes resource kind. "
+                        "Must be one of: Deployment, StatefulSet, DaemonSet, Job. "
+                        "Leave empty to include all kinds."
+                    ),
                     type="string",
-                    required=True,
+                    required=False,
+                ),
+                "container": ToolParameter(
+                    description="Filter by container name (exact match). Leave empty to include all containers.",
+                    type="string",
+                    required=False,
                 ),
             },
         )
         self._dal = dal
 
-    def _resource_recommendation(self, params: Dict) -> Optional[List[Dict]]:
+    def _fetch_recommendations(self, params: Dict) -> Optional[List[Dict]]:
         if self._dal and self._dal.enabled:
+            # Set default values
+            limit = min(params.get("limit", 10) or 10, 100)
+            sort_by = params.get("sort_by") or "cpu_total"
+
             return self._dal.get_resource_recommendation(
-                name=params["name"],
-                namespace=params["namespace"],
-                kind=params["kind"],
+                limit=limit,
+                sort_by=sort_by,
+                namespace=params.get("namespace"),
+                name_pattern=params.get("name_pattern"),
+                kind=params.get("kind"),
+                container=params.get("container"),
             )
         return None
 
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
         try:
-            recommendations = self._resource_recommendation(params)
+            recommendations = self._fetch_recommendations(params)
             if recommendations:
                 return StructuredToolResult(
-                    status=ToolResultStatus.SUCCESS,
+                    status=StructuredToolResultStatus.SUCCESS,
                     data=recommendations,
                     params=params,
                 )
             else:
                 return StructuredToolResult(
-                    status=ToolResultStatus.NO_DATA,
-                    data=f"Could not find recommendations for {params}",
+                    status=StructuredToolResultStatus.NO_DATA,
+                    data=f"Could not find any recommendations with filters: {params}",
                     params=params,
                 )
         except Exception as e:
-            msg = f"There was an internal error while fetching recommendations for {params}. {str(e)}"
+            msg = f"There was an error while fetching top recommendations for {params}. {str(e)}"
             logging.exception(msg)
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
-                data=msg,
+                status=StructuredToolResultStatus.ERROR,
+                error=msg,
                 params=params,
             )
 
     def get_parameterized_one_liner(self, params: Dict) -> str:
-        return f"Robusta: Check Historical Resource Utilization: ({str(params)})"
+        return f"Robusta: Fetch KRR Recommendations ({str(params)})"
 
 
-class FetchConfigurationChanges(Tool):
+class FetchConfigurationChangesMetadataBase(Tool):
     _dal: Optional[SupabaseDal]
 
-    def __init__(self, dal: Optional[SupabaseDal]):
+    def __init__(
+        self,
+        dal: Optional[SupabaseDal],
+        name: str,
+        description: str,
+        add_cluster_filter: bool = True,
+    ):
+        """
+        We need seperate tools for external and cluster configuration changes due to the different cluster parameters that are not on "external" changes like 'workload' and 'namespace'.
+        add_cluster_filter: adds the namespace and workload parameters for configuration changes tool.
+        """
+        parameters = {
+            START_TIME: ToolParameter(
+                description="The starting time boundary for the search period. String in RFC3339 format.",
+                type="string",
+                required=True,
+            ),
+            END_TIME: ToolParameter(
+                description="The ending time boundary for the search period. String in RFC3339 format.",
+                type="string",
+                required=True,
+            ),
+            "limit": ToolParameter(
+                description=f"Maximum number of rows to return. Default is {DEFAULT_LIMIT_CHANGE_ROWS} and the maximum is 200",
+                type="integer",
+                required=False,
+            ),
+        }
+
+        if add_cluster_filter:
+            parameters.update(
+                {
+                    "namespace": ToolParameter(
+                        description="The Kubernetes namespace name for filtering configuration changes",
+                        type="string",
+                        required=False,
+                    ),
+                    "workload": ToolParameter(
+                        description="Kubernetes resource name to filter configuration changes (e.g., Pod, Deployment, Job, etc.). Must be the full name. For Pods, include the exact generated suffix.",
+                        type="string",
+                        required=False,
+                    ),
+                }
+            )
+
         super().__init__(
-            name="fetch_configuration_changes",
-            description="Fetch configuration changes in a given time range. By default, fetch all cluster changes. Can be filtered on a given namespace or a specific workload",
-            parameters={
-                START_TIME: ToolParameter(
-                    description="The starting time boundary for the search period. String in RFC3339 format.",
-                    type="string",
-                    required=True,
-                ),
-                END_TIME: ToolParameter(
-                    description="The starting time boundary for the search period. String in RFC3339 format.",
-                    type="string",
-                    required=True,
-                ),
-            },
+            name=name,
+            description=description,
+            parameters=parameters,
         )
         self._dal = dal
 
-    def _fetch_change_history(self, params: Dict) -> Optional[List[Dict]]:
+    def _fetch_issues(
+        self,
+        params: Dict,
+        cluster: Optional[str] = None,
+        finding_type: FindingType = FindingType.CONFIGURATION_CHANGE,
+    ) -> Optional[List[Dict]]:
         if self._dal and self._dal.enabled:
-            return self._dal.get_configuration_changes(
+            return self._dal.get_issues_metadata(
                 start_datetime=params["start_datetime"],
                 end_datetime=params["end_datetime"],
+                limit=min(
+                    params.get("limit") or DEFAULT_LIMIT_CHANGE_ROWS,
+                    MAX_LIMIT_CHANGE_ROWS,
+                ),
+                ns=params.get("namespace"),
+                workload=params.get("workload"),
+                cluster=cluster,
+                finding_type=finding_type,
             )
         return None
 
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
         try:
-            changes = self._fetch_change_history(params)
+            changes = self._fetch_issues(params)
             if changes:
                 return StructuredToolResult(
-                    status=ToolResultStatus.SUCCESS,
+                    status=StructuredToolResultStatus.SUCCESS,
                     data=changes,
                     params=params,
                 )
             else:
                 return StructuredToolResult(
-                    status=ToolResultStatus.NO_DATA,
-                    data=f"Could not find changes for {params}",
+                    status=StructuredToolResultStatus.NO_DATA,
+                    data=f"{self.name} found no data. {params}",
                     params=params,
                 )
         except Exception as e:
             msg = f"There was an internal error while fetching changes for {params}. {str(e)}"
             logging.exception(msg)
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 data=msg,
                 params=params,
             )
 
     def get_parameterized_one_liner(self, params: Dict) -> str:
-        return "Robusta: Search Change History"
+        return f"Robusta: Search Change History {params}"
+
+
+class FetchConfigurationChangesMetadata(FetchConfigurationChangesMetadataBase):
+    def __init__(self, dal: Optional[SupabaseDal]):
+        super().__init__(
+            dal=dal,
+            name="fetch_configuration_changes_metadata",
+            description=(
+                "Fetch configuration changes metadata in a given time range. "
+                "By default, fetch all cluster changes. Can be filtered on a given namespace or a specific kubernetes resource. "
+                "Use fetch_finding_by_id to get detailed change of one specific configuration change."
+            ),
+        )
+
+
+class FetchExternalConfigurationChangesMetadata(FetchConfigurationChangesMetadataBase):
+    """
+    Fetch configuration changes from external sources, e.g., LaunchDarkly changes.
+    It needs to be a seperate tool due to the different cluster parameter used in the DAL method like workload and namespace.
+    """
+
+    def __init__(self, dal: Optional[SupabaseDal]):
+        super().__init__(
+            dal=dal,
+            name="fetch_external_configuration_changes_metadata",
+            description=(
+                "Fetch external configuration changes metadata in a given time range. "
+                "Fetches configuration changes from external sources. "
+                "Use fetch_finding_by_id to get detailed change of one specific configuration change."
+            ),
+            add_cluster_filter=False,
+        )
+
+    def _fetch_issues(self, params: Dict) -> Optional[List[Dict]]:  # type: ignore
+        return super()._fetch_issues(params, cluster="external")
+
+    def get_parameterized_one_liner(self, params: Dict) -> str:
+        return f"Robusta: Search External Change History {params}"
+
+
+class FetchResourceIssuesMetadata(FetchConfigurationChangesMetadataBase):
+    def __init__(self, dal: Optional[SupabaseDal]):
+        super().__init__(
+            dal=dal,
+            name="fetch_resource_issues_metadata",
+            description=(
+                "Fetch issues and alert metadata in a given time range. "
+                "Must be filtered on a given namespace and specific kubernetes resource, such as pod, deployment, job, etc. "
+                "Use fetch_finding_by_id to get further information on a specific issue or alert."
+            ),
+            add_cluster_filter=False,
+        )
+        self.parameters.update(
+            {
+                "namespace": ToolParameter(
+                    description="The Kubernetes namespace name for filtering issues and alerts",
+                    type="string",
+                    required=True,
+                ),
+                "workload": ToolParameter(
+                    description="Kubernetes resource name to filter issues and alerts (e.g., Pod, Deployment, Job, etc.). Must be the full name. For Pods, include the exact generated suffix.",
+                    type="string",
+                    required=True,
+                ),
+            }
+        )
+
+    def _fetch_issues(self, params: Dict) -> Optional[List[Dict]]:  # type: ignore
+        return super()._fetch_issues(params, finding_type=FindingType.ISSUE)
+
+    def get_parameterized_one_liner(self, params: Dict) -> str:
+        return f"Robusta: fetch resource issues metadata {params}"
 
 
 class RobustaToolset(Toolset):
@@ -216,17 +381,23 @@ class RobustaToolset(Toolset):
                 enabled=dal.enabled, disabled_reason="Data access layer is disabled"
             )
 
+        tools = [
+            FetchRobustaFinding(dal),
+            FetchConfigurationChangesMetadata(dal),
+            FetchResourceRecommendation(dal),
+            FetchResourceIssuesMetadata(dal),
+        ]
+
+        if PULL_EXTERNAL_FINDINGS:
+            tools.append(FetchExternalConfigurationChangesMetadata(dal))
+
         super().__init__(
             icon_url="https://cdn.prod.website-files.com/633e9bac8f71dfb7a8e4c9a6/646be7710db810b14133bdb5_logo.svg",
             description="Fetches alerts metadata and change history",
             docs_url="https://holmesgpt.dev/data-sources/builtin-toolsets/robusta/",
             name="robusta",
             prerequisites=[dal_prereq],
-            tools=[
-                FetchRobustaFinding(dal),
-                FetchConfigurationChanges(dal),
-                FetchResourceRecommendation(dal),
-            ],
+            tools=tools,
             tags=[
                 ToolsetTag.CORE,
             ],

holmes/plugins/toolsets/robusta/robusta_instructions.jinja2

@@ -1,7 +1,10 @@
 # Configuration and alerts history
-* Use fetch_configuration_changes to get historical configuration changes
-* You must ALWAYS call fetch_configuration_changes when investigating an alert
-* Never respond without calling fetch_configuration_changes
+* Use fetch_configuration_changes_metadata to get historical configuration changes in a cluster or for a specific workload.
+* If a change seems important to the investigation, Use fetch_finding_by_id with the configuration change ID to get full details of the change.
+* You must ALWAYS call fetch_configuration_changes_metadata when investigating an alert
+* Never respond without calling fetch_configuration_changes_metadata
+* When investigating a resource (pod, deployment, or job), if no relevant information is available from the live cluster at the time of investigation, call the fetch_resource_issues_metadata function to retrieve its historical alert data.
+* You can use fetch_resource_issues_metadata to get issues context for a specific kubernetes resource. Start with a 4 hours window and try to expand to 24 hours windows if nothing comes up.
 * When investigating an alert, look at historical configuration changes that happen 4 hours before the alert started
 * If you found a change that caused the alert, you MUST write: 'The issue was introduced by ...' with a short description of the change, and the date of it.
 For example:
@@ -11,12 +14,26 @@ For example:
 * Embed it in with the evidence id and a title describing the change. Use this format:
 << { "type": "diff", "evidence_id": "8a4d1369-0e98-4ff2-b180-699d5ff286ab", "title": "Image change on the DB workload" } >>
 
-# Resource and efficiency recommendations
-* Use fetch_resource_recommendation to get resource recommendations for a given kubernetes workload
-* Resource recommendations contains memory and cpu recommended request and limits for a given workload
-* When asked if a resource can be optimized, or if a resources is over utilized, use the fetch_resource_recommendation tool to answer
-* Right sizing of resources is a key to avoiding performance issues
-* Right sizing of resouces can also lead to cost savings
+# Resource and efficiency recommendations (KRR)
+* KRR (Kubernetes Resource Recommendations) provides AI-powered recommendations for right-sizing CPU and memory requests/limits
+* Use fetch_resource_recommendation for all KRR queries - it supports two modes:
+  - **Discovery mode**: Get a ranked list of top optimization opportunities across multiple workloads
+    - Use limit and sort_by parameters to control ranking (CPU savings, memory savings, or priority)
+    - Supports filtering by namespace, name_pattern (with wildcards like '%app%'), kind, and container
+    - Returns up to 100 recommendations sorted by potential impact
+    - Use this for questions like "top recommendations", "cost savings opportunities", "what to optimize"
+  - **Specific lookup mode**: Get recommendations for a single known workload
+    - Use name_pattern with exact workload name, along with namespace and kind
+    - Best for focused analysis when you already know which workload to investigate
+* When asked if a resource can be optimized, or if resources are over-utilized, use fetch_resource_recommendation to answer
+* When asked about "GPU workloads" or filtering out GPU-based resources, you can use filters like name_pattern or namespace to exclude them
+* Right-sizing of resources is key to avoiding performance issues and achieving cost savings
+* Examples of questions that use fetch_resource_recommendation:
+  - "Show me top CPU recommendations" → Use limit=10, sort_by='cpu_total'
+  - "What are the biggest memory optimization opportunities?" → Use limit=10, sort_by='memory_total'
+  - "Show me top KRR recommendations for non-GPU workloads" → Use name_pattern filter or namespace filter
+  - "Find workloads in namespace X that can save the most CPU" → Use namespace='X', sort_by='cpu_total'
+  - "Get recommendations for deployment nginx in namespace prod" → Use name_pattern='nginx', namespace='prod', kind='Deployment'
 
 # Investigating issues
 * If provided an issue id (a.k.a. a finding), use `fetch_finding_by_id` to get more information about that issue