holmesgpt 0.13.2__py3-none-any.whl → 0.16.2a0__py3-none-any.whl

holmes/plugins/toolsets/prometheus/prometheus_instructions.jinja2

@@ -1,6 +1,27 @@
 
 # Prometheus/PromQL queries
-* ALWAYS call list_prometheus_rules to get the alert definition
+
+## Efficient Metric Discovery (when needed)
+* When you need to discover metrics, use `get_metric_names` with filters - it's the fastest method
+* Combine multiple patterns with regex OR (|) to reduce API calls:
+  - `{__name__=~"node_cpu.*|node_memory.*|node_disk.*"}` - get all node resource metrics in one call
+  - `{__name__=~"container.*|pod.*|kube.*"}` - get all Kubernetes-related metrics
+  - `{namespace=~"example1|example2|example3"}` - metrics from multiple namespaces
+* Use `get_metric_metadata` after discovering names to get types/descriptions if needed
+* Use `get_label_values` to discover pods, namespaces, jobs: e.g., get_label_values(label="pod")
+* Only use `get_series` when you need full label sets (slower than other methods)
+
+## Retrying queries that return too much data
+* When a Prometheus query returns too much data (e.g., truncation error), you MUST retry with a more specific query or less data points or topk/bottomk
+* NEVER EVER EVER answer a question based on Prometheus data that was truncated as you might be missing important information and give the totally wrong answer
+* Prefer telling the user you can't answer the question because of too much data rather than answering based on incomplete data
+* You are also able to show graphs to the user (using the promql embed functionality mentioned below) so you can show users graphs and THEY can interpret the data themselves, even if you can't answer.
+* Do NOT hestitate to try alternative queries and try to reduce the amount of data returned until you get a successful query
+* Be extremely, extremely cautious when answering based on get_label_values because the existence of a label value says NOTHING about the metric value itself (is it high, low, or perhaps the label exists in Prometheus but its an older series not present right now)
+* DO NOT give answers about metrics based on what 'is typically the case' or 'common knowledge' - if you can't see the actual metric value, you MUST NEVER EVER answer about it - just tell the user your limitations due to the size of the data
+
+## Alert Investigation & Query Execution
+* When investigating a Prometheus alert, ALWAYS call list_prometheus_rules to get the alert definition
 * Use Prometheus to query metrics from the alert promql
 * Use prometheus to execute promql queries with the tools `execute_prometheus_instant_query` and `execute_prometheus_range_query`
 * To create queries, use 'start_timestamp' and 'end_timestamp' as graphs start and end times
@@ -16,9 +37,29 @@
 ** Avoid global averages like `sum(rate(<metric>_sum)) / sum(rate(<metric>_count))` because it hides data and is not generally informative
 * Timestamps MUST be in string date format. For example: '2025-03-15 10:10:08.610862+00:00'
 * Post processing will parse your response, re-run the query from the tool output and create a chart visible to the user
-* Only generate and execute a prometheus query after checking what metrics are available with the `list_available_metrics` tool
+* When unsure about available metrics, use `get_metric_names` with appropriate filters (combine multiple patterns with | for efficiency). Then use `get_metric_metadata` if you need descriptions/types
 * Check that any node, service, pod, container, app, namespace, etc. mentioned in the query exist in the kubernetes cluster before making a query. Use any appropriate kubectl tool(s) for this
 * The toolcall will return no data to you. That is expected. You MUST however ensure that the query is successful.
+
+## Handling High-Cardinality Metrics
+* CRITICAL: When querying metrics that may return many time series (>10), ALWAYS use aggregation to limit results
+* ALWAYS use `topk()` or `bottomk()` to limit the number of series returned
+* Standard pattern for high-cardinality queries:
+  - Use `topk(5, <your_query>)` to get the top 5 series
+  - Example: `topk(5, rate(container_cpu_usage_seconds_total{namespace="example"}[5m]))`
+  - This prevents context overflow and focuses on the most relevant data
+* To also capture the aggregate of remaining series as "other":
+  ```
+  topk(5, rate(container_cpu_usage_seconds_total{namespace="example"}[5m])) or label_replace((sum(rate(container_cpu_usage_seconds_total{namespace="example"}[5m])) - sum(topk(5, rate(container_cpu_usage_seconds_total{namespace="example"}[5m])))), "pod", "other", "", "")
+  ```
+* Common high-cardinality scenarios requiring topk():
+  - Pod-level metrics in namespaces with many pods
+  - Container-level CPU/memory metrics
+  - HTTP metrics with many endpoints or status codes
+  - Any query returning more than 10 time series
+* For initial exploration, you may use instant queries with `count()` to check cardinality:
+  - Example: `count(count by (pod) (container_cpu_usage_seconds_total{namespace="example"}))`
+  - If count > 10, use topk() in your range query
 * When doing queries, always extend the time range, to 15 min before and after the alert start time
 * ALWAYS embed the execution results into your answer
 * ALWAYS embed a Prometheus graph in the response. The graph should visualize data related to the incident.

holmes/plugins/toolsets/prometheus/utils.py

@@ -0,0 +1,28 @@
+import re
+from typing import Optional, Union
+
+
+def parse_duration_to_seconds(v: Optional[Union[str, float, int]]) -> Optional[float]:
+    if v is None:
+        return None
+    if isinstance(v, (int, float)):
+        return float(v)
+    s = v.strip().lower()
+    if s.isdigit():
+        return float(int(s))
+
+    units = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+
+    # Check for partial time formats (e.g., 1h30m, 5m12s, 1d2h30m)
+    pattern = r"(\d+(?:\.\d+)?)(d|h|m|s)"
+    matches = re.findall(pattern, s)
+
+    if matches:
+        total_seconds = 0.0
+        for value_str, unit in matches:
+            value = float(value_str)
+            total_seconds += value * units[unit]
+        return float(int(total_seconds))
+
+    # fallback: try float seconds
+    return float(s)

holmes/plugins/toolsets/rabbitmq/toolset_rabbitmq.py

@@ -7,8 +7,9 @@ from holmes.core.tools import (
     CallablePrerequisite,
     StructuredToolResult,
     Tool,
+    ToolInvokeContext,
     ToolParameter,
-    ToolResultStatus,
+    StructuredToolResultStatus,
     Toolset,
     ToolsetTag,
 )
@@ -63,9 +64,7 @@ class ListConfiguredClusters(BaseRabbitMQTool):
             toolset=toolset,
         )
 
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
         if not self.toolset.config:
             raise ValueError("RabbitMQ is not configured.")
 
@@ -79,7 +78,7 @@ class ListConfiguredClusters(BaseRabbitMQTool):
             if c.connection_status == ClusterConnectionStatus.SUCCESS
         ]
         return StructuredToolResult(
-            status=ToolResultStatus.SUCCESS, data=available_clusters
+            status=StructuredToolResultStatus.SUCCESS, data=available_clusters
         )
 
     def get_parameterized_one_liner(self, params) -> str:
@@ -103,21 +102,21 @@ class GetRabbitMQClusterStatus(BaseRabbitMQTool):
             toolset=toolset,
         )
 
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
         try:
             # Fetch node details which include partition info
             cluster_config = self._get_cluster_config(
                 cluster_id=params.get("cluster_id")
             )
             result = get_cluster_status(cluster_config)
-            return StructuredToolResult(status=ToolResultStatus.SUCCESS, data=result)
+            return StructuredToolResult(
+                status=StructuredToolResultStatus.SUCCESS, data=result
+            )
 
         except Exception as e:
             logging.info("Failed to process RabbitMQ cluster status", exc_info=True)
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=f"Unexpected error fetching RabbitMQ cluster status: {str(e)}",
                 data=None,
             )

holmes/plugins/toolsets/robusta/robusta.py

@@ -3,21 +3,27 @@ import os
 import logging
 
 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 SupabaseDal, FindingType
 from holmes.core.tools import (
     StaticPrerequisite,
     Tool,
+    ToolInvokeContext,
     ToolParameter,
     Toolset,
     ToolsetTag,
 )
-from holmes.core.tools import StructuredToolResult, ToolResultStatus
+from holmes.core.tools import StructuredToolResult, StructuredToolResultStatus
+
+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