awslabs.cloudwatch-mcp-server 0.0.10__tar.gz → 0.0.13__tar.gz

{awslabs_cloudwatch_mcp_server-0.0.10 → awslabs_cloudwatch_mcp_server-0.0.13}/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+
+## [0.0.5] - 2025-10-06
+
+### Added
+
+- Added tool to analyze CloudWatch Metric data
+
+### Changed
+
+- Updated Alarm recommendation tool to support CloudWatch Anomaly Detection Alarms
+
 ## [0.0.4] - 2025-07-11
 
 ### Changed

{awslabs_cloudwatch_mcp_server-0.0.10 → awslabs_cloudwatch_mcp_server-0.0.13}/Dockerfile

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 # dependabot should continue to update this to the latest hash.
-FROM public.ecr.aws/docker/library/python:3.13.5-alpine3.21@sha256:c9a09c45a4bcc618c7f7128585b8dd0d41d0c31a8a107db4c8255ffe0b69375d AS uv
+FROM public.ecr.aws/docker/library/python:3.13-alpine@sha256:070342a0cc1011532c0e69972cce2bbc6cc633eba294bae1d12abea8bd05303b AS uv
 
 # Install the project into `/app`
 WORKDIR /app
@@ -61,7 +61,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 # Make the directory just in case it doesn't exist
 RUN mkdir -p /root/.local
 
-FROM public.ecr.aws/docker/library/python:3.13.5-alpine3.21@sha256:c9a09c45a4bcc618c7f7128585b8dd0d41d0c31a8a107db4c8255ffe0b69375d
+FROM public.ecr.aws/docker/library/python:3.13-alpine@sha256:070342a0cc1011532c0e69972cce2bbc6cc633eba294bae1d12abea8bd05303b
 
 # Place executables in the environment at the front of the path and include other binaries
 ENV PATH="/app/.venv/bin:$PATH" \

{awslabs_cloudwatch_mcp_server-0.0.10 → awslabs_cloudwatch_mcp_server-0.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: awslabs.cloudwatch-mcp-server
-Version: 0.0.10
+Version: 0.0.13
 Summary: An AWS Labs Model Context Protocol (MCP) server for cloudwatch
 Project-URL: homepage, https://awslabs.github.io/mcp/
 Project-URL: docs, https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server/
@@ -24,7 +24,10 @@ Requires-Python: >=3.10
 Requires-Dist: boto3>=1.38.22
 Requires-Dist: loguru>=0.7.0
 Requires-Dist: mcp[cli]>=1.11.0
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: pandas>=2.2.3
 Requires-Dist: pydantic>=2.10.6
+Requires-Dist: statsmodels>=0.14.0
 Description-Content-Type: text/markdown
 
 # AWS Labs cloudwatch MCP Server
@@ -57,7 +60,8 @@ Alarm Recommendations - Suggests recommended alarm configurations for CloudWatch
 ### Tools for CloudWatch Metrics
 * `get_metric_data` - Retrieves detailed CloudWatch metric data for any CloudWatch metric. Use this for general CloudWatch metrics that aren't specific to Application Signals. Provides ability to query any metric namespace, dimension, and statistic
 * `get_metric_metadata` - Retrieves comprehensive metadata about a specific CloudWatch metric
-* `get_recommended_metric_alarms` - Gets recommended alarms for a CloudWatch metric
+* `get_recommended_metric_alarms` - Gets recommended alarms for a CloudWatch metric based on best practice, and trend, seasonality and statistical analysis.
+* `analyze_metric` - Analyzes CloudWatch metric data to determine trend, seasonality, and statistical properties
 
 ### Tools for CloudWatch Alarms
 * `get_active_alarms` - Identifies currently active CloudWatch alarms across the account

{awslabs_cloudwatch_mcp_server-0.0.10 → awslabs_cloudwatch_mcp_server-0.0.13}/README.md

@@ -28,7 +28,8 @@ Alarm Recommendations - Suggests recommended alarm configurations for CloudWatch
 ### Tools for CloudWatch Metrics
 * `get_metric_data` - Retrieves detailed CloudWatch metric data for any CloudWatch metric. Use this for general CloudWatch metrics that aren't specific to Application Signals. Provides ability to query any metric namespace, dimension, and statistic
 * `get_metric_metadata` - Retrieves comprehensive metadata about a specific CloudWatch metric
-* `get_recommended_metric_alarms` - Gets recommended alarms for a CloudWatch metric
+* `get_recommended_metric_alarms` - Gets recommended alarms for a CloudWatch metric based on best practice, and trend, seasonality and statistical analysis.
+* `analyze_metric` - Analyzes CloudWatch metric data to determine trend, seasonality, and statistical properties
 
 ### Tools for CloudWatch Alarms
 * `get_active_alarms` - Identifies currently active CloudWatch alarms across the account

{awslabs_cloudwatch_mcp_server-0.0.10 → awslabs_cloudwatch_mcp_server-0.0.13}/awslabs/cloudwatch_mcp_server/__init__.py

@@ -14,4 +14,4 @@
 
 """awslabs.cloudwatch-mcp-server"""
 
-MCP_SERVER_VERSION = '0.0.1'
+MCP_SERVER_VERSION = '0.0.12'

{awslabs_cloudwatch_mcp_server-0.0.10 → awslabs_cloudwatch_mcp_server-0.0.13}/awslabs/cloudwatch_mcp_server/cloudwatch_alarms/models.py

@@ -54,7 +54,7 @@ class CompositeAlarmSummary(BaseModel):
 
 
 class ActiveAlarmsResponse(BaseModel):
-    """Response containing active CloudWatch alarms."""
+    """Response containing active CloudWatch Alarms."""
 
     metric_alarms: List[MetricAlarmSummary] = Field(
         default_factory=list, description='List of active metric alarms'

{awslabs_cloudwatch_mcp_server-0.0.10 → awslabs_cloudwatch_mcp_server-0.0.13}/awslabs/cloudwatch_mcp_server/cloudwatch_alarms/tools.py

@@ -80,9 +80,9 @@ class CloudWatchAlarmsTools:
             Field(description='AWS region to query. Defaults to us-east-1.'),
         ] = 'us-east-1',
     ) -> ActiveAlarmsResponse:
-        """Gets all CloudWatch alarms currently in ALARM state.
+        """Gets all CloudWatch Alarms currently in ALARM state.
 
-        This tool retrieves all CloudWatch alarms that are currently in the ALARM state,
+        This tool retrieves all CloudWatch Alarms that are currently in the ALARM state,
         including both metric alarms and composite alarms. Results are optimized for
         LLM reasoning with summary-level information.
 

{awslabs_cloudwatch_mcp_server-0.0.10 → awslabs_cloudwatch_mcp_server-0.0.13}/awslabs/cloudwatch_mcp_server/cloudwatch_logs/tools.py

@@ -168,12 +168,37 @@ class CloudWatchLogsTools:
         """
         poll_start = timer()
         while poll_start + max_timeout > timer():
-            response = logs_client.get_query_results(queryId=query_id)
-            status = response['status']
+            try:
+                response = logs_client.get_query_results(queryId=query_id)
+                status = response['status']
+
+                logger.debug(f'Query {query_id} status: {status}')
+
+                if status in {'Complete', 'Failed', 'Cancelled'}:
+                    logger.info(f'Query {query_id} finished with status {status}')
+                    result = self._process_query_results(response, query_id)
+
+                    # Handle case where query completed but returned no results
+                    if status == 'Complete' and not result.get('results'):
+                        logger.info(f'Query {query_id} completed but returned no results')
+                        result['results'] = []
+
+                    return result
+
+                # Handle unexpected status states
+                if status not in {'Scheduled', 'Running'}:
+                    logger.warning(f'Query {query_id} has unexpected status: {status}')
+                    return self._process_query_results(response, query_id)
 
-            if status in {'Complete', 'Failed', 'Cancelled'}:
-                logger.info(f'Query {query_id} finished with status {status}')
-                return self._process_query_results(response, query_id)
+            except Exception as e:
+                logger.error(f'Error polling for query {query_id} completion: {str(e)}')
+                await ctx.error(f'Error during query polling: {str(e)}')
+                return {
+                    'queryId': query_id,
+                    'status': 'Error',
+                    'message': f'Error occurred while polling: {str(e)}',
+                    'results': [],
+                }
 
             await asyncio.sleep(1)
 
@@ -184,6 +209,7 @@ class CloudWatchLogsTools:
             'queryId': query_id,
             'status': 'Polling Timeout',
             'message': msg,
+            'results': [],
         }
 
     def register(self, mcp):
@@ -576,8 +602,16 @@ class CloudWatchLogsTools:
 
         except Exception as e:
             logger.error(f'Error in execute_log_insights_query_tool: {str(e)}')
-            await ctx.error(f'Error executing CloudWatch Logs Insights query: {str(e)}')
-            raise
+            error_msg = f'Error executing CloudWatch Logs Insights query: {str(e)}'
+            await ctx.error(error_msg)
+
+            # Instead of raising, return a consistent error result
+            return {
+                'queryId': '',
+                'status': 'Error',
+                'message': error_msg,
+                'results': [],
+            }
 
     async def get_logs_insight_query_results(
         self,
@@ -612,11 +646,26 @@ class CloudWatchLogsTools:
 
             logger.info(f'Retrieved results for query ID {query_id}')
 
-            return self._process_query_results(response, query_id)
+            result = self._process_query_results(response, query_id)
+
+            # Ensure results is always an array, even if empty
+            if not result.get('results'):
+                result['results'] = []
+
+            return result
+
         except Exception as e:
             logger.error(f'Error in get_query_results_tool: {str(e)}')
-            await ctx.error(f'Error retrieving CloudWatch Logs Insights query results: {str(e)}')
-            raise
+            error_msg = f'Error retrieving CloudWatch Logs Insights query results: {str(e)}'
+            await ctx.error(error_msg)
+
+            # Return consistent error structure instead of raising
+            return {
+                'queryId': query_id,
+                'status': 'Error',
+                'message': error_msg,
+                'results': [],
+            }
 
     async def cancel_logs_insight_query(
         self,

awslabs_cloudwatch_mcp_server-0.0.13/awslabs/cloudwatch_mcp_server/cloudwatch_metrics/cloudformation_template_generator.py

@@ -0,0 +1,162 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+from awslabs.cloudwatch_mcp_server.cloudwatch_metrics.constants import COMPARISON_OPERATOR_ANOMALY
+from awslabs.cloudwatch_mcp_server.cloudwatch_metrics.models import AnomalyDetectionAlarmThreshold
+from typing import Any, Dict
+
+
+logger = logging.getLogger(__name__)
+
+
+class CloudFormationTemplateGenerator:
+    """Generate CloudFormation JSON for CloudWatch Anomaly Detection Alarms."""
+
+    def generate_metric_alarm_template(self, alarm_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Generate CFN template for a single CloudWatch Alarm."""
+        if not self._is_anomaly_detection_alarm(alarm_data):
+            return {}
+
+        # Validate required fields
+        if not alarm_data.get('metricName'):
+            raise ValueError(
+                'Metric Name is required to generate CloudFormation templates for Cloudwatch Alarms'
+            )
+        if not alarm_data.get('namespace'):
+            raise ValueError(
+                'Metric Namespace is required to generate CloudFormation templates for Cloudwatch Alarms'
+            )
+
+        # Process alarm data and add computed fields
+        formatted_data = self._format_anomaly_detection_alarm_data(alarm_data)
+
+        # Build resources dict
+        anomaly_detector_key = f'{formatted_data["resourceKey"]}AnomalyDetector'
+        alarm_key = f'{formatted_data["resourceKey"]}Alarm'
+
+        resources = {
+            anomaly_detector_key: {
+                'Type': 'AWS::CloudWatch::AnomalyDetector',
+                'Properties': {
+                    'MetricName': formatted_data['metricName'],
+                    'Namespace': formatted_data['namespace'],
+                    'Stat': formatted_data['statistic'],
+                    'Dimensions': formatted_data['dimensions'],
+                },
+            },
+            alarm_key: {
+                'Type': 'AWS::CloudWatch::Alarm',
+                'DependsOn': anomaly_detector_key,
+                'Properties': {
+                    'AlarmDescription': formatted_data['alarmDescription'],
+                    'Metrics': [
+                        {
+                            'Expression': f'ANOMALY_DETECTION_BAND(m1, {formatted_data["sensitivity"]})',
+                            'Id': 'ad1',
+                        },
+                        {
+                            'Id': 'm1',
+                            'MetricStat': {
+                                'Metric': {
+                                    'MetricName': formatted_data['metricName'],
+                                    'Namespace': formatted_data['namespace'],
+                                    'Dimensions': formatted_data['dimensions'],
+                                },
+                                'Stat': formatted_data['statistic'],
+                                'Period': formatted_data['period'],
+                            },
+                        },
+                    ],
+                    'EvaluationPeriods': formatted_data['evaluationPeriods'],
+                    'DatapointsToAlarm': formatted_data['datapointsToAlarm'],
+                    'ThresholdMetricId': 'ad1',
+                    'ComparisonOperator': formatted_data['comparisonOperator'],
+                    'TreatMissingData': formatted_data['treatMissingData'],
+                },
+            },
+        }
+
+        final_template = {
+            'AWSTemplateFormatVersion': '2010-09-09',
+            'Description': 'CloudWatch Alarms and Anomaly Detectors',
+            'Resources': resources,
+        }
+
+        return final_template
+
+    def _is_anomaly_detection_alarm(self, alarm_data: Dict[str, Any]) -> bool:
+        return alarm_data.get('comparisonOperator') == COMPARISON_OPERATOR_ANOMALY
+
+    def _format_anomaly_detection_alarm_data(self, alarm_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Sanitize alarm data and add computed fields."""
+        formatted_data = alarm_data.copy()
+
+        # Generate resource key from metric name and namespace
+        formatted_data['resourceKey'] = self._generate_resource_key(
+            metric_name=alarm_data.get('metricName', ''),
+            namespace=alarm_data.get('namespace', ''),
+            dimensions=alarm_data.get('dimensions', []),
+        )
+
+        # Process threshold value
+        threshold = alarm_data.get('threshold', {})
+        formatted_data['sensitivity'] = threshold.get(
+            'sensitivity', AnomalyDetectionAlarmThreshold.DEFAULT_SENSITIVITY
+        )
+
+        # Set defaults
+        formatted_data.setdefault(
+            'alarmDescription', 'CloudWatch Alarm generated by CloudWatch MCP server.'
+        )
+        formatted_data.setdefault('statistic', 'Average')
+        formatted_data.setdefault('period', 300)
+        formatted_data.setdefault('evaluationPeriods', 2)
+        formatted_data.setdefault('datapointsToAlarm', 2)
+        formatted_data.setdefault('comparisonOperator', COMPARISON_OPERATOR_ANOMALY)
+        formatted_data.setdefault('treatMissingData', 'missing')
+        formatted_data.setdefault('dimensions', [])
+
+        return formatted_data
+
+    def _generate_resource_key(self, metric_name: str, namespace: str, dimensions: list) -> str:
+        """Generate CloudFormation resource key from metric components to act as logical id."""
+        # Strip AWS/ prefix from namespace (AWS CDK style)
+        clean_namespace = namespace.replace('AWS/', '')
+
+        # Add first dimension key and value for uniqueness if present
+        dimension_suffix = ''
+        if dimensions:
+            first_dim = dimensions[0]
+            dim_name = first_dim.get('Name', '')
+            dim_value = first_dim.get('Value', '')
+            dimension_suffix = f'{dim_name}{dim_value}'
+
+        resource_base = f'{clean_namespace}{metric_name}{dimension_suffix}'
+        return self._sanitize_resource_name(resource_base)
+
+    def _sanitize_resource_name(self, name: str) -> str:
+        """Sanitize name for CloudFormation resource key."""
+        # Remove non-alphanumeric characters
+        sanitized = ''.join(c for c in name if c.isalnum())
+
+        # Ensure it starts with letter
+        if not sanitized or not sanitized[0].isalpha():
+            sanitized = 'Resource' + sanitized
+
+        # Truncate if too long
+        if len(sanitized) > 255:
+            sanitized = sanitized[:255]
+
+        return sanitized

awslabs_cloudwatch_mcp_server-0.0.13/awslabs/cloudwatch_mcp_server/cloudwatch_metrics/constants.py

@@ -0,0 +1,30 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# CloudWatch MCP Server Constants
+
+# Time constants
+SECONDS_PER_MINUTE = 60
+MINUTES_PER_HOUR = 60
+HOURS_PER_DAY = 24
+DAYS_PER_WEEK = 7
+
+# Analysis constants
+DEFAULT_ANALYSIS_PERIOD_MINUTES = 20160  # 2 weeks
+
+# Threshold constants
+COMPARISON_OPERATOR_ANOMALY = 'LessThanLowerOrGreaterThanUpperThreshold'
+
+# Numerical stability
+NUMERICAL_STABILITY_THRESHOLD = 1e-10

awslabs_cloudwatch_mcp_server-0.0.13/awslabs/cloudwatch_mcp_server/cloudwatch_metrics/metric_analyzer.py

@@ -0,0 +1,192 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+from awslabs.cloudwatch_mcp_server.cloudwatch_metrics.constants import (
+    NUMERICAL_STABILITY_THRESHOLD,
+)
+from awslabs.cloudwatch_mcp_server.cloudwatch_metrics.metric_data_decomposer import (
+    MetricDataDecomposer,
+)
+from awslabs.cloudwatch_mcp_server.cloudwatch_metrics.models import (
+    DecompositionResult,
+    MetricData,
+    Seasonality,
+    Trend,
+)
+from collections import Counter
+from loguru import logger
+from typing import Any, Dict, Optional
+
+
+class MetricAnalyzer:
+    """Metric analysis including trend, density, seasonality, and statistical measures."""
+
+    def __init__(self):
+        """Initialize the metric analyzer."""
+        self.decomposer = MetricDataDecomposer()
+
+    def analyze_metric_data(self, metric_data: MetricData) -> Dict[str, Any]:
+        """Analyze metric data and return comprehensive analysis results.
+
+        Args:
+            metric_data: MetricData object containing timestamps and values
+
+        Returns:
+            Dict containing analysis results including seasonality, trend, statistics, and message
+        """
+        if not metric_data.timestamps or not metric_data.values:
+            return {'message': 'No metric data available for analysis'}
+
+        clean_data = [
+            (ts, val)
+            for ts, val in zip(metric_data.timestamps, metric_data.values)
+            if val is not None and not (np.isnan(val) or np.isinf(val))
+        ]
+
+        if len(clean_data) < 2:
+            return {'message': 'Insufficient valid data points for analysis'}
+
+        clean_timestamps, clean_values = zip(*clean_data)
+        clean_timestamps = list(clean_timestamps)
+        clean_values = list(clean_values)
+
+        try:
+            # Compute detailed analysis
+            publishing_period_seconds = self._compute_publishing_period(clean_timestamps)
+            density_ratio = self._compute_density_ratio(
+                clean_timestamps, publishing_period_seconds or 0.0
+            )
+            decomposition = self._compute_seasonality_and_trend(
+                clean_timestamps, clean_values, density_ratio, publishing_period_seconds
+            )
+            statistics = self._compute_statistics(clean_values)
+
+            return {
+                'data_points_found': len(metric_data.values),
+                'seasonality_seconds': decomposition.seasonality.value,
+                'trend': decomposition.trend,
+                'statistics': statistics,
+                'data_quality': {
+                    'total_points': len(metric_data.values),
+                    'density_ratio': density_ratio,
+                    'publishing_period_seconds': publishing_period_seconds,
+                },
+                'message': 'Metric analysis completed successfully',
+            }
+        except Exception as e:
+            logger.error(f'Error during metric analysis: {str(e)}')
+            return {'message': 'Unable to analyze metric data'}
+
+    def _compute_seasonality_and_trend(
+        self,
+        timestamps_ms: list[int],
+        values: list[float],
+        density_ratio: Optional[float],
+        publishing_period_seconds: Optional[float],
+    ):
+        """Compute seasonality and trend using decomposition.
+
+        Returns:
+            DecompositionResult with seasonality and trend
+        """
+        if density_ratio is None or publishing_period_seconds is None:
+            return DecompositionResult(seasonality=Seasonality.NONE, trend=Trend.NONE)
+
+        try:
+            return self.decomposer.detect_seasonality_and_trend(
+                timestamps_ms, values, density_ratio, int(publishing_period_seconds)
+            )
+        except Exception as e:
+            logger.error(f'Error computing seasonality and trend: {e}')
+            raise
+
+    def _compute_publishing_period(self, timestamps_ms: list[int]) -> Optional[float]:
+        """Compute the publishing period in seconds from timestamp gaps."""
+        try:
+            gaps = [timestamps_ms[i + 1] - timestamps_ms[i] for i in range(len(timestamps_ms) - 1)]
+            gap_counts = Counter(gaps)
+
+            if not gap_counts:
+                return None
+
+            most_common_gap_ms, _ = gap_counts.most_common(1)[0]
+            return self._get_closest_cloudwatch_period(most_common_gap_ms / 1000)
+        except Exception as e:
+            logger.warning(f'Error computing publishing period: {e}')
+            return None
+
+    def _get_closest_cloudwatch_period(self, period_seconds: float) -> float:
+        """Validate and normalize period to CloudWatch valid values."""
+        valid_periods = [1, 5, 10, 30] + [
+            i * 60 for i in range(1, 3601)
+        ]  # 1min to 1hour multiples
+
+        # Find closest valid period
+        closest_period = min(valid_periods, key=lambda x: abs(x - period_seconds))
+
+        # Only return if within 10% tolerance
+        if abs(closest_period - period_seconds) / closest_period <= 0.1:
+            return closest_period
+
+        return period_seconds  # Return original if no close match
+
+    def _compute_density_ratio(
+        self, timestamps_ms: list[int], publishing_period_seconds: float
+    ) -> Optional[float]:
+        """Calculate density ratio based on perfect timeline."""
+        if (
+            not publishing_period_seconds
+            or publishing_period_seconds <= 0
+            or len(timestamps_ms) < 2
+        ):
+            return None
+
+        try:
+            start_time = timestamps_ms[0]
+            publishing_period_ms = publishing_period_seconds * 1000
+            perfect_end_time = start_time + (publishing_period_ms * (len(timestamps_ms) - 1))
+            actual_points_in_range = sum(1 for ts in timestamps_ms if ts <= perfect_end_time)
+            return actual_points_in_range / len(timestamps_ms)
+        except Exception as e:
+            logger.error(f'Error calculating density ratio: {e}', exc_info=True)
+            raise
+
+    def _compute_statistics(self, values: list[float]) -> Dict[str, Any]:
+        """Compute essential statistical measures for LLM consumption."""
+        if not values:
+            return {
+                'min': None,
+                'max': None,
+                'std_deviation': None,
+                'coefficient_of_variation': None,
+                'median': None,
+            }
+
+        try:
+            values_array = np.array(values)
+            mean_val = np.mean(values_array)
+            std_dev = np.std(values_array, ddof=0)
+            cv = std_dev / abs(mean_val) if abs(mean_val) > NUMERICAL_STABILITY_THRESHOLD else None
+
+            return {
+                'min': float(np.min(values_array)),
+                'max': float(np.max(values_array)),
+                'std_deviation': float(std_dev),
+                'coefficient_of_variation': float(cv) if cv is not None else None,
+                'median': float(np.median(values_array)),
+            }
+        except Exception as e:
+            logger.warning(f'Error computing statistics: {e}')
+            raise