ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/logic/telemetry/core.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections import defaultdict, deque
+from datetime import datetime, timedelta
+from typing import Any, Deque, Dict, Optional, Tuple
+from uuid import uuid4
+
+from ciris_engine.logic.persistence.models.correlations import add_correlation
+from ciris_engine.logic.services.base_service import BaseService
+from ciris_engine.logic.services.lifecycle.time import TimeService
+from ciris_engine.schemas.runtime.enums import ServiceType
+from ciris_engine.schemas.runtime.system_context import SystemSnapshot
+from ciris_engine.schemas.telemetry.core import (
+    CorrelationType,
+    MetricData,
+    ServiceCorrelation,
+    ServiceCorrelationStatus,
+)
+from ciris_engine.schemas.types import JSONDict
+
+from .security import SecurityFilter
+
+logger = logging.getLogger(__name__)
+
+
+class BasicTelemetryCollector(BaseService):
+    """Collects and exposes basic telemetry for agent introspection."""
+
+    def __init__(
+        self,
+        buffer_size: int = 1000,
+        security_filter: SecurityFilter | None = None,
+        time_service: TimeService | None = None,
+    ) -> None:
+        # Initialize BaseService with time_service
+        super().__init__(time_service=time_service, service_name="BasicTelemetryCollector")
+        self.buffer_size = buffer_size
+        self._history: Dict[str, Deque[Tuple[datetime, float]]] = defaultdict(lambda: deque(maxlen=self.buffer_size))
+        self._filter = security_filter or SecurityFilter()
+        # Use the time_service from BaseService instead of creating a new one
+        if not self._time_service:
+            self._time_service = TimeService()
+        self.start_time = self._time_service.now()
+        self._pending_stores: set[asyncio.Task[Any]] = set()
+        # Note: _started is now provided by BaseService
+
+    async def start(self) -> None:
+        await super().start()
+        logger.info("Telemetry service started")
+
+    async def stop(self) -> None:
+        """Stop the service and ensure all metrics are persisted."""
+        await super().stop()
+
+        if self._pending_stores:
+            logger.info(f"Waiting for {len(self._pending_stores)} pending metric storage tasks...")
+            try:
+                await asyncio.wait_for(asyncio.gather(*self._pending_stores, return_exceptions=True), timeout=30.0)
+                logger.info("All metric storage tasks completed")
+            except asyncio.TimeoutError:
+                logger.warning("Timed out waiting for metric storage - some metrics may be lost")
+
+        logger.info("Telemetry service stopped")
+
+    async def is_healthy(self) -> bool:
+        """Check if service is healthy."""
+        if len(self._pending_stores) > 100:
+            logger.warning(f"Telemetry backlog: {len(self._pending_stores)} pending tasks")
+            return False
+        return await super().is_healthy()
+
+    async def record_metric(  # NOSONAR: Async for future compatibility with async backends
+        self,
+        metric_name: str,
+        value: float = 1.0,
+        tags: Optional[Dict[str, str]] = None,
+        path_type: Optional[str] = None,  # hot, cold, critical
+        source_module: Optional[str] = None,
+    ) -> None:
+        # FAIL FAST: TimeService must be initialized
+        assert self._time_service is not None, "TimeService not initialized in BasicTelemetryCollector"
+
+        sanitized = self._filter.sanitize(metric_name, value)
+        if sanitized is None:
+            logger.debug("Metric discarded by security filter: %s", metric_name)
+            return
+        name, val = sanitized
+
+        # Enhanced metric with tags, timestamp, and hot/cold path info
+        timestamp = self._time_service.now()
+
+        # Auto-detect path type based on metric name patterns if not provided
+        if path_type is None:
+            if any(critical in name for critical in ["error", "critical", "security", "auth", "circuit_breaker"]):
+                path_type = "critical"
+            elif any(hot in name for hot in ["thought_processing", "handler_invoked", "action_selected", "dma_"]):
+                path_type = "hot"
+            elif any(cold in name for cold in ["memory_", "persistence_", "context_fetch", "service_lookup"]):
+                path_type = "cold"
+            else:
+                path_type = "normal"
+
+        metric_entry = {
+            "timestamp": timestamp,
+            "value": float(val),
+            "tags": tags or {},
+            "path_type": path_type,
+            "source_module": source_module or "unknown",
+        }
+
+        # Store both simple format for backward compatibility and enhanced format
+        self._history[name].append((timestamp, float(val)))
+
+        # Store enhanced metrics in separate history for TSDB capabilities
+        if not hasattr(self, "_enhanced_history"):
+            self._enhanced_history: Dict[str, Deque[JSONDict]] = defaultdict(lambda: deque(maxlen=self.buffer_size))
+
+        from typing import cast
+
+        self._enhanced_history[name].append(cast(JSONDict, metric_entry))
+
+        # Store metric in TSDB as correlation
+        try:
+            # Include path_type and source_module in tags instead of metadata
+            combined_tags = tags.copy() if tags else {}
+            combined_tags["path_type"] = path_type
+            combined_tags["source_module"] = source_module or "unknown"
+
+            metric_correlation = ServiceCorrelation(
+                correlation_id=str(uuid4()),
+                service_type="telemetry",
+                handler_name="telemetry_service",
+                action_type="record_metric",
+                correlation_type=CorrelationType.METRIC_DATAPOINT,
+                timestamp=timestamp,
+                metric_data=MetricData(
+                    metric_name=name, metric_value=float(val), metric_unit="count", metric_type="gauge"  # Default unit
+                ),
+                tags=combined_tags,
+                status=ServiceCorrelationStatus.COMPLETED,
+                retention_policy=self._get_retention_policy(path_type),
+                created_at=timestamp,
+                updated_at=timestamp,
+            )
+
+            # Store asynchronously without blocking metric recording
+            task = asyncio.create_task(self._store_metric_correlation(metric_correlation))
+            self._pending_stores.add(task)
+            task.add_done_callback(lambda t: self._pending_stores.discard(t))
+        except Exception as e:
+            logger.error(f"Failed to create metric correlation: {e}")
+
+    async def _store_metric_correlation(self, correlation: ServiceCorrelation) -> None:
+        """Store metric correlation in TSDB asynchronously."""
+        try:
+            add_correlation(correlation, self._time_service)
+        except Exception as e:
+            logger.error(f"Failed to store metric correlation in TSDB: {e}")
+
+    async def update_system_snapshot(self, snapshot: SystemSnapshot) -> None:
+        """Update SystemSnapshot.telemetry with recent metrics."""
+        # FAIL FAST: TimeService must be initialized
+        assert self._time_service is not None, "TimeService not initialized in BasicTelemetryCollector"
+
+        now = self._time_service.now()
+        cutoff_24h = now - timedelta(hours=24)
+        cutoff_1h = now - timedelta(hours=1)
+
+        # Create telemetry summary
+        from ciris_engine.schemas.runtime.system_context import TelemetrySummary
+
+        telemetry = TelemetrySummary(
+            window_start=cutoff_24h, window_end=now, uptime_seconds=(now - self.start_time).total_seconds()
+        )
+
+        # Count metrics for different time windows
+        for name, records in self._history.items():
+            # Filter to 24h window and clean up old records
+            filtered_records = [r for r in records if r[0] > cutoff_24h]
+            self._history[name] = deque(filtered_records, maxlen=self.buffer_size)
+
+            # Count 24h metrics
+            count_24h = len(filtered_records)
+            # Count current hour metrics
+            count_1h = len([r for r in filtered_records if r[0] > cutoff_1h])
+
+            # Update telemetry based on metric name
+            if name == "message_processed":
+                telemetry.messages_processed_24h = count_24h
+                telemetry.messages_current_hour = count_1h
+            elif name == "error":
+                telemetry.errors_24h = count_24h
+                telemetry.errors_current_hour = count_1h
+            elif name == "thought_processed":
+                telemetry.thoughts_processed_24h = count_24h
+                telemetry.thoughts_current_hour = count_1h
+            elif name == "task_completed":
+                telemetry.tasks_completed_24h = count_24h
+
+            # Track service-specific metrics
+            if name.startswith("service_"):
+                service_name = name.replace("service_", "").replace("_call", "")
+                telemetry.service_calls[service_name] = count_24h
+
+        # Calculate rates
+        if telemetry.messages_processed_24h > 0:
+            telemetry.error_rate_percent = (telemetry.errors_24h / telemetry.messages_processed_24h) * 100
+
+        # Update snapshot
+        snapshot.telemetry_summary = telemetry
+
+    def _get_retention_policy(self, path_type: Optional[str]) -> str:
+        """Determine retention policy based on path type."""
+        if path_type == "critical":
+            return "raw"  # Keep all critical metrics
+        elif path_type == "hot":
+            return "raw"  # Keep hot path metrics for performance analysis
+        elif path_type == "cold":
+            return "aggregated"  # Aggregate cold path metrics
+        else:
+            return "aggregated"  # Default to aggregated
+
+    # Required abstract methods from BaseService
+
+    def get_service_type(self) -> ServiceType:
+        """Get the service type enum value."""
+        return ServiceType.TELEMETRY
+
+    def _get_actions(self) -> list[str]:
+        """Get list of actions this service provides."""
+        return ["record_metric", "update_system_snapshot", "get_metrics"]
+
+    def _check_dependencies(self) -> bool:
+        """Check if all required dependencies are available."""
+        # TimeService is our only dependency and it's optional
+        # (we create one if not provided)
+        return True

ciris_engine/logic/telemetry/hot_cold_config.py

@@ -0,0 +1,133 @@
+"""
+Hot/Cold Path Telemetry Configuration
+
+Defines which code paths are HOT (mission-critical, high-frequency) vs COLD (background, low-frequency)
+and enforces telemetry requirements based on the ciris_mypy_toolkit analysis.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Set
+
+
+@dataclass
+class PathConfig:
+    """Configuration for a specific code path."""
+
+    path_type: str  # hot, cold, critical
+    telemetry_required: bool
+    retention_policy: str  # raw, aggregated, sampled
+    alert_threshold_ms: float  # Alert if execution exceeds this
+    sampling_rate: float = 1.0  # 1.0 = 100% sampling
+
+
+@dataclass
+class ModulePathConfig:
+    """Hot/cold path configuration for a module."""
+
+    module_name: str
+    hot_types: Set[str] = field(default_factory=set)
+    cold_types: Set[str] = field(default_factory=set)
+    critical_functions: Set[str] = field(default_factory=set)
+    telemetry_points: List[str] = field(default_factory=list)
+
+
+# Global hot/cold path configuration based on ciris_mypy_toolkit analysis
+HOT_COLD_PATH_CONFIG: Dict[str, PathConfig] = {
+    # CRITICAL PATHS - Always monitor with full telemetry
+    "audit_log": PathConfig("critical", True, "raw", 10.0),
+    "security_check": PathConfig("critical", True, "raw", 5.0),
+    "auth_verification": PathConfig("critical", True, "raw", 5.0),
+    "error_handler": PathConfig("critical", True, "raw", 20.0),
+    "circuit_breaker": PathConfig("critical", True, "raw", 1.0),
+    # HOT PATHS - Core agent processing
+    "thought_processing": PathConfig("hot", True, "raw", 100.0),
+    "action_selection": PathConfig("hot", True, "raw", 50.0),
+    "handler_invocation": PathConfig("hot", True, "raw", 200.0),
+    "dma_execution": PathConfig("hot", True, "raw", 150.0),
+    "conscience_check": PathConfig("hot", True, "raw", 30.0),
+    # WARM PATHS - Important but less frequent
+    "context_building": PathConfig("hot", True, "aggregated", 300.0, 0.5),
+    "service_lookup": PathConfig("hot", True, "aggregated", 50.0, 0.5),
+    "message_processing": PathConfig("hot", True, "aggregated", 100.0, 0.8),
+    # COLD PATHS - Background operations
+    "memory_operation": PathConfig("cold", False, "aggregated", 1000.0, 0.1),
+    "persistence_fetch": PathConfig("cold", False, "aggregated", 500.0, 0.2),
+    "context_fetch": PathConfig("cold", False, "sampled", 300.0, 0.1),
+    "telemetry_aggregation": PathConfig("cold", False, "sampled", 5000.0, 0.05),
+}
+
+# Module-specific configurations
+MODULE_CONFIGS: Dict[str, ModulePathConfig] = {
+    "ciris_engine.processor.thought_processor": ModulePathConfig(
+        module_name="thought_processor",
+        hot_types={"Thought", "ActionSelectionDMAResult", "ThoughtContext", "DMAResults"},
+        cold_types={"ConscienceResult", "EpistemicData"},
+        critical_functions={"process_thought", "_handle_special_cases"},
+        telemetry_points=["thought_processing_started", "thought_processing_completed", "action_selected"],
+    ),
+    "ciris_engine.action_handlers": ModulePathConfig(
+        module_name="action_handlers",
+        hot_types={"ActionSelectionDMAResult", "DispatchContext", "HandlerActionType"},
+        cold_types={"AuditLogEntry", "ServiceCorrelation"},
+        critical_functions={"dispatch", "handle"},
+        telemetry_points=["handler_invoked", "handler_completed", "handler_error"],
+    ),
+    "ciris_engine.services": ModulePathConfig(
+        module_name="services",
+        hot_types={"ServiceProvider", "ServiceType"},
+        cold_types={"ServiceHealth", "ServiceMetrics"},
+        critical_functions={"get_service", "register_service"},
+        telemetry_points=["service_lookup", "service_registered", "service_health_check"],
+    ),
+    "ciris_engine.dma": ModulePathConfig(
+        module_name="dma",
+        hot_types={"EthicalDMAResult", "CSDMAResult", "DSDMAResult"},
+        cold_types={"DMAMetrics", "DMAHistory"},
+        critical_functions={"evaluate", "run_dma_with_retries"},
+        telemetry_points=["dma_started", "dma_completed", "dma_failed"],
+    ),
+}
+
+
+def get_path_config(metric_name: str) -> PathConfig:
+    """Get the path configuration for a metric."""
+    # Check exact matches first
+    if metric_name in HOT_COLD_PATH_CONFIG:
+        return HOT_COLD_PATH_CONFIG[metric_name]
+
+    # Check prefixes
+    for path_name, config in HOT_COLD_PATH_CONFIG.items():
+        if metric_name.startswith(path_name):
+            return config
+
+    # Default to normal path
+    return PathConfig("normal", False, "aggregated", 1000.0, 0.1)
+
+
+def is_hot_path(module: str, type_name: str) -> bool:
+    """Check if a type in a module is on the hot path."""
+    for module_pattern, config in MODULE_CONFIGS.items():
+        if module_pattern in module:
+            return type_name in config.hot_types
+    return False
+
+
+def is_critical_function(module: str, function_name: str) -> bool:
+    """Check if a function is critical and requires telemetry."""
+    for module_pattern, config in MODULE_CONFIGS.items():
+        if module_pattern in module:
+            return function_name in config.critical_functions
+    return False
+
+
+def get_telemetry_requirements(module: str, operation: str) -> dict[str, Any]:
+    """Get telemetry requirements for a module operation."""
+    path_config = get_path_config(operation)
+
+    return {
+        "enabled": path_config.telemetry_required,
+        "path_type": path_config.path_type,
+        "retention_policy": path_config.retention_policy,
+        "sampling_rate": path_config.sampling_rate,
+        "alert_threshold_ms": path_config.alert_threshold_ms,
+    }

ciris_engine/logic/telemetry/log_collector.py

@@ -0,0 +1,190 @@
+"""
+Log Correlation Collector
+
+Captures application logs and stores them as correlations in the TSDB,
+enabling time-series queries and agent introspection of log data.
+"""
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+from uuid import uuid4
+
+from ciris_engine.logic.persistence.models.correlations import add_correlation
+from ciris_engine.protocols.services.lifecycle.time import TimeServiceProtocol
+from ciris_engine.schemas.telemetry.core import CorrelationType, ServiceCorrelation, ServiceCorrelationStatus
+
+
+class TSDBLogHandler(logging.Handler):
+    """Logging handler that stores logs as TSDB correlations."""
+
+    def __init__(self, tags: Optional[Dict[str, str]] = None, time_service: Optional[TimeServiceProtocol] = None):
+        super().__init__()
+        self.tags = tags or {}
+        self._async_loop: Optional[asyncio.AbstractEventLoop] = None
+        self._time_service = time_service
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Process log record and store as correlation."""
+        try:
+            from ciris_engine.schemas.telemetry.core import LogData
+
+            # Create LogData for the log entry
+            log_data = LogData(
+                log_level=record.levelname,
+                log_message=self.format(record),
+                logger_name=record.name,
+                module_name=record.module or "unknown",
+                function_name=record.funcName or "unknown",
+                line_number=record.lineno,
+                extra_fields={
+                    "pathname": record.pathname,
+                    "thread": str(record.thread),
+                    "process": str(record.process),
+                },
+            )
+
+            # Create the correlation with log data
+            timestamp = datetime.fromtimestamp(record.created, timezone.utc)
+            log_correlation = ServiceCorrelation(
+                correlation_id=str(uuid4()),
+                service_type="logging",
+                handler_name="log_collector",
+                action_type="log_entry",
+                correlation_type=CorrelationType.LOG_ENTRY,
+                timestamp=timestamp,
+                created_at=timestamp,
+                updated_at=timestamp,
+                log_data=log_data,
+                tags={
+                    **self.tags,
+                    "logger": record.name,
+                    "level": record.levelname,
+                    "module": record.module or "unknown",
+                },
+                status=ServiceCorrelationStatus.COMPLETED,
+                retention_policy="raw",
+            )
+
+            if self._async_loop and self._async_loop.is_running():
+                self._async_loop.create_task(self._store_log_correlation(log_correlation))
+            else:
+                if self._time_service:
+                    add_correlation(log_correlation, self._time_service)
+                else:
+                    # Skip if no time service available
+                    print("Warning: TSDBLogHandler requires time_service to store correlations")
+
+        except Exception as e:
+            print(f"Failed to store log correlation: {e}")
+
+    async def _store_log_correlation(self, correlation: ServiceCorrelation) -> None:
+        """Store log correlation asynchronously."""
+        try:
+            if self._time_service:
+                add_correlation(correlation, self._time_service)
+            else:
+                print("Warning: TSDBLogHandler requires time_service to store correlations")
+        except Exception as e:
+            print(f"Failed to store log correlation in TSDB: {e}")
+
+    def set_async_loop(self, loop: asyncio.AbstractEventLoop) -> None:
+        """Set the async event loop for asynchronous storage."""
+        self._async_loop = loop
+
+
+class LogCorrelationCollector:
+    """
+    Service that configures logging to store logs in TSDB.
+
+    This collector sets up logging handlers that capture log entries
+    and store them as correlations, enabling time-series queries.
+    """
+
+    def __init__(
+        self,
+        log_levels: Optional[List[str]] = None,
+        tags: Optional[Dict[str, str]] = None,
+        loggers: Optional[List[str]] = None,
+    ):
+        """
+        Initialize the log collector.
+
+        Args:
+            log_levels: Log levels to capture (default: WARNING and above)
+            tags: Global tags to add to all log correlations
+            loggers: Specific logger names to attach to (default: root logger)
+        """
+        self.log_levels = log_levels or ["WARNING", "ERROR", "CRITICAL"]
+        self.tags = tags or {"source": "ciris_agent"}
+        self.loggers: List[Optional[str]] = list(loggers) if loggers is not None else [None]  # None means root logger
+        self.handlers: List[TSDBLogHandler] = []
+
+    async def start(self) -> None:
+        """Start collecting logs."""
+        # Get current event loop
+        loop = asyncio.get_event_loop()
+
+        # Create handlers for each logger
+        for logger_name in self.loggers:
+            handler = TSDBLogHandler(tags=self.tags)
+            handler.set_async_loop(loop)
+
+            # Set formatter
+            formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+            handler.setFormatter(formatter)
+
+            # Set level based on configured levels
+            min_level = min(getattr(logging, level) for level in self.log_levels)
+            handler.setLevel(min_level)
+
+            # Add handler to logger
+            if logger_name is None:
+                logger = logging.getLogger()
+            else:
+                logger = logging.getLogger(logger_name)
+
+            logger.addHandler(handler)
+            self.handlers.append(handler)
+
+        logging.info("Log correlation collector started")
+
+    async def stop(self) -> None:
+        """Stop collecting logs."""
+        for i, handler in enumerate(self.handlers):
+            try:
+                logger_name = self.loggers[i] if i < len(self.loggers) else None
+                if logger_name is None:
+                    logger = logging.getLogger()
+                else:
+                    logger = logging.getLogger(logger_name)
+
+                logger.removeHandler(handler)
+                handler.close()
+            except Exception as e:
+                logging.warning(f"Error removing handler: {e}")
+
+        self.handlers.clear()
+        logging.info("Log correlation collector stopped")
+
+    def add_logger(self, logger_name: str) -> None:
+        """Add a new logger to collect from."""
+        if logger_name not in self.loggers:
+            self.loggers.append(logger_name)
+
+            # If already started, add handler now
+            if self.handlers:
+                loop = asyncio.get_event_loop()
+                handler = TSDBLogHandler(tags=self.tags)
+                handler.set_async_loop(loop)
+
+                formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+                handler.setFormatter(formatter)
+
+                min_level = min(getattr(logging, level) for level in self.log_levels)
+                handler.setLevel(min_level)
+
+                logger = logging.getLogger(logger_name)
+                logger.addHandler(handler)
+                self.handlers.append(handler)

ciris_engine/logic/telemetry/resource_monitor.py

@@ -0,0 +1,7 @@
+# This module has been moved to services/infrastructure/resource_monitor.py
+# NO BACKWARDS COMPATIBILITY - Update your imports immediately
+
+from ciris_engine.logic.services.infrastructure.resource_monitor import ResourceMonitorService as ResourceMonitor
+from ciris_engine.logic.services.infrastructure.resource_monitor import ResourceSignalBus
+
+__all__ = ["ResourceMonitor", "ResourceSignalBus"]

ciris_engine/logic/telemetry/security.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import logging
+import re
+import time
+from collections import deque
+from typing import Any, Deque, Dict, Tuple
+
+logger = logging.getLogger(__name__)
+
+EMAIL_RE = re.compile(r"[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,253}\.[A-Za-z]{2,6}", re.ASCII)
+SSN_RE = re.compile(r"\b\d{3}-\d{2}-\d{4}\b")
+PHONE_RE = re.compile(r"\b\d{3}[-.\s]?\d{3}[-.\s]?\d{4}\b")
+
+
+class SecurityFilter:
+    """Sanitize telemetry metrics to prevent sensitive data leaks."""
+
+    def __init__(
+        self,
+        bounds: Dict[str, Tuple[float, float]] | None = None,
+        rate_limits: Dict[str, Tuple[int, float]] | None = None,
+    ) -> None:
+        self.bounds = bounds or {}
+        self.rate_limits = rate_limits or {}
+        self._history: Dict[str, Deque[float]] = {name: deque() for name in self.rate_limits}
+
+    def sanitize(self, metric_name: str, value: Any) -> Tuple[str, Any] | None:
+        # Rate limiting
+        if not self._check_rate_limit(metric_name):
+            logger.debug("Metric %s rate limited", metric_name)
+            return None
+
+        if isinstance(value, str):
+            if self._contains_pii(value):
+                logger.warning("PII detected in metric %s", metric_name)
+                return None
+            if metric_name.endswith("error"):
+                value = self._sanitize_error(value)
+                return metric_name, value
+            else:
+                return None
+
+        if isinstance(value, (int, float)):
+            if not self._validate_bounds(metric_name, float(value)):
+                logger.warning("Metric %s out of bounds", metric_name)
+                return None
+            return metric_name, float(value)
+
+        return None
+
+    def _contains_pii(self, text: str) -> bool:
+        """Return True if the text contains common PII patterns."""
+        return bool(EMAIL_RE.search(text) or SSN_RE.search(text) or PHONE_RE.search(text))
+
+    def _sanitize_error(self, message: str) -> str:
+        message = re.sub(r"/[^\s]+", "[REDACTED]", message)
+        message = re.sub(r"\b0x[0-9a-fA-F]+\b", "0xXXXX", message)
+        return message[:200]
+
+    def _validate_bounds(self, name: str, value: float) -> bool:
+        if name in self.bounds:
+            low, high = self.bounds[name]
+            if value < low or value > high:
+                return False
+        return True
+
+    def _check_rate_limit(self, name: str) -> bool:
+        if name not in self.rate_limits:
+            return True
+        limit, period = self.rate_limits[name]
+        history = self._history.setdefault(name, deque())
+        now = time.monotonic()
+        while history and now - history[0] > period:
+            history.popleft()
+        if len(history) >= limit:
+            return False
+        history.append(now)
+        return True

ciris_engine/logic/utils/__init__.py

@@ -0,0 +1,18 @@
+"""Utility helpers for CIRIS Engine."""
+
+import logging
+
+from .constants import COVENANT_TEXT, ENGINE_OVERVIEW_TEMPLATE, WA_USER_IDS  # noqa:F401
+from .graphql_context_provider import GraphQLClient, GraphQLContextProvider  # noqa:F401
+from .user_utils import extract_user_nick  # noqa:F401
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "COVENANT_TEXT",
+    "ENGINE_OVERVIEW_TEMPLATE",
+    "WA_USER_IDS",
+    "GraphQLClient",
+    "GraphQLContextProvider",
+    "extract_user_nick",
+]