agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/server/app.py

@@ -0,0 +1,277 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""FastAPI application for Agent OS governance API."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, Query, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from agent_os.server.models import (
+    DetectBatchRequest,
+    DetectInjectionRequest,
+    DetectionBatchResponse,
+    DetectionResponse,
+    ErrorResponse,
+    ExecuteRequest,
+    ExecuteResponse,
+    HealthResponse,
+    MetricsResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _detection_result_to_response(result: Any) -> DetectionResponse:
+    """Convert a ``DetectionResult`` dataclass to a Pydantic response."""
+    return DetectionResponse(
+        is_injection=result.is_injection,
+        threat_level=result.threat_level.value,
+        injection_type=result.injection_type.value if result.injection_type else None,
+        confidence=result.confidence,
+        matched_patterns=list(result.matched_patterns),
+        explanation=result.explanation,
+    )
+
+
+class GovServer:
+    """High-level wrapper that owns the FastAPI app and its dependencies."""
+
+    def __init__(
+        self,
+        *,
+        title: str = "Agent OS Governance API",
+        version: str | None = None,
+    ) -> None:
+        from agent_os import __version__
+        from agent_os.health import HealthChecker
+        from agent_os.metrics import GovernanceMetrics
+        from agent_os.prompt_injection import DetectionConfig, PromptInjectionDetector
+
+        self._version = version or __version__
+        self._detector = PromptInjectionDetector(DetectionConfig(sensitivity="balanced"))
+        self._metrics = GovernanceMetrics()
+        self._health_checker = HealthChecker(version=self._version)
+        self._app = create_app(self, title=title)
+
+    @property
+    def app(self) -> FastAPI:
+        return self._app
+
+    @property
+    def detector(self) -> Any:
+        return self._detector
+
+    @property
+    def metrics(self) -> Any:
+        return self._metrics
+
+    @property
+    def health_checker(self) -> Any:
+        return self._health_checker
+
+
+def create_app(
+    server: GovServer | None = None,
+    *,
+    title: str = "Agent OS Governance API",
+) -> FastAPI:
+    """Build and return the FastAPI application with all routes."""
+    from agent_os import __version__
+
+    version = server._version if server else __version__
+
+    app = FastAPI(
+        title=title,
+        version=version,
+        description="REST API for Agent OS governance operations.",
+    )
+
+    # -- CORS middleware ----------------------------------------------------
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=os.environ.get("CORS_ALLOWED_ORIGINS", "http://localhost:3000,http://localhost:8080").split(","),
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # -- request timing middleware -----------------------------------------
+    @app.middleware("http")
+    async def _timing_middleware(request: Request, call_next: Any) -> Any:
+        start = time.perf_counter()
+        response = await call_next(request)
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        response.headers["X-Response-Time"] = f"{elapsed_ms:.2f}ms"
+        return response
+
+    # -- exception handler -------------------------------------------------
+    @app.exception_handler(Exception)
+    async def _global_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+        logger.exception("Unhandled exception: %s", exc)
+        return JSONResponse(
+            status_code=500,
+            content=ErrorResponse(
+                detail=str(exc),
+                error_code="INTERNAL_ERROR",
+            ).model_dump(),
+        )
+
+    # ======================================================================
+    # Routes
+    # ======================================================================
+
+    @app.get("/")
+    async def root() -> dict:
+        """Root info endpoint."""
+        return {
+            "name": "Agent OS Governance API",
+            "version": version,
+            "docs": "/docs",
+        }
+
+    # -- health / readiness ------------------------------------------------
+
+    @app.get("/health", response_model=HealthResponse)
+    async def health() -> HealthResponse:
+        """Health check endpoint."""
+        if server:
+            report = server.health_checker.check_health()
+            return HealthResponse(
+                status=report.status.value,
+                components={
+                    name: {
+                        "status": comp.status.value,
+                        "message": comp.message,
+                    }
+                    for name, comp in report.components.items()
+                },
+                timestamp=report.timestamp,
+            )
+        return HealthResponse(
+            status="healthy",
+            components={},
+            timestamp=datetime.now(timezone.utc).isoformat() + "Z",
+        )
+
+    @app.get("/ready")
+    async def ready() -> dict:
+        """Readiness probe."""
+        if server:
+            report = server.health_checker.check_ready()
+            if not report.is_ready():
+                raise HTTPException(status_code=503, detail="Not ready")
+        return {"ready": True}
+
+    # -- metrics -----------------------------------------------------------
+
+    @app.get("/api/v1/metrics", response_model=MetricsResponse)
+    async def get_metrics() -> MetricsResponse:
+        """Return governance metrics snapshot."""
+        if server:
+            snap = server.metrics.snapshot()
+            return MetricsResponse(
+                total_checks=snap["total_checks"],
+                violations=snap["violations"],
+                approvals=snap["approvals"],
+                blocked=snap["blocked"],
+                avg_latency_ms=snap["avg_latency_ms"],
+            )
+        return MetricsResponse()
+
+    # -- prompt injection detection ----------------------------------------
+
+    @app.post("/api/v1/detect/injection", response_model=DetectionResponse)
+    async def detect_injection(req: DetectInjectionRequest) -> DetectionResponse:
+        """Scan a single text for prompt injection."""
+        from agent_os.prompt_injection import DetectionConfig, PromptInjectionDetector
+
+        if server and req.sensitivity == server.detector._config.sensitivity:
+            detector = server.detector
+        else:
+            detector = PromptInjectionDetector(
+                DetectionConfig(sensitivity=req.sensitivity)
+            )
+
+        result = detector.detect(req.text, req.source, req.canary_tokens)
+        return _detection_result_to_response(result)
+
+    @app.post("/api/v1/detect/injection/batch", response_model=DetectionBatchResponse)
+    async def detect_injection_batch(req: DetectBatchRequest) -> DetectionBatchResponse:
+        """Scan multiple texts for prompt injection."""
+        from agent_os.prompt_injection import DetectionConfig, PromptInjectionDetector
+
+        if server and req.sensitivity == server.detector._config.sensitivity:
+            detector = server.detector
+        else:
+            detector = PromptInjectionDetector(
+                DetectionConfig(sensitivity=req.sensitivity)
+            )
+
+        inputs = [(item.get("text", ""), item.get("source", "api")) for item in req.inputs]
+        results = detector.detect_batch(inputs, req.canary_tokens)
+        responses = [_detection_result_to_response(r) for r in results]
+        injections = sum(1 for r in responses if r.is_injection)
+
+        return DetectionBatchResponse(
+            results=responses,
+            total=len(responses),
+            injections_found=injections,
+        )
+
+    # -- execute -----------------------------------------------------------
+
+    @app.post("/api/v1/execute", response_model=ExecuteResponse)
+    async def execute(req: ExecuteRequest) -> ExecuteResponse:
+        """Execute an action through the stateless kernel."""
+        from agent_os.stateless import ExecutionContext, StatelessKernel
+
+        kernel = StatelessKernel()
+        ctx = ExecutionContext(
+            agent_id=req.agent_id,
+            policies=req.policies,
+        )
+        try:
+            result = await kernel.execute(req.action, req.params, ctx)
+            return ExecuteResponse(
+                success=result.success,
+                data=result.data,
+                error=result.error,
+                signal=result.signal,
+            )
+        except Exception as exc:
+            return ExecuteResponse(
+                success=False,
+                error=str(exc),
+                signal="SIGTERM",
+            )
+
+    # -- audit -------------------------------------------------------------
+
+    @app.get("/api/v1/audit/injections")
+    async def audit_injections(limit: int = Query(default=50, ge=1, le=1000)) -> dict:
+        """Return recent injection audit log entries."""
+        records: list[dict] = []
+        if server:
+            for rec in server.detector.audit_log[-limit:]:
+                records.append({
+                    "timestamp": rec.timestamp.isoformat(),
+                    "input_hash": rec.input_hash,
+                    "source": rec.source,
+                    "is_injection": rec.result.is_injection,
+                    "threat_level": rec.result.threat_level.value,
+                    "injection_type": (
+                        rec.result.injection_type.value if rec.result.injection_type else None
+                    ),
+                    "explanation": rec.result.explanation,
+                })
+        return {"records": records, "total": len(records)}
+
+    return app

agent_os/server/models.py

@@ -0,0 +1,104 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Pydantic v2 request/response models for Agent OS Governance API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+# ---------------------------------------------------------------------------
+# Request models
+# ---------------------------------------------------------------------------
+
+class ExecuteRequest(BaseModel):
+    """Request to execute an action through the stateless kernel."""
+
+    action: str = Field(..., description="Action to execute")
+    params: dict = Field(default_factory=dict, description="Action parameters")
+    agent_id: str = Field(..., description="Unique agent identifier")
+    policies: list[str] = Field(default_factory=list, description="Policy names to enforce")
+
+
+class DetectInjectionRequest(BaseModel):
+    """Request to scan a single text for prompt injection."""
+
+    text: str = Field(..., description="Input text to screen")
+    source: str = Field(default="api", description="Source identifier")
+    canary_tokens: list[str] | None = Field(default=None, description="Canary tokens to check")
+    sensitivity: str = Field(default="balanced", description="Detection sensitivity")
+
+
+class DetectBatchRequest(BaseModel):
+    """Request to scan multiple texts for prompt injection."""
+
+    inputs: list[dict] = Field(
+        ..., description="List of dicts with 'text' and optional 'source' keys"
+    )
+    canary_tokens: list[str] | None = Field(default=None, description="Canary tokens to check")
+    sensitivity: str = Field(default="balanced", description="Detection sensitivity")
+
+
+class PolicyEvalRequest(BaseModel):
+    """Request to evaluate policies against a context."""
+
+    context: dict = Field(..., description="Execution context for policy evaluation")
+    policy_name: str | None = Field(default=None, description="Specific policy to evaluate")
+
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+class ExecuteResponse(BaseModel):
+    """Response from stateless kernel execution."""
+
+    success: bool
+    data: Any = None
+    error: str | None = None
+    signal: str | None = None
+
+
+class DetectionResponse(BaseModel):
+    """Response from prompt injection detection."""
+
+    is_injection: bool
+    threat_level: str
+    injection_type: str | None = None
+    confidence: float
+    matched_patterns: list[str] = Field(default_factory=list)
+    explanation: str = ""
+
+
+class DetectionBatchResponse(BaseModel):
+    """Response from batch prompt injection detection."""
+
+    results: list[DetectionResponse]
+    total: int
+    injections_found: int
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+
+    status: str
+    components: dict = Field(default_factory=dict)
+    timestamp: str = ""
+
+
+class MetricsResponse(BaseModel):
+    """Governance metrics snapshot."""
+
+    total_checks: int = 0
+    violations: int = 0
+    approvals: int = 0
+    blocked: int = 0
+    avg_latency_ms: float = 0.0
+
+
+class ErrorResponse(BaseModel):
+    """Error response for failed requests."""
+
+    detail: str
+    error_code: str = "INTERNAL_ERROR"

agent_os/shift_left_metrics.py

@@ -0,0 +1,130 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Shift-left compliance metrics.
+
+Tracks where policy violations are caught in the development lifecycle
+and computes a shift-left score: the earlier violations are detected,
+the higher the score.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+
+class ViolationStage(str, Enum):
+    """Stage in the development lifecycle where a violation was caught."""
+
+    PRE_COMMIT = "pre_commit"      # IDE / local hooks
+    PR_CHECK = "pr_check"          # Pull-request checks
+    CI_GATE = "ci_gate"            # CI/CD pipeline gates
+    RUNTIME = "runtime"            # Production / agent runtime
+
+
+# Weights: earlier stages earn a higher shift-left contribution.
+_STAGE_WEIGHTS: dict[ViolationStage, float] = {
+    ViolationStage.PRE_COMMIT: 1.0,
+    ViolationStage.PR_CHECK: 0.75,
+    ViolationStage.CI_GATE: 0.5,
+    ViolationStage.RUNTIME: 0.0,
+}
+
+
+@dataclass
+class ViolationRecord:
+    """A single recorded policy violation."""
+
+    rule_name: str
+    stage: ViolationStage
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    resolved: bool = False
+    message: str = ""
+
+
+class ShiftLeftTracker:
+    """Tracks violation records and computes shift-left metrics."""
+
+    def __init__(self) -> None:
+        self._records: list[ViolationRecord] = []
+
+    def record(
+        self,
+        rule_name: str,
+        stage: ViolationStage,
+        *,
+        resolved: bool = False,
+        message: str = "",
+    ) -> ViolationRecord:
+        """Record a new violation and return the record."""
+        rec = ViolationRecord(
+            rule_name=rule_name,
+            stage=stage,
+            resolved=resolved,
+            message=message,
+        )
+        self._records.append(rec)
+        return rec
+
+    @property
+    def records(self) -> list[ViolationRecord]:
+        return list(self._records)
+
+    # ------------------------------------------------------------------
+    # Stage distribution
+    # ------------------------------------------------------------------
+
+    def stage_distribution(self) -> dict[str, int]:
+        """Return counts of violations per stage."""
+        dist: dict[str, int] = {s.value: 0 for s in ViolationStage}
+        for rec in self._records:
+            dist[rec.stage.value] += 1
+        return dist
+
+    # ------------------------------------------------------------------
+    # Shift-left score
+    # ------------------------------------------------------------------
+
+    def shift_left_score(self) -> float:
+        """Compute the shift-left score (0.0 - 1.0).
+
+        A score of 1.0 means every violation was caught at *pre_commit*.
+        A score of 0.0 means every violation was only caught at *runtime*
+        (or no violations were recorded).
+        """
+        if not self._records:
+            return 0.0
+        total_weight = sum(
+            _STAGE_WEIGHTS[rec.stage] for rec in self._records
+        )
+        return total_weight / len(self._records)
+
+    # ------------------------------------------------------------------
+    # Trend report
+    # ------------------------------------------------------------------
+
+    def trend_report(self) -> dict[str, Any]:
+        """Generate a summary trend report."""
+        total = len(self._records)
+        resolved = sum(1 for r in self._records if r.resolved)
+        return {
+            "total_violations": total,
+            "resolved": resolved,
+            "unresolved": total - resolved,
+            "shift_left_score": round(self.shift_left_score(), 3),
+            "stage_distribution": self.stage_distribution(),
+            "resolution_rate": round(resolved / total, 3) if total else 0.0,
+        }
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def violations_for_rule(self, rule_name: str) -> list[ViolationRecord]:
+        """Return all violation records for a given rule name."""
+        return [r for r in self._records if r.rule_name == rule_name]
+
+    def clear(self) -> None:
+        """Remove all recorded violations."""
+        self._records.clear()