holmesgpt 0.14.4a0__py3-none-any.whl → 0.16.0__py3-none-any.whl

holmes/plugins/toolsets/opensearch/opensearch_query_assist.py

@@ -0,0 +1,78 @@
+import logging
+import os
+from typing import Any, Dict
+
+from holmes.core.tools import (
+    StructuredToolResult,
+    StructuredToolResultStatus,
+    Tool,
+    ToolParameter,
+    Toolset,
+    ToolsetTag,
+    ToolInvokeContext,
+    ToolsetEnvironmentPrerequisite,
+)
+
+
+class PplQueryAssistTool(Tool):
+    def __init__(self, toolset: "OpenSearchQueryAssistToolset"):
+        super().__init__(
+            name="opensearch_ppl_query_assist",
+            description="Generate valid OpenSearch Piped Processing Language (PPL) queries to suggest to users for execution",
+            parameters={
+                "query": ToolParameter(
+                    description="Valid OpenSearch Piped Processing Language (PPL) query to suggest to users for execution",
+                    type="string",
+                    required=True,
+                ),
+            },
+        )
+        self._toolset = toolset
+
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
+        try:
+            query = params.get("query", "")
+            response_data = {"query": query}
+            return StructuredToolResult(
+                status=StructuredToolResultStatus.SUCCESS,
+                data=response_data,
+                params=params,
+            )
+
+        except Exception as e:
+            logging.exception(f"error using {self.name} tool")
+            return StructuredToolResult(
+                status=StructuredToolResultStatus.ERROR,
+                error=f"Failed to generate PPL query: {str(e)}",
+                params=params,
+            )
+
+    def get_parameterized_one_liner(self, params: Dict) -> str:
+        query = params.get("query", "")
+        return f"OpenSearchQueryToolset: Query ({query})"
+
+
+class OpenSearchQueryAssistToolset(Toolset):
+    """OpenSearch query assist with PPL queries"""
+
+    def __init__(self):
+        super().__init__(
+            name="opensearch/query_assist",
+            description="OpenSearch query assist with PPL queries.",
+            experimental=True,
+            icon_url="https://opensearch.org/assets/brand/PNG/Mark/opensearch_mark_default.png",
+            tools=[PplQueryAssistTool(self)],
+            tags=[ToolsetTag.CORE],
+            prerequisites=[ToolsetEnvironmentPrerequisite(env=["OPENSEARCH_URL"])],
+        )
+
+    def get_example_config(self) -> Dict[str, Any]:
+        return {"opensearch_url": "http://localhost:9200"}
+
+    def _reload_instructions(self):
+        template_file_path = os.path.abspath(
+            os.path.join(
+                os.path.dirname(__file__), "opensearch_query_assist_instructions.jinja2"
+            )
+        )
+        self._load_llm_instructions(jinja_template=f"file://{template_file_path}")

holmes/plugins/toolsets/opensearch/opensearch_query_assist_instructions.jinja2

@@ -0,0 +1,223 @@
+# Query Generation
+You have access to the opensearch_ppl_query_assist tool to help you generate your valid, accurate OpenSearch Piped Processing Language (PPL) queries.
+DO NOT PROVIDE INVALID QUERIES. ALWAYS CHECK YOUR QUERY WITH VALID QUERIES FIRST.
+
+Once a valid query is generated, you MUST provide a concise, but informative breakdown of each part of the query structure
+
+## CRITICAL: Query Intent Detection
+
+ALWAYS check if the user's question is about:
+
+* Log Analysis: Errors, warnings, messages, patterns, tool usage
+* Metrics Analysis: Performance, latency, throughput, resource usage
+* Time-based Analysis: "Last X hours/days", "recent", "today", "since"
+* Aggregation Requests: Count, sum, average, top, frequency
+* Troubleshooting: Issues, problems, failures, debugging
+
+If ANY of the above apply → Generate PPL query IMMEDIATELY and use the OpenSearch Dashboards Page State
+
+### Example GOOD response:
+I've retrieved your current query from the query bar `source=logs-otel-v1* | STAT count() BY severityText` and it
+appears there is a typo in "STAT", it should be "STATS". Below is the fixed query:
+```
+source=logs-otel-v1* | STATS count() BY severityText
+```
+
+
+## CRITICAL: OpenSearch Dashboards Page State
+User may be using this agent from OpenSearch Dashboards (OSD) for which provides the current page state.
+It may be included in the conversation history as a system message.
+
+IMPORTANT: YOU CAN USE THE CURRENT USE QUERY TO HELP ENHANCE/MODIFY/FIX/SUGGEST VALID QUERY USING THE SAME INDEX PATTERN
+REFER TO "Core PPL Commands" FOR SYNTAX
+
+```
+## OpenSearch PPL Query Language
+
+### PPL (Piped Processing Language) Overview
+PPL is OpenSearch's query language for analyzing logs, metrics, and traces. It uses a pipe-based syntax similar to Unix commands, processing data through sequential transformations.
+
+### Core PPL Commands
+
+**Data Source & Search:**
+- `source=<index>` or `search source=<index>` - Specify data source
+- `source=<cluster>:<index>` - Cross-cluster search
+- `| where <condition>` - Filter results
+- `| fields <field-list>` - Project specific fields
+- `| fields - <field-list>` - Exclude specific fields
+
+**Data Transformation:**
+- `| stats <aggregation> by <field>` - Aggregate data (count(), sum(), avg(), min(), max())
+- `| eval <field>=<expression>` - Create calculated fields
+- `| sort [+|-] <field>` - Sort results (+ ascending, - descending)
+- `| head <n>` - Return first n results
+- `| tail <n>` - Return last n results
+- `| dedup <field-list>` - Remove duplicates
+
+**Advanced Analysis:**
+- `| top [N] <field>` - Find most common values
+- `| rare [N] <field>` - Find least common values
+- `| parse <field> <regex>` - Extract fields using regex patterns
+- `| grok <field> <pattern>` - Parse using grok patterns
+- `| patterns <field> [SIMPLE_PATTERN|BRAIN]` - Extract log patterns
+
+**Time Series:**
+- `| trendline SMA(<period>, <field>)` - Calculate moving averages
+- `| fillnull with <value> in <fields>` - Replace null values
+
+**Joins & Lookups:**
+- `| join <table>` - Join with another dataset
+- `| lookup <table> <field>` - Enrich with lookup data (requires Calcite)
+
+**Pattern Extraction:**
+- `| patterns message BRAIN` - Semantic log pattern extraction
+- `| patterns new_field='extracted' pattern='[0-9]' message` - Custom regex patterns
+
+### PPL Query Examples for Observability
+
+**Error Analysis:**
+```ppl
+source=ai-agent-logs-*
+| where level="ERROR"
+| stats count() by message
+| sort - count
+```
+
+**Service Latency Analysis:**
+```ppl
+source=traces
+| where service="checkout"
+| stats avg(duration) as avg_latency, max(duration) as max_latency by endpoint
+| where avg_latency > 100
+```
+
+**Log Pattern Detection:**
+```ppl
+source=ai-agent-audit-logs-*
+| patterns message BRAIN
+| stats count() by patterns_field
+| top 10 patterns_field
+```
+
+**Time-based Aggregation:**
+```ppl
+source=metrics
+| eval hour=date_format(timestamp, 'HH')
+| stats avg(cpu_usage) by hour, host
+| sort hour
+```
+
+**Multi-field Correlation:**
+```ppl
+source=ai-agent-logs-*
+| parse message '.*thread_id=(?<tid>[^,]+).*run_id=(?<rid>[^,]+)'
+| stats count() by tid, rid, level
+| where count > 100
+```
+
+**Advanced PPL Query Patterns:**
+
+**Top N Analysis with Filtering:**
+```ppl
+source=ai-agent-logs-*
+| where timestamp >= now() - 1h
+| top 20 message by level
+| where level in ["ERROR", "WARN"]
+```
+
+**Deduplication and Unique Values:**
+```ppl
+source=ai-agent-audit-logs-*
+| dedup thread_id
+| fields thread_id, run_id, timestamp
+| sort - timestamp
+```
+
+**Fillnull for Missing Data Handling:**
+```ppl
+source=ai-agent-metrics-*
+| fillnull with 0 in cpu_usage, memory_usage
+| stats avg(cpu_usage) as avg_cpu, avg(memory_usage) as avg_mem by host
+```
+
+**Rare Events Detection:**
+```ppl
+source=ai-agent-logs-*
+| rare 10 error_code
+| where count < 5
+```
+
+**Field Extraction with Grok:**
+```ppl
+source=ai-agent-logs-*
+| grok message '%{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:level} %{GREEDYDATA:msg}'
+| stats count() by level
+```
+
+**Time Span Aggregations:**
+```ppl
+source=ai-agent-metrics-*
+| stats count() by span(timestamp, 5m) as time_bucket, status
+| where status != 200
+```
+
+**Eval with Conditional Logic:**
+```ppl
+source=ai-agent-logs-*
+| eval severity = case(
+    level = "ERROR", 1,
+    level = "WARN", 2,
+    level = "INFO", 3,
+    else = 4
+  )
+| stats count() by severity
+```
+
+**Join Operations (with Calcite enabled):**
+```ppl
+source=ai-agent-logs-*
+| join left=l right=r on l.thread_id = r.thread_id
+  [ source=ai-agent-audit-logs-* ]
+| fields l.timestamp, l.message, r.tool_name
+```
+
+**Subquery for Complex Filtering:**
+```ppl
+source=ai-agent-logs-*
+| where thread_id in [
+    source=ai-agent-audit-logs-*
+    | where tool_name = "opensearch__search"
+    | fields thread_id
+  ]
+```
+
+**Trendline for Moving Averages:**
+```ppl
+source=ai-agent-metrics-*
+| trendline SMA(5, cpu_usage) as cpu_trend
+| fields timestamp, cpu_usage, cpu_trend
+```
+
+### PPL Best Practices
+
+1. **Index Patterns**: Use wildcards for daily indices: `source=ai-agent-logs-*`
+2. **Field Extraction**: Use `parse` for structured logs, `patterns` for unstructured
+3. **Performance**: Apply `where` filters early in the pipeline
+4. **Aggregations**: Use `stats` before `sort` for better performance
+5. **Null Handling**: Use `fillnull` to handle missing data in calculations
+
+### OpenSearch Index Patterns (Current Environment)
+- `ai-agent-logs-YYYY.MM.DD` - Application logs
+- `ai-agent-audit-logs-YYYY.MM.DD` - Audit logs
+- `ai-agent-metrics-YYYY.MM.DD` - Prometheus metrics
+
+## Query Response Formatting
+You MUST respond with queries in the following format. `ppl` contains the valid ppl query
+```typescript
+query: {
+ ppl: string,
+}
+```
+
+## More PPL Queries
+{% include "opensearch_ppl_query_docs.jinja2" %}

holmes/plugins/toolsets/prometheus/prometheus.py

@@ -1591,7 +1591,7 @@ class PrometheusToolset(Toolset):
                 )
 
         except Exception as e:
-            logging.exception("Failed to initialize Prometheus", exc_info=True)
+            logging.debug("Failed to initialize Prometheus", exc_info=True)
             return (
                 False,
                 f"Failed to initialize using url={url}. Unexpected error: {str(e)}",

holmes/plugins/toolsets/robusta/robusta.py

@@ -19,6 +19,8 @@ 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):
@@ -27,7 +29,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",
@@ -75,7 +77,7 @@ class FetchRobustaFinding(Tool):
             )
 
     def get_parameterized_one_liner(self, params: Dict) -> str:
-        return "Robusta: Fetch Alert Metadata"
+        return f"Robusta: Fetch finding data {params}"
 
 
 class FetchResourceRecommendation(Tool):
@@ -142,13 +144,17 @@ class FetchResourceRecommendation(Tool):
         return f"Robusta: Check Historical Resource Utilization: ({str(params)})"
 
 
-class FetchConfigurationChanges(Tool):
+class FetchConfigurationChangesMetadata(Tool):
     _dal: Optional[SupabaseDal]
 
     def __init__(self, dal: Optional[SupabaseDal]):
         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",
+            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 workload. "
+                "Use fetch_finding_by_id to get detailed change of one specific configuration change."
+            ),
             parameters={
                 START_TIME: ToolParameter(
                     description="The starting time boundary for the search period. String in RFC3339 format.",
@@ -160,15 +166,36 @@ class FetchConfigurationChanges(Tool):
                     type="string",
                     required=True,
                 ),
+                "namespace": ToolParameter(
+                    description="The Kubernetes namespace name for filtering configuration changes",
+                    type="string",
+                    required=False,
+                ),
+                "workload": ToolParameter(
+                    description="The kubernetes workload name for filtering configuration changes. Deployment name or Pod name for example.",
+                    type="string",
+                    required=False,
+                ),
+                "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,
+                ),
             },
         )
         self._dal = dal
 
     def _fetch_change_history(self, params: Dict) -> Optional[List[Dict]]:
         if self._dal and self._dal.enabled:
-            return self._dal.get_configuration_changes(
+            return self._dal.get_configuration_changes_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"),
             )
         return None
 
@@ -197,7 +224,7 @@ class FetchConfigurationChanges(Tool):
             )
 
     def get_parameterized_one_liner(self, params: Dict) -> str:
-        return "Robusta: Search Change History"
+        return f"Robusta: Search Change History {params}"
 
 
 class RobustaToolset(Toolset):
@@ -219,7 +246,7 @@ class RobustaToolset(Toolset):
             prerequisites=[dal_prereq],
             tools=[
                 FetchRobustaFinding(dal),
-                FetchConfigurationChanges(dal),
+                FetchConfigurationChangesMetadata(dal),
                 FetchResourceRecommendation(dal),
             ],
             tags=[

holmes/plugins/toolsets/robusta/robusta_instructions.jinja2

@@ -1,7 +1,8 @@
 # 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 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:

holmes/plugins/toolsets/service_discovery.py

@@ -36,7 +36,7 @@ def find_service_url(label_selector):
         port = svc.spec.ports[0].port
         url = f"http://{name}.{namespace}.svc.{CLUSTER_DOMAIN}:{port}"
         logging.info(
-            f"discovered service with label-selector: `{label_selector}` at url: `{url}`"
+            f"Discovered service with label-selector: `{label_selector}` at url: `{url}`"
         )
         return url
     except Exception:

holmes/plugins/toolsets/servicenow/servicenow.py

@@ -37,7 +37,6 @@ class ServiceNowToolset(Toolset):
     def __init__(self):
         super().__init__(
             prerequisites=[CallablePrerequisite(callable=self.prerequisites_callable)],
-            experimental=True,
             tools=[
                 ReturnChangesInTimerange(toolset=self),
                 ReturnChange(toolset=self),

holmes/utils/stream.py

@@ -1,11 +1,15 @@
 import json
 from enum import Enum
-from typing import Generator, Optional, List
+from typing import Generator, Optional, List, Union
 import litellm
 from pydantic import BaseModel, Field
 from holmes.core.investigation_structured_output import process_response_into_sections
 from functools import partial
 import logging
+from litellm.litellm_core_utils.streaming_handler import CustomStreamWrapper
+from litellm.types.utils import ModelResponse, TextCompletionResponse
+
+from holmes.core.llm import TokenCountMetadata, get_llm_usage
 
 
 class StreamEvents(str, Enum):
@@ -15,6 +19,8 @@ class StreamEvents(str, Enum):
     ERROR = "error"
     AI_MESSAGE = "ai_message"
     APPROVAL_REQUIRED = "approval_required"
+    TOKEN_COUNT = "token_count"
+    CONVERSATION_HISTORY_COMPACTED = "conversation_history_compacted"
 
 
 class StreamMessage(BaseModel):
@@ -112,3 +118,27 @@ def stream_chat_formatter(
             yield create_rate_limit_error_message(str(e))
         else:
             yield create_sse_error_message(description=str(e), error_code=1, msg=str(e))
+
+
+def add_token_count_to_metadata(
+    tokens: TokenCountMetadata,
+    metadata: dict,
+    max_context_size: int,
+    maximum_output_token: int,
+    full_llm_response: Union[
+        ModelResponse, CustomStreamWrapper, TextCompletionResponse
+    ],
+):
+    metadata["usage"] = get_llm_usage(full_llm_response)
+    metadata["tokens"] = tokens.model_dump()
+    metadata["max_tokens"] = max_context_size
+    metadata["max_output_tokens"] = maximum_output_token
+
+
+def build_stream_event_token_count(metadata: dict) -> StreamMessage:
+    return StreamMessage(
+        event=StreamEvents.TOKEN_COUNT,
+        data={
+            "metadata": metadata,
+        },
+    )

{holmesgpt-0.14.4a0.dist-info → holmesgpt-0.16.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: holmesgpt
-Version: 0.14.4a0
+Version: 0.16.0
 Summary: 
 Author: Natan Yellin
 Author-email: natan@robusta.dev
@@ -8,6 +8,7 @@ Requires-Python: >=3.10,<4.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: ag-ui-protocol (>=0.1.9,<0.2.0)
 Requires-Dist: azure-core (>=1.34.0,<2.0.0)
 Requires-Dist: azure-identity (>=1.23.0,<2.0.0)
 Requires-Dist: azure-mgmt-alertsmanagement (>=1.0.0,<2.0.0)
@@ -23,6 +24,7 @@ Requires-Dist: certifi (>=2024.7.4,<2025.0.0)
 Requires-Dist: colorlog (>=6.8.2,<7.0.0)
 Requires-Dist: confluent-kafka (>=2.6.1,<3.0.0)
 Requires-Dist: fastapi (>=0.116,<0.117)
+Requires-Dist: google-cloud-aiplatform (>=1.38)
 Requires-Dist: httpx[socks] (<0.28)
 Requires-Dist: humanize (>=4.9.0,<5.0.0)
 Requires-Dist: jinja2 (>=3.1.2,<4.0.0)
@@ -56,7 +58,9 @@ Description-Content-Type: text/markdown
 
 HolmesGPT is an AI agent for investigating problems in your cloud, finding the root cause, and suggesting remediations. It has dozens of built-in integrations for cloud providers, observability tools, and on-call systems.
 
-HolmesGPT has been submitted to the CNCF as a sandbox project ([view status](https://github.com/cncf/sandbox/issues/392)). You can learn more about HolmesGPT's maintainers and adopters [here](./ADOPTERS.md).
+>🎉 **HolmesGPT is now a CNCF Sandbox Project!** We're thrilled to be part of the Cloud Native Computing Foundation. [Learn more about our journey](https://github.com/cncf/sandbox/issues/392#issuecomment-3380007501).
+
+Find more about HolmesGPT's maintainers and adopters [here](./ADOPTERS.md).
 
   <p align="center">
     <a href="#how-it-works"><strong>How it Works</strong></a> |