cortexdb-connectors 0.2.0__py3-none-any.whl

cortexdb_connectors/insights/api.py

@@ -0,0 +1,252 @@
+"""FastAPI router exposing the Insights Engine via HTTP endpoints.
+
+Mount this router into an existing FastAPI application::
+
+    from fastapi import FastAPI
+    from cortexdb_connectors.insights.api import create_insights_router
+    from cortexdb_connectors.insights.engine import InsightsEngine
+
+    engine = InsightsEngine(cortex_url="...", cortex_api_key="...")
+    app = FastAPI()
+    app.include_router(create_insights_router(engine))
+
+Endpoints
+---------
+GET  /v1/insights            List insights with optional filters.
+GET  /v1/insights/{id}       Retrieve a single insight by id.
+POST /v1/insights/{id}/dismiss  Dismiss an insight.
+GET  /v1/insights/status     Engine health / status.
+POST /v1/insights/run        Trigger an on-demand analysis pass.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel, Field
+
+from cortexdb_connectors.insights.detectors import (
+    Insight,
+    InsightSeverity,
+    InsightType,
+)
+from cortexdb_connectors.insights.engine import InsightsEngine
+
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+class InsightResponse(BaseModel):
+    """Single insight in API responses."""
+
+    id: str
+    insight_type: InsightType
+    title: str
+    description: str
+    severity: InsightSeverity
+    entities: list[str]
+    detected_at: datetime
+    confidence: float
+    dismissed: bool
+    dismissed_at: datetime | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class InsightListResponse(BaseModel):
+    """Paginated list of insights."""
+
+    insights: list[InsightResponse]
+    total: int
+    limit: int
+    offset: int
+
+
+class DismissResponse(BaseModel):
+    """Response after dismissing an insight."""
+
+    id: str
+    dismissed: bool
+    dismissed_at: datetime | None
+
+
+class StatusResponse(BaseModel):
+    """Engine status response."""
+
+    running: bool
+    interval_seconds: int
+    detector_count: int
+    insight_count: int
+    active_insight_count: int
+    last_run_at: str | None
+    run_count: int
+
+
+class RunResponse(BaseModel):
+    """Response from triggering an on-demand analysis pass."""
+
+    new_insights: int
+    total_insights: int
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _insight_to_response(insight: Insight) -> InsightResponse:
+    """Convert an internal Insight model to an API response model."""
+    return InsightResponse(
+        id=insight.id,
+        insight_type=insight.insight_type,
+        title=insight.title,
+        description=insight.description,
+        severity=insight.severity,
+        entities=insight.entities,
+        detected_at=insight.detected_at,
+        confidence=insight.confidence,
+        dismissed=insight.dismissed,
+        dismissed_at=insight.dismissed_at,
+        metadata=insight.metadata,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Router factory
+# ---------------------------------------------------------------------------
+
+def create_insights_router(engine: InsightsEngine) -> APIRouter:
+    """Create a FastAPI router wired to the given ``InsightsEngine``.
+
+    Parameters
+    ----------
+    engine:
+        A configured InsightsEngine instance whose in-memory insight
+        store will be served through the API.
+
+    Returns
+    -------
+    APIRouter
+        A router with prefix ``/v1/insights`` ready to be mounted on a
+        FastAPI application.
+    """
+    router = APIRouter(prefix="/v1/insights", tags=["insights"])
+
+    @router.get(
+        "",
+        response_model=InsightListResponse,
+        summary="List insights",
+        description=(
+            "Return insights with optional filters for type, severity, "
+            "entity, and pagination."
+        ),
+    )
+    async def list_insights(
+        type: InsightType | None = Query(
+            None,
+            description="Filter by insight type",
+            alias="type",
+        ),
+        severity: InsightSeverity | None = Query(
+            None, description="Filter by severity level"
+        ),
+        entity: str | None = Query(
+            None,
+            description=(
+                "Filter to insights mentioning this entity "
+                "(case-insensitive substring match)"
+            ),
+        ),
+        include_dismissed: bool = Query(
+            False, description="Include dismissed insights"
+        ),
+        limit: int = Query(50, ge=1, le=500, description="Max results"),
+        offset: int = Query(0, ge=0, description="Pagination offset"),
+    ) -> InsightListResponse:
+        """List insights with optional filters."""
+        # Get unfiltered count for the total (with same filters minus pagination).
+        all_matching = engine.query_insights(
+            insight_type=type,
+            severity=severity,
+            entity=entity,
+            include_dismissed=include_dismissed,
+            limit=engine.max_insights,
+            offset=0,
+        )
+        total = len(all_matching)
+
+        page = engine.query_insights(
+            insight_type=type,
+            severity=severity,
+            entity=entity,
+            include_dismissed=include_dismissed,
+            limit=limit,
+            offset=offset,
+        )
+
+        return InsightListResponse(
+            insights=[_insight_to_response(i) for i in page],
+            total=total,
+            limit=limit,
+            offset=offset,
+        )
+
+    @router.get(
+        "/status",
+        response_model=StatusResponse,
+        summary="Engine status",
+        description="Return the current status of the insights engine.",
+    )
+    async def get_status() -> StatusResponse:
+        """Return engine health information."""
+        return StatusResponse(**engine.status())
+
+    @router.get(
+        "/{insight_id}",
+        response_model=InsightResponse,
+        summary="Get single insight",
+        description="Retrieve a single insight by its id.",
+    )
+    async def get_insight(insight_id: str) -> InsightResponse:
+        """Retrieve a single insight by id."""
+        insight = engine.get_insight(insight_id)
+        if insight is None:
+            raise HTTPException(status_code=404, detail="Insight not found")
+        return _insight_to_response(insight)
+
+    @router.post(
+        "/{insight_id}/dismiss",
+        response_model=DismissResponse,
+        summary="Dismiss an insight",
+        description=(
+            "Mark an insight as dismissed. Dismissed insights will not "
+            "reappear in default list queries."
+        ),
+    )
+    async def dismiss_insight(insight_id: str) -> DismissResponse:
+        """Dismiss an insight so it no longer surfaces in default queries."""
+        insight = engine.dismiss_insight(insight_id)
+        if insight is None:
+            raise HTTPException(status_code=404, detail="Insight not found")
+        return DismissResponse(
+            id=insight.id,
+            dismissed=insight.dismissed,
+            dismissed_at=insight.dismissed_at,
+        )
+
+    @router.post(
+        "/run",
+        response_model=RunResponse,
+        summary="Trigger analysis",
+        description="Run all detectors immediately and return a summary.",
+    )
+    async def trigger_run() -> RunResponse:
+        """Trigger an on-demand analysis pass."""
+        new_insights = await engine.run_once()
+        return RunResponse(
+            new_insights=len(new_insights),
+            total_insights=len(engine._insights),
+        )
+
+    return router