cortexdb-connectors 0.2.0__py3-none-any.whl

cortexdb_connectors/insights/engine.py

@@ -0,0 +1,308 @@
+"""InsightsEngine -- periodic analysis orchestrator for CortexDB.
+
+The engine manages a collection of insight detectors, runs them on a
+configurable schedule, and maintains an in-memory store of generated
+insights that can be queried via the companion FastAPI router.
+
+Usage::
+
+    engine = InsightsEngine(
+        cortex_url="http://localhost:8080",
+        cortex_api_key="secret",
+        interval_seconds=300,
+    )
+    # One-shot analysis:
+    insights = await engine.run_once()
+
+    # Periodic background loop (runs until cancelled):
+    await engine.start()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from cortexdb_connectors.insights.detectors import (
+    BaseDetector,
+    CortexAPIClient,
+    IncidentSpikeDetector,
+    Insight,
+    InsightSeverity,
+    InsightType,
+    KnowledgeGapDetector,
+    NewDependencyDetector,
+    OwnershipGapDetector,
+    StaleRunbookDetector,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class InsightsEngine:
+    """Orchestrates periodic insight detection against CortexDB data.
+
+    Parameters
+    ----------
+    cortex_url:
+        Base URL of the CortexDB HTTP API (e.g. ``http://localhost:8080``).
+    cortex_api_key:
+        Bearer token for CortexDB authentication.
+    tenant_id:
+        CortexDB tenant identifier (default ``"default"``).
+    interval_seconds:
+        Seconds between analysis passes when running in periodic mode
+        (default 300 = 5 minutes).
+    detectors:
+        Optional list of detector instances.  If not provided, all
+        built-in detectors are registered with default settings.
+    max_insights:
+        Maximum number of insights to retain in memory (default 1000).
+        Oldest insights beyond this limit are evicted.
+    """
+
+    def __init__(
+        self,
+        cortex_url: str,
+        cortex_api_key: str,
+        tenant_id: str = "default",
+        interval_seconds: int = 300,
+        detectors: list[BaseDetector] | None = None,
+        max_insights: int = 1000,
+    ) -> None:
+        self.client = CortexAPIClient(
+            base_url=cortex_url,
+            api_key=cortex_api_key,
+            tenant_id=tenant_id,
+        )
+        self.interval_seconds = interval_seconds
+        self.max_insights = max_insights
+
+        self._detectors: list[BaseDetector] = detectors or self._default_detectors()
+        self._insights: dict[str, Insight] = {}
+        self._running = False
+        self._task: asyncio.Task[None] | None = None
+        self._last_run_at: datetime | None = None
+        self._run_count: int = 0
+
+    # -- Detector management -------------------------------------------------
+
+    @staticmethod
+    def _default_detectors() -> list[BaseDetector]:
+        """Return the full set of built-in detectors with default config."""
+        return [
+            IncidentSpikeDetector(),
+            NewDependencyDetector(),
+            KnowledgeGapDetector(),
+            OwnershipGapDetector(),
+            StaleRunbookDetector(),
+        ]
+
+    def register_detector(self, detector: BaseDetector) -> None:
+        """Add a custom detector to the engine."""
+        self._detectors.append(detector)
+
+    @property
+    def detectors(self) -> list[BaseDetector]:
+        """Return the list of registered detectors."""
+        return list(self._detectors)
+
+    # -- Insight store -------------------------------------------------------
+
+    @property
+    def insights(self) -> list[Insight]:
+        """Return all stored insights, newest first."""
+        return sorted(
+            self._insights.values(),
+            key=lambda i: i.detected_at,
+            reverse=True,
+        )
+
+    def get_insight(self, insight_id: str) -> Insight | None:
+        """Look up a single insight by id."""
+        return self._insights.get(insight_id)
+
+    def dismiss_insight(self, insight_id: str) -> Insight | None:
+        """Mark an insight as dismissed.
+
+        Returns the updated insight, or ``None`` if not found.
+        """
+        insight = self._insights.get(insight_id)
+        if insight is None:
+            return None
+        insight.dismissed = True
+        insight.dismissed_at = datetime.now(timezone.utc)
+        return insight
+
+    def query_insights(
+        self,
+        *,
+        insight_type: InsightType | None = None,
+        severity: InsightSeverity | None = None,
+        entity: str | None = None,
+        include_dismissed: bool = False,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[Insight]:
+        """Query stored insights with optional filters.
+
+        Parameters
+        ----------
+        insight_type:
+            Filter by insight type.
+        severity:
+            Filter by severity level.
+        entity:
+            Filter to insights mentioning this entity name (case-insensitive
+            substring match).
+        include_dismissed:
+            Whether to include dismissed insights (default ``False``).
+        limit:
+            Maximum number of results to return.
+        offset:
+            Number of results to skip (for pagination).
+        """
+        results = self.insights  # already sorted newest-first
+
+        if not include_dismissed:
+            results = [i for i in results if not i.dismissed]
+        if insight_type is not None:
+            results = [i for i in results if i.insight_type == insight_type]
+        if severity is not None:
+            results = [i for i in results if i.severity == severity]
+        if entity is not None:
+            entity_lower = entity.lower()
+            results = [
+                i for i in results
+                if any(entity_lower in e.lower() for e in i.entities)
+            ]
+
+        return results[offset : offset + limit]
+
+    def _store_insight(self, insight: Insight) -> None:
+        """Store an insight, merging by id and enforcing the size limit."""
+        existing = self._insights.get(insight.id)
+        if existing is not None and existing.dismissed:
+            # Do not overwrite a dismissed insight with a re-detection.
+            return
+        self._insights[insight.id] = insight
+
+        # Evict oldest non-dismissed insights beyond the cap.
+        if len(self._insights) > self.max_insights:
+            sorted_ids = sorted(
+                self._insights,
+                key=lambda k: self._insights[k].detected_at,
+            )
+            excess = len(self._insights) - self.max_insights
+            for iid in sorted_ids[:excess]:
+                if not self._insights[iid].dismissed:
+                    del self._insights[iid]
+
+    # -- Execution -----------------------------------------------------------
+
+    async def run_once(self) -> list[Insight]:
+        """Execute all detectors once and return newly generated insights.
+
+        This is safe to call from application code for on-demand analysis.
+        """
+        new_insights: list[Insight] = []
+        logger.info(
+            "InsightsEngine: starting analysis pass (%d detectors)",
+            len(self._detectors),
+        )
+
+        for detector in self._detectors:
+            detector_name = type(detector).__name__
+            try:
+                detected = await detector.detect(self.client)
+                for insight in detected:
+                    self._store_insight(insight)
+                    new_insights.append(insight)
+                logger.info(
+                    "InsightsEngine: %s produced %d insight(s)",
+                    detector_name, len(detected),
+                )
+            except Exception:
+                logger.exception(
+                    "InsightsEngine: detector %s raised an unexpected error",
+                    detector_name,
+                )
+
+        self._last_run_at = datetime.now(timezone.utc)
+        self._run_count += 1
+
+        logger.info(
+            "InsightsEngine: analysis pass complete, %d new insight(s), "
+            "%d total stored",
+            len(new_insights), len(self._insights),
+        )
+        return new_insights
+
+    async def start(self) -> None:
+        """Start the periodic analysis loop.
+
+        This method blocks until ``stop()`` is called or the task is
+        cancelled.  It is designed to be run as an ``asyncio.Task``.
+        """
+        if self._running:
+            logger.warning("InsightsEngine: already running")
+            return
+
+        self._running = True
+        logger.info(
+            "InsightsEngine: starting periodic loop (interval=%ds)",
+            self.interval_seconds,
+        )
+
+        try:
+            while self._running:
+                try:
+                    await self.run_once()
+                except Exception:
+                    logger.exception(
+                        "InsightsEngine: unhandled error in analysis loop"
+                    )
+                await asyncio.sleep(self.interval_seconds)
+        finally:
+            self._running = False
+            logger.info("InsightsEngine: periodic loop stopped")
+
+    def start_background(self) -> asyncio.Task[None]:
+        """Launch the periodic loop as a background asyncio task.
+
+        Returns the created task so the caller can cancel or await it.
+        """
+        self._task = asyncio.create_task(self.start(), name="insights-engine")
+        return self._task
+
+    async def stop(self) -> None:
+        """Stop the periodic analysis loop gracefully."""
+        self._running = False
+        if self._task is not None and not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+        logger.info("InsightsEngine: stopped")
+
+    # -- Status / health -----------------------------------------------------
+
+    def status(self) -> dict[str, Any]:
+        """Return engine status suitable for health check endpoints."""
+        return {
+            "running": self._running,
+            "interval_seconds": self.interval_seconds,
+            "detector_count": len(self._detectors),
+            "insight_count": len(self._insights),
+            "active_insight_count": sum(
+                1 for i in self._insights.values() if not i.dismissed
+            ),
+            "last_run_at": (
+                self._last_run_at.isoformat() if self._last_run_at else None
+            ),
+            "run_count": self._run_count,
+        }