cortexdb-connectors 0.2.0__py3-none-any.whl

cortexdb_connectors/insights/detectors.py

@@ -0,0 +1,771 @@
+"""Insight detectors for CortexDB proactive analysis.
+
+Each detector implements a single analysis pattern, querying the CortexDB
+HTTP API for episodes and entities, then returning zero or more ``Insight``
+objects when a noteworthy pattern is found.
+
+Detectors are stateless -- all persistence is handled by the
+``InsightsEngine`` that orchestrates them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import uuid
+from abc import ABC, abstractmethod
+from collections import Counter, defaultdict
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+class InsightSeverity(str, Enum):
+    """Severity levels for generated insights."""
+
+    INFO = "info"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+class InsightType(str, Enum):
+    """Canonical insight types produced by the built-in detectors."""
+
+    INCIDENT_SPIKE = "incident_spike"
+    NEW_DEPENDENCY = "new_dependency"
+    KNOWLEDGE_GAP = "knowledge_gap"
+    STALE_RUNBOOK = "stale_runbook"
+    OWNERSHIP_GAP = "ownership_gap"
+
+
+class Insight(BaseModel):
+    """A single actionable insight generated by a detector."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    insight_type: InsightType
+    title: str
+    description: str
+    severity: InsightSeverity
+    entities: list[str] = Field(default_factory=list)
+    detected_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc)
+    )
+    confidence: float = Field(ge=0.0, le=1.0, default=1.0)
+    dismissed: bool = False
+    dismissed_at: datetime | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def stable_id(self, *parts: str) -> str:
+        """Derive a deterministic id from content so duplicates can be detected.
+
+        Useful for detectors that want to avoid re-creating the same insight
+        on every analysis pass.
+        """
+        raw = "|".join(parts)
+        return hashlib.sha256(raw.encode()).hexdigest()[:24]
+
+
+# ---------------------------------------------------------------------------
+# CortexDB API client helper
+# ---------------------------------------------------------------------------
+
+class CortexAPIClient:
+    """Thin async wrapper around the CortexDB HTTP API used by detectors.
+
+    Handles authentication headers and pagination.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        tenant_id: str = "default",
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.tenant_id = tenant_id
+        self.timeout = timeout
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "X-Tenant-Id": self.tenant_id,
+            "Content-Type": "application/json",
+        }
+
+    async def get_episodes(
+        self,
+        *,
+        source: str | None = None,
+        episode_type: str | None = None,
+        limit: int = 500,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        """Fetch episodes from ``GET /v1/episodes``.
+
+        Returns the raw JSON list. Paginates automatically when more
+        results are available and *limit* has not been reached.
+        """
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if source:
+            params["source"] = source
+        if episode_type:
+            params["episode_type"] = episode_type
+
+        all_episodes: list[dict[str, Any]] = []
+        remaining = limit
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            while remaining > 0:
+                params["limit"] = min(remaining, 500)
+                resp = await client.get(
+                    f"{self.base_url}/v1/episodes",
+                    params=params,
+                    headers=self._headers(),
+                )
+                resp.raise_for_status()
+                batch = resp.json()
+
+                # The API may return a list directly or wrap in {"episodes": [...]}.
+                items: list[dict[str, Any]]
+                if isinstance(batch, list):
+                    items = batch
+                elif isinstance(batch, dict) and "episodes" in batch:
+                    items = batch["episodes"]
+                else:
+                    items = []
+
+                if not items:
+                    break
+
+                all_episodes.extend(items)
+                remaining -= len(items)
+                params["offset"] = params.get("offset", 0) + len(items)
+
+                # If the API returned fewer than requested, we're done.
+                if len(items) < params["limit"]:
+                    break
+
+        return all_episodes
+
+    async def get_entities(
+        self,
+        *,
+        limit: int = 1000,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        """Fetch entities from ``GET /v1/entities``."""
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.get(
+                f"{self.base_url}/v1/entities",
+                params=params,
+                headers=self._headers(),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+
+        if isinstance(data, list):
+            return data
+        if isinstance(data, dict) and "entities" in data:
+            return data["entities"]
+        return []
+
+    async def get_entity_edges(
+        self, entity_id: str
+    ) -> list[dict[str, Any]]:
+        """Fetch edges for a single entity from ``GET /v1/entities/{id}/edges``."""
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.get(
+                f"{self.base_url}/v1/entities/{entity_id}/edges",
+                headers=self._headers(),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+
+        if isinstance(data, list):
+            return data
+        if isinstance(data, dict) and "edges" in data:
+            return data["edges"]
+        return []
+
+
+# ---------------------------------------------------------------------------
+# Abstract detector
+# ---------------------------------------------------------------------------
+
+class BaseDetector(ABC):
+    """Base class for all insight detectors.
+
+    Subclasses implement ``detect`` which queries CortexDB data via the
+    provided ``CortexAPIClient`` and returns a list of ``Insight`` objects.
+    """
+
+    @abstractmethod
+    async def detect(self, client: CortexAPIClient) -> list[Insight]:
+        """Run the detector and return any discovered insights."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Concrete detectors
+# ---------------------------------------------------------------------------
+
+class IncidentSpikeDetector(BaseDetector):
+    """Detect unusual increases in incident-type episodes within a time window.
+
+    Compares the incident count in the recent window to a longer baseline
+    window.  If the recent rate exceeds the baseline by more than
+    ``spike_threshold`` standard deviations, a spike insight is emitted.
+
+    Parameters
+    ----------
+    recent_window_hours:
+        Length of the recent window to inspect (default 4 hours).
+    baseline_window_hours:
+        Length of the historical baseline window (default 168 hours / 7 days).
+    spike_threshold:
+        Multiplier over the baseline average that constitutes a spike
+        (default 2.0x).
+    """
+
+    def __init__(
+        self,
+        recent_window_hours: int = 4,
+        baseline_window_hours: int = 168,
+        spike_threshold: float = 2.0,
+    ) -> None:
+        self.recent_window_hours = recent_window_hours
+        self.baseline_window_hours = baseline_window_hours
+        self.spike_threshold = spike_threshold
+
+    async def detect(self, client: CortexAPIClient) -> list[Insight]:
+        """Fetch incident episodes and check for a spike."""
+        insights: list[Insight] = []
+        now = datetime.now(timezone.utc)
+        recent_start = now - timedelta(hours=self.recent_window_hours)
+        baseline_start = now - timedelta(hours=self.baseline_window_hours)
+
+        try:
+            episodes = await client.get_episodes(
+                episode_type="incident", limit=5000
+            )
+        except httpx.HTTPError as exc:
+            logger.warning("IncidentSpikeDetector: failed to fetch episodes: %s", exc)
+            return insights
+
+        # Bucket episodes by hour.
+        baseline_hourly: Counter[int] = Counter()
+        recent_count = 0
+
+        for ep in episodes:
+            occurred_at_raw = ep.get("occurred_at")
+            if not occurred_at_raw:
+                continue
+
+            try:
+                ts = datetime.fromisoformat(occurred_at_raw.replace("Z", "+00:00"))
+            except (ValueError, TypeError):
+                continue
+
+            if ts < baseline_start:
+                continue
+
+            hour_key = int((ts - baseline_start).total_seconds() // 3600)
+            baseline_hourly[hour_key] += 1
+
+            if ts >= recent_start:
+                recent_count += 1
+
+        if not baseline_hourly:
+            return insights
+
+        # Compute baseline average hourly rate (excluding the recent window).
+        baseline_hours = max(
+            self.baseline_window_hours - self.recent_window_hours, 1
+        )
+        baseline_total = sum(
+            count for key, count in baseline_hourly.items()
+            if key < (self.baseline_window_hours - self.recent_window_hours)
+        )
+        avg_hourly = baseline_total / baseline_hours
+        recent_rate = recent_count / max(self.recent_window_hours, 1)
+
+        if avg_hourly == 0 and recent_count > 0:
+            # No baseline incidents but we have recent ones -- definite spike.
+            severity = InsightSeverity.CRITICAL
+            confidence = 0.9
+        elif avg_hourly > 0 and recent_rate > avg_hourly * self.spike_threshold:
+            ratio = recent_rate / avg_hourly
+            if ratio > self.spike_threshold * 2:
+                severity = InsightSeverity.CRITICAL
+                confidence = min(0.95, 0.7 + (ratio - self.spike_threshold) * 0.05)
+            else:
+                severity = InsightSeverity.WARNING
+                confidence = min(0.9, 0.6 + (ratio - self.spike_threshold) * 0.1)
+        else:
+            return insights
+
+        # Collect entity names mentioned in recent incidents.
+        entity_names: list[str] = []
+        for ep in episodes:
+            occurred_raw = ep.get("occurred_at", "")
+            try:
+                ts = datetime.fromisoformat(occurred_raw.replace("Z", "+00:00"))
+            except (ValueError, TypeError):
+                continue
+            if ts >= recent_start:
+                for ent in ep.get("entities", []):
+                    name = ent.get("display_name") or ent.get("entity_id", "")
+                    if name and name not in entity_names:
+                        entity_names.append(name)
+
+        insight = Insight(
+            insight_type=InsightType.INCIDENT_SPIKE,
+            title=f"Incident spike: {recent_count} incidents in last {self.recent_window_hours}h",
+            description=(
+                f"Detected {recent_count} incidents in the last "
+                f"{self.recent_window_hours} hours, compared to a baseline "
+                f"average of {avg_hourly:.1f}/hour over the past "
+                f"{self.baseline_window_hours} hours. "
+                f"This is {recent_rate / max(avg_hourly, 0.01):.1f}x the "
+                f"normal rate."
+            ),
+            severity=severity,
+            entities=entity_names[:20],
+            confidence=round(confidence, 2),
+            metadata={
+                "recent_count": recent_count,
+                "baseline_avg_hourly": round(avg_hourly, 3),
+                "recent_rate_hourly": round(recent_rate, 3),
+                "recent_window_hours": self.recent_window_hours,
+                "baseline_window_hours": self.baseline_window_hours,
+            },
+        )
+        insight.id = insight.stable_id("incident_spike", str(now.date()))
+        insights.append(insight)
+        return insights
+
+
+class NewDependencyDetector(BaseDetector):
+    """Detect newly discovered service dependencies from entity edges.
+
+    Scans all entities of type ``service`` and inspects their edges.
+    Edges with relationship types like ``DependsOn``, ``CallsTo``, or
+    ``ConsumesFrom`` that were created within the lookback window are
+    flagged as new dependencies.
+
+    Parameters
+    ----------
+    lookback_hours:
+        How far back to look for new edges (default 24 hours).
+    dependency_edge_types:
+        Edge relationship types that represent dependencies.
+    """
+
+    DEFAULT_DEPENDENCY_EDGES = frozenset({
+        "DependsOn", "CallsTo", "ConsumesFrom", "Imports", "Requires",
+    })
+
+    def __init__(
+        self,
+        lookback_hours: int = 24,
+        dependency_edge_types: frozenset[str] | None = None,
+    ) -> None:
+        self.lookback_hours = lookback_hours
+        self.dependency_edge_types = (
+            dependency_edge_types or self.DEFAULT_DEPENDENCY_EDGES
+        )
+
+    async def detect(self, client: CortexAPIClient) -> list[Insight]:
+        """Scan service entities for new dependency edges."""
+        insights: list[Insight] = []
+        now = datetime.now(timezone.utc)
+        cutoff = now - timedelta(hours=self.lookback_hours)
+
+        try:
+            entities = await client.get_entities(limit=2000)
+        except httpx.HTTPError as exc:
+            logger.warning("NewDependencyDetector: failed to fetch entities: %s", exc)
+            return insights
+
+        service_entities = [
+            e for e in entities
+            if (e.get("entity_type") or "").lower() == "service"
+        ]
+
+        for entity in service_entities:
+            entity_id = entity.get("id") or entity.get("entity_id", "")
+            entity_name = (
+                entity.get("display_name")
+                or entity.get("name")
+                or entity_id
+            )
+
+            try:
+                edges = await client.get_entity_edges(entity_id)
+            except httpx.HTTPError as exc:
+                logger.debug(
+                    "NewDependencyDetector: failed to fetch edges for %s: %s",
+                    entity_id, exc,
+                )
+                continue
+
+            for edge in edges:
+                rel_type = edge.get("relationship_type") or edge.get("type", "")
+                if rel_type not in self.dependency_edge_types:
+                    continue
+
+                created_raw = (
+                    edge.get("created_at")
+                    or edge.get("discovered_at")
+                    or ""
+                )
+                if not created_raw:
+                    continue
+
+                try:
+                    created_at = datetime.fromisoformat(
+                        created_raw.replace("Z", "+00:00")
+                    )
+                except (ValueError, TypeError):
+                    continue
+
+                if created_at < cutoff:
+                    continue
+
+                target_name = (
+                    edge.get("target_name")
+                    or edge.get("target_display_name")
+                    or edge.get("target_id", "unknown")
+                )
+
+                insight = Insight(
+                    insight_type=InsightType.NEW_DEPENDENCY,
+                    title=f"New dependency: {entity_name} -> {target_name}",
+                    description=(
+                        f"A new '{rel_type}' relationship was discovered "
+                        f"between '{entity_name}' and '{target_name}' "
+                        f"at {created_at.isoformat()}. Review this dependency "
+                        f"to ensure it is expected and documented."
+                    ),
+                    severity=InsightSeverity.INFO,
+                    entities=[entity_name, target_name],
+                    confidence=0.85,
+                    metadata={
+                        "source_entity_id": entity_id,
+                        "target_id": edge.get("target_id", ""),
+                        "relationship_type": rel_type,
+                        "created_at": created_raw,
+                    },
+                )
+                insight.id = insight.stable_id(
+                    "new_dep", entity_id, edge.get("target_id", ""), rel_type
+                )
+                insights.append(insight)
+
+        return insights
+
+
+class KnowledgeGapDetector(BaseDetector):
+    """Detect entities with high mention count but no documentation episodes.
+
+    An entity that appears frequently across episodes but has zero
+    associated ``document`` episodes likely represents a knowledge gap
+    that should be addressed.
+
+    Parameters
+    ----------
+    min_mention_count:
+        Minimum number of episode mentions before an entity is considered
+        "high mention" (default 5).
+    """
+
+    def __init__(self, min_mention_count: int = 5) -> None:
+        self.min_mention_count = min_mention_count
+
+    async def detect(self, client: CortexAPIClient) -> list[Insight]:
+        """Cross-reference entity mention counts against document episodes."""
+        insights: list[Insight] = []
+
+        try:
+            all_episodes = await client.get_episodes(limit=5000)
+            doc_episodes = await client.get_episodes(
+                episode_type="document", limit=5000
+            )
+        except httpx.HTTPError as exc:
+            logger.warning("KnowledgeGapDetector: failed to fetch data: %s", exc)
+            return insights
+
+        # Count mentions per entity across all episodes.
+        mention_counts: Counter[str] = Counter()
+        entity_display: dict[str, str] = {}
+
+        for ep in all_episodes:
+            for ent in ep.get("entities", []):
+                eid = ent.get("entity_id", "")
+                if not eid:
+                    continue
+                mention_counts[eid] += 1
+                name = ent.get("display_name") or eid
+                entity_display[eid] = name
+
+        # Collect entity ids that appear in documentation episodes.
+        documented_entities: set[str] = set()
+        for ep in doc_episodes:
+            for ent in ep.get("entities", []):
+                eid = ent.get("entity_id", "")
+                if eid:
+                    documented_entities.add(eid)
+
+        # Flag high-mention entities with no documentation.
+        for eid, count in mention_counts.most_common():
+            if count < self.min_mention_count:
+                break
+            if eid in documented_entities:
+                continue
+
+            name = entity_display.get(eid, eid)
+            severity = (
+                InsightSeverity.WARNING if count >= self.min_mention_count * 3
+                else InsightSeverity.INFO
+            )
+            confidence = min(0.95, 0.5 + (count / 100))
+
+            insight = Insight(
+                insight_type=InsightType.KNOWLEDGE_GAP,
+                title=f"Knowledge gap: '{name}' has {count} mentions but no docs",
+                description=(
+                    f"Entity '{name}' (id: {eid}) is referenced in {count} "
+                    f"episodes but has no associated documentation episodes. "
+                    f"Consider creating documentation to capture institutional "
+                    f"knowledge about this entity."
+                ),
+                severity=severity,
+                entities=[name],
+                confidence=round(confidence, 2),
+                metadata={
+                    "entity_id": eid,
+                    "mention_count": count,
+                    "min_threshold": self.min_mention_count,
+                },
+            )
+            insight.id = insight.stable_id("knowledge_gap", eid)
+            insights.append(insight)
+
+        return insights
+
+
+class StaleRunbookDetector(BaseDetector):
+    """Detect documents not updated relative to service change frequency.
+
+    If a service has had recent code changes or incidents but its
+    associated documentation episodes are significantly older, the
+    documentation is likely stale.
+
+    Parameters
+    ----------
+    stale_threshold_days:
+        Number of days after which a document is considered stale if the
+        service has had recent activity (default 30).
+    activity_lookback_days:
+        How far back to look for recent service activity (default 14).
+    """
+
+    def __init__(
+        self,
+        stale_threshold_days: int = 30,
+        activity_lookback_days: int = 14,
+    ) -> None:
+        self.stale_threshold_days = stale_threshold_days
+        self.activity_lookback_days = activity_lookback_days
+
+    async def detect(self, client: CortexAPIClient) -> list[Insight]:
+        """Compare document freshness against service activity."""
+        insights: list[Insight] = []
+        now = datetime.now(timezone.utc)
+        stale_cutoff = now - timedelta(days=self.stale_threshold_days)
+        activity_cutoff = now - timedelta(days=self.activity_lookback_days)
+
+        try:
+            all_episodes = await client.get_episodes(limit=5000)
+        except httpx.HTTPError as exc:
+            logger.warning("StaleRunbookDetector: failed to fetch episodes: %s", exc)
+            return insights
+
+        # Group episodes by entity, separating docs from activity.
+        entity_docs: dict[str, datetime] = {}  # entity_id -> latest doc timestamp
+        entity_activity: dict[str, list[datetime]] = defaultdict(list)
+        entity_display: dict[str, str] = {}
+        activity_types = {"code_change", "incident", "deployment", "alert"}
+
+        for ep in all_episodes:
+            ep_type = ep.get("episode_type", "")
+            occurred_raw = ep.get("occurred_at", "")
+            try:
+                ts = datetime.fromisoformat(occurred_raw.replace("Z", "+00:00"))
+            except (ValueError, TypeError):
+                continue
+
+            for ent in ep.get("entities", []):
+                eid = ent.get("entity_id", "")
+                if not eid:
+                    continue
+                entity_display[eid] = ent.get("display_name") or eid
+
+                if ep_type == "document":
+                    existing = entity_docs.get(eid)
+                    if existing is None or ts > existing:
+                        entity_docs[eid] = ts
+                elif ep_type in activity_types:
+                    entity_activity[eid].append(ts)
+
+        # Find entities with recent activity but stale docs.
+        for eid, activity_times in entity_activity.items():
+            recent_activity = [t for t in activity_times if t >= activity_cutoff]
+            if not recent_activity:
+                continue
+
+            latest_doc = entity_docs.get(eid)
+            if latest_doc is None:
+                # No docs at all -- this is more of a knowledge gap; skip.
+                continue
+
+            if latest_doc >= stale_cutoff:
+                # Doc is fresh enough.
+                continue
+
+            name = entity_display.get(eid, eid)
+            days_since_doc = (now - latest_doc).days
+            recent_count = len(recent_activity)
+
+            severity = (
+                InsightSeverity.WARNING if days_since_doc > self.stale_threshold_days * 2
+                else InsightSeverity.INFO
+            )
+            confidence = min(0.9, 0.5 + recent_count * 0.05 + days_since_doc * 0.002)
+
+            insight = Insight(
+                insight_type=InsightType.STALE_RUNBOOK,
+                title=f"Stale runbook: '{name}' docs are {days_since_doc}d old",
+                description=(
+                    f"Entity '{name}' has documentation last updated "
+                    f"{days_since_doc} days ago, but has had {recent_count} "
+                    f"activity episodes (code changes, incidents, deployments) "
+                    f"in the last {self.activity_lookback_days} days. "
+                    f"The documentation may be outdated."
+                ),
+                severity=severity,
+                entities=[name],
+                confidence=round(confidence, 2),
+                metadata={
+                    "entity_id": eid,
+                    "days_since_doc_update": days_since_doc,
+                    "recent_activity_count": recent_count,
+                    "latest_doc_date": latest_doc.isoformat(),
+                },
+            )
+            insight.id = insight.stable_id("stale_runbook", eid)
+            insights.append(insight)
+
+        return insights
+
+
+class OwnershipGapDetector(BaseDetector):
+    """Detect services with no clear owner (no WorksOn/Owns edges).
+
+    Iterates over service entities and checks for ownership-indicating
+    edges.  Services without any such edges are flagged.
+
+    Parameters
+    ----------
+    ownership_edge_types:
+        Edge relationship types that indicate ownership.
+    """
+
+    DEFAULT_OWNERSHIP_EDGES = frozenset({
+        "WorksOn", "Owns", "Maintains", "OwnedBy", "MaintainedBy",
+    })
+
+    def __init__(
+        self,
+        ownership_edge_types: frozenset[str] | None = None,
+    ) -> None:
+        self.ownership_edge_types = (
+            ownership_edge_types or self.DEFAULT_OWNERSHIP_EDGES
+        )
+
+    async def detect(self, client: CortexAPIClient) -> list[Insight]:
+        """Check service entities for ownership edges."""
+        insights: list[Insight] = []
+
+        try:
+            entities = await client.get_entities(limit=2000)
+        except httpx.HTTPError as exc:
+            logger.warning("OwnershipGapDetector: failed to fetch entities: %s", exc)
+            return insights
+
+        service_entities = [
+            e for e in entities
+            if (e.get("entity_type") or "").lower() == "service"
+        ]
+
+        for entity in service_entities:
+            entity_id = entity.get("id") or entity.get("entity_id", "")
+            entity_name = (
+                entity.get("display_name")
+                or entity.get("name")
+                or entity_id
+            )
+
+            try:
+                edges = await client.get_entity_edges(entity_id)
+            except httpx.HTTPError as exc:
+                logger.debug(
+                    "OwnershipGapDetector: failed to fetch edges for %s: %s",
+                    entity_id, exc,
+                )
+                continue
+
+            has_owner = any(
+                (edge.get("relationship_type") or edge.get("type", ""))
+                in self.ownership_edge_types
+                for edge in edges
+            )
+
+            if has_owner:
+                continue
+
+            insight = Insight(
+                insight_type=InsightType.OWNERSHIP_GAP,
+                title=f"Ownership gap: '{entity_name}' has no assigned owner",
+                description=(
+                    f"Service '{entity_name}' (id: {entity_id}) has no "
+                    f"ownership edges ({', '.join(sorted(self.ownership_edge_types))}). "
+                    f"Unowned services risk slower incident response and "
+                    f"unclear accountability."
+                ),
+                severity=InsightSeverity.WARNING,
+                entities=[entity_name],
+                confidence=0.9,
+                metadata={
+                    "entity_id": entity_id,
+                    "edge_count": len(edges),
+                    "checked_edge_types": sorted(self.ownership_edge_types),
+                },
+            )
+            insight.id = insight.stable_id("ownership_gap", entity_id)
+            insights.append(insight)
+
+        return insights