driftshield-sdk 0.2.0__py3-none-any.whl

driftshield/__init__.py

@@ -0,0 +1,31 @@
+"""DriftShield - AI Decision Forensics.
+
+The public API is exactly two operations, ``analyse_run`` and ``submit``, with
+their result and error types. Everything else in the package is internal.
+"""
+
+from driftshield.public import (
+    AnalysedRun,
+    Finding,
+    NoParseableEventsError,
+    SignatureHit,
+    SubmitError,
+    SubmitReceipt,
+    UnsupportedFormatError,
+    analyse_run,
+    submit,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AnalysedRun",
+    "Finding",
+    "NoParseableEventsError",
+    "SignatureHit",
+    "SubmitError",
+    "SubmitReceipt",
+    "UnsupportedFormatError",
+    "analyse_run",
+    "submit",
+]

driftshield/api/app.py

@@ -0,0 +1,47 @@
+import os
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from driftshield import __version__
+from driftshield.api.routes.behaviour import router as behaviour_router
+from driftshield.api.routes.connectors import router as connectors_router
+from driftshield.api.routes.health import router as health_router
+from driftshield.api.routes.ingest import router as ingest_router
+from driftshield.api.routes.reports import router as reports_router
+from driftshield.api.routes.sessions import router as sessions_router
+from driftshield.api.security import RequestSizeLimitMiddleware
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="DriftShield",
+        description="AI Decision Forensics API",
+        version=__version__,
+    )
+    app.add_middleware(RequestSizeLimitMiddleware)
+    app.include_router(behaviour_router)
+    app.include_router(connectors_router)
+    app.include_router(health_router)
+    app.include_router(ingest_router)
+    app.include_router(sessions_router)
+    app.include_router(reports_router)
+
+    # Serve React static files in production
+    # When installed as a package, __file__ points to site-packages.
+    # Use STATIC_DIR env var (set in Docker) or fall back to relative path for local dev.
+    static_dir = Path(os.environ.get("STATIC_DIR", Path(__file__).parent.parent.parent.parent / "static"))
+    if static_dir.exists():
+        app.mount("/assets", StaticFiles(directory=str(static_dir / "assets")), name="assets")
+
+        @app.get("/{path:path}")
+        async def serve_spa(path: str) -> FileResponse:
+            """Serve React SPA. All non-API routes fall through to index.html."""
+            file_path = static_dir / path
+            if file_path.exists() and file_path.is_file():
+                return FileResponse(str(file_path))
+            return FileResponse(str(static_dir / "index.html"))
+
+    return app

driftshield/api/auth.py

@@ -0,0 +1,13 @@
+from fastapi import HTTPException, Security
+from fastapi.security import APIKeyHeader
+
+from driftshield.api.security import get_expected_api_key
+
+api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+
+def require_api_key(api_key: str | None = Security(api_key_header)) -> str:
+    expected = get_expected_api_key()
+    if not api_key or api_key != expected:
+        raise HTTPException(status_code=401, detail="Missing or invalid API key")
+    return api_key

driftshield/api/dependencies.py

@@ -0,0 +1,24 @@
+from collections.abc import Generator
+
+from sqlalchemy.orm import Session as DBSession
+
+from driftshield.db.engine import get_engine, get_session_factory
+
+_engine = None
+_session_factory = None
+
+
+def get_db() -> Generator[DBSession, None, None]:
+    global _engine, _session_factory
+    if _engine is None:
+        _engine = get_engine()
+        _session_factory = get_session_factory(_engine)
+    session = _session_factory()
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()

driftshield/api/ingest_workflow.py

@@ -0,0 +1,102 @@
+from fastapi import HTTPException, UploadFile
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session as DBSession
+
+from driftshield.api.security import get_max_request_bytes
+from driftshield.core.analysis.session import AnalysisResult
+from driftshield.db.behaviour_service import BehaviourEventService
+from driftshield.db.ingest_service import TranscriptIngestService, metrics_payload_from_analysis_result
+from driftshield.db.persistence import IngestOutcome, PersistenceService
+from driftshield.public import analyse_run
+from driftshield.telemetry import TelemetryService
+
+
+def ingest_transcript_bytes(
+    db: DBSession,
+    *,
+    raw_bytes: bytes,
+    format_name: str,
+    filename: str | None,
+    commit: bool = True,
+) -> tuple[IngestOutcome, AnalysisResult | None, str]:
+    _validate_request_size(raw_bytes)
+    try:
+        run = analyse_run(
+            raw_bytes,
+            source=filename,
+            format=None if format_name == "auto" else format_name,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    normalised = run.detected_format
+
+    ingest_service = TranscriptIngestService(db)
+    try:
+        outcome, analysis_result = ingest_service.ingest_run(run)
+        if not outcome.deduplicated and analysis_result is not None and analysis_result.events:
+            BehaviourEventService(db).link_new_run_after_pattern_view(session_id=outcome.session_id)
+        if commit:
+            db.commit()
+            if not outcome.deduplicated and analysis_result is not None:
+                record_analysis_telemetry(analysis_result)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except IntegrityError:
+        db.rollback()
+        outcome = PersistenceService(db).get_ingest_outcome(run.provenance)
+        if outcome is None:
+            raise
+        analysis_result = None
+    except HTTPException:
+        db.rollback()
+        raise
+    except Exception as exc:
+        db.rollback()
+        raise HTTPException(
+            status_code=422,
+            detail=f"Failed to process transcript: {exc}",
+        ) from exc
+
+    return outcome, analysis_result, normalised
+
+
+def read_upload_bytes(
+    file: UploadFile,
+    *,
+    chunk_size: int = 1024 * 1024,
+) -> bytes:
+    max_request_bytes = get_max_request_bytes()
+    total_bytes = 0
+    chunks: list[bytes] = []
+
+    while True:
+        chunk = file.file.read(chunk_size)
+        if not chunk:
+            break
+
+        total_bytes += len(chunk)
+        if total_bytes > max_request_bytes:
+            raise HTTPException(status_code=413, detail=f"Request body exceeds {max_request_bytes} bytes")
+        chunks.append(chunk)
+
+    return b"".join(chunks)
+
+
+def record_analysis_telemetry(result: AnalysisResult) -> None:
+    metrics = metrics_payload_from_analysis_result(result)
+    try:
+        TelemetryService().record_analysis_event(
+            outcome_status=metrics["outcome_status"],
+            match_count=metrics["match_count"],
+            primary_mechanism_id=metrics["primary_family_id"],
+            mixed_mechanism=metrics["mixed_family"],
+            not_classifiable_reason=metrics["not_classifiable_reason"],
+        )
+    except Exception:
+        pass
+
+
+def _validate_request_size(raw_bytes: bytes) -> None:
+    max_request_bytes = get_max_request_bytes()
+    if len(raw_bytes) > max_request_bytes:
+        raise HTTPException(status_code=413, detail=f"Request body exceeds {max_request_bytes} bytes")

driftshield/api/routes/behaviour.py

@@ -0,0 +1,160 @@
+import uuid
+from typing import Literal, cast
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session as DBSession
+
+from driftshield.api.auth import require_api_key
+from driftshield.api.dependencies import get_db
+from driftshield.api.schemas import (
+    BehaviourEventCreateRequest,
+    BehaviourEventResponse,
+    BehaviourSubjectCreateRequest,
+    BehaviourSubjectResponse,
+)
+from driftshield.db.behaviour_service import BehaviourEventService, BehaviourSubjectSnapshot
+from driftshield.db.models import SessionModel
+
+router = APIRouter()
+
+SubjectType = Literal["trusted_pattern", "report", "linked_run_set"]
+SurfaceType = Literal["api", "ui", "report"]
+EventType = Literal[
+    "pattern_viewed",
+    "pattern_expanded",
+    "pattern_revisited",
+    "pattern_linked_runs_viewed",
+    "new_run_after_pattern_view",
+]
+
+_ALLOWED_SUBJECT_TYPES = {"trusted_pattern", "report", "linked_run_set"}
+_ALLOWED_SURFACES = {"api", "ui", "report"}
+_ALLOWED_EVENT_TYPES = {
+    "pattern_viewed",
+    "pattern_expanded",
+    "pattern_revisited",
+    "pattern_linked_runs_viewed",
+    "new_run_after_pattern_view",
+}
+
+
+@router.post("/api/behaviour/subjects", response_model=BehaviourSubjectResponse, status_code=201)
+def create_behaviour_subject(
+    payload: BehaviourSubjectCreateRequest,
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> BehaviourSubjectResponse:
+    del api_key
+    _validate_subject_payload(payload)
+    _require_session_exists(db, payload.session_id, detail="Behaviour subject session not found")
+
+    service = BehaviourEventService(db)
+    subject = service.create_subject(
+        subject_type=cast(SubjectType, payload.subject_type),
+        pattern_reference=payload.pattern_reference,
+        trust_band=payload.trust_band,
+        surface=cast(SurfaceType, payload.surface),
+        session_id=payload.session_id,
+        first_exposed_at=payload.first_exposed_at,
+        metadata_json=payload.metadata_json,
+    )
+    snapshot = service.get_subject_snapshot(subject.id)
+    assert snapshot is not None
+    db.commit()
+    return _subject_response(snapshot)
+
+
+@router.get("/api/behaviour/subjects/{subject_id}", response_model=BehaviourSubjectResponse)
+def get_behaviour_subject(
+    subject_id: uuid.UUID,
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> BehaviourSubjectResponse:
+    del api_key
+    snapshot = BehaviourEventService(db).get_subject_snapshot(subject_id)
+    if snapshot is None:
+        raise HTTPException(status_code=404, detail="Behaviour subject not found")
+    return _subject_response(snapshot)
+
+
+@router.post("/api/behaviour/events", response_model=BehaviourEventResponse, status_code=201)
+def create_behaviour_event(
+    payload: BehaviourEventCreateRequest,
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> BehaviourEventResponse:
+    del api_key
+    if payload.event_type not in _ALLOWED_EVENT_TYPES:
+        raise HTTPException(status_code=422, detail="Unsupported behaviour event type")
+    _require_session_exists(
+        db,
+        payload.linked_session_id,
+        detail="Linked behaviour event session not found",
+    )
+
+    service = BehaviourEventService(db)
+    try:
+        event = service.record_event(
+            subject_id=payload.subject_id,
+            event_type=cast(EventType, payload.event_type),
+            actor_id=payload.actor_id,
+            originating_session_id=payload.originating_session_id,
+            linked_session_id=payload.linked_session_id,
+            occurred_at=payload.occurred_at,
+            metadata_json=payload.metadata_json,
+        )
+    except LookupError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+    db.commit()
+    return BehaviourEventResponse(
+        id=event.id,
+        subject_id=event.subject_id,
+        occurred_at=event.occurred_at,
+        event_type=event.event_type,
+        actor_id=event.actor_id,
+        originating_session_id=event.originating_session_id,
+        linked_session_id=event.linked_session_id,
+        metadata_json=event.metadata_json or {},
+    )
+
+
+def _validate_subject_payload(payload: BehaviourSubjectCreateRequest) -> None:
+    if payload.subject_type not in _ALLOWED_SUBJECT_TYPES:
+        raise HTTPException(status_code=422, detail="Unsupported behaviour subject type")
+    if payload.surface not in _ALLOWED_SURFACES:
+        raise HTTPException(status_code=422, detail="Unsupported behaviour surface")
+    if payload.subject_type != "trusted_pattern" and payload.trust_band == "trusted":
+        raise HTTPException(
+            status_code=422,
+            detail="Only trusted_pattern subjects can be marked trusted in OSS v1",
+        )
+
+
+def _require_session_exists(
+    db: DBSession,
+    session_id: uuid.UUID | None,
+    *,
+    detail: str,
+) -> None:
+    if session_id is None:
+        return
+    if db.get(SessionModel, session_id) is None:
+        raise HTTPException(status_code=404, detail=detail)
+
+
+def _subject_response(snapshot: BehaviourSubjectSnapshot) -> BehaviourSubjectResponse:
+    subject = snapshot.subject
+    return BehaviourSubjectResponse(
+        id=subject.id,
+        session_id=subject.session_id,
+        subject_type=subject.subject_type,
+        pattern_reference=subject.pattern_reference,
+        trust_band=subject.trust_band,
+        surface=subject.surface,
+        first_exposed_at=subject.first_exposed_at,
+        metadata_json=subject.metadata_json or {},
+        tracking_status=snapshot.tracking_status,
+        follow_up_status=snapshot.follow_up_status,
+        event_counts=snapshot.event_counts,
+    )

driftshield/api/routes/connectors.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import os
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session as DBSession
+
+from driftshield.api.auth import require_api_key
+from driftshield.api.dependencies import get_db
+from driftshield.api.schemas import (
+    ConnectorApproveRequest,
+    ConnectorDiscoverRequest,
+    ConnectorListResponse,
+    ConnectorResponse,
+    ConnectorScanResponse,
+)
+from driftshield.db.connector_service import ConnectorService
+from driftshield.db.models import ConnectorModel
+
+router = APIRouter()
+
+
+def _claude_home_from_env() -> Path | None:
+    value = os.environ.get("CLAUDE_HOME")
+    return Path(value).expanduser() if value else None
+
+
+def _ensure_utc(value: datetime | None) -> datetime | None:
+    if value is None:
+        return None
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+def _connector_response(connector: ConnectorModel) -> ConnectorResponse:
+    return ConnectorResponse(
+        id=connector.id,
+        source_type=connector.source_type,
+        display_name=connector.display_name,
+        root_path=connector.root_path,
+        parser_name=connector.parser_name,
+        consent_state=connector.consent_state,
+        status=connector.status,
+        watchable=connector.watchable,
+        metadata=connector.metadata_json or {},
+        watch_status=connector.watch_status,
+        last_scanned_at=_ensure_utc(connector.last_scanned_at),
+        last_watch_heartbeat_at=_ensure_utc(connector.last_watch_heartbeat_at),
+        last_ingested_at=_ensure_utc(connector.last_ingested_at),
+        last_seen_activity_at=_ensure_utc(connector.last_seen_activity_at),
+        last_error=connector.last_error,
+        last_error_at=_ensure_utc(connector.last_error_at),
+    )
+
+
+@router.get("/api/connectors", response_model=ConnectorListResponse)
+def list_connectors(
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> ConnectorListResponse:
+    del api_key
+    service = ConnectorService(db)
+    return ConnectorListResponse(
+        items=[_connector_response(connector) for connector in service.list_connectors()]
+    )
+
+
+@router.post("/api/connectors/discover", response_model=ConnectorListResponse)
+def discover_connectors(
+    payload: ConnectorDiscoverRequest,
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> ConnectorListResponse:
+    del api_key
+    service = ConnectorService(db)
+    project_dir = Path(payload.project_dir).expanduser().resolve() if payload.project_dir else Path.cwd()
+    connectors = service.refresh_candidates(
+        project_dir=project_dir,
+        claude_home=_claude_home_from_env(),
+    )
+    db.commit()
+    return ConnectorListResponse(items=[_connector_response(connector) for connector in connectors])
+
+
+@router.get("/api/connectors/{connector_id}", response_model=ConnectorResponse)
+def get_connector(
+    connector_id: uuid.UUID,
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> ConnectorResponse:
+    del api_key
+    service = ConnectorService(db)
+    connector = service.get_connector(connector_id)
+    if connector is None:
+        raise HTTPException(status_code=404, detail="Connector not found")
+    return _connector_response(connector)
+
+
+@router.post("/api/connectors/{connector_id}/approve", response_model=ConnectorResponse)
+def approve_connector(
+    connector_id: uuid.UUID,
+    payload: ConnectorApproveRequest,
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> ConnectorResponse:
+    del api_key
+    service = ConnectorService(db)
+    try:
+        connector = service.approve_connector(connector_id, mode=payload.mode)
+    except LookupError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    db.commit()
+    return _connector_response(connector)
+
+
+@router.post("/api/connectors/{connector_id}/deny", response_model=ConnectorResponse)
+def deny_connector(
+    connector_id: uuid.UUID,
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> ConnectorResponse:
+    del api_key
+    service = ConnectorService(db)
+    try:
+        connector = service.deny_connector(connector_id)
+    except LookupError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    db.commit()
+    return _connector_response(connector)
+
+
+@router.post("/api/connectors/{connector_id}/pause", response_model=ConnectorResponse)
+def pause_connector(
+    connector_id: uuid.UUID,
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> ConnectorResponse:
+    del api_key
+    service = ConnectorService(db)
+    try:
+        connector = service.pause_connector(connector_id)
+    except LookupError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    db.commit()
+    return _connector_response(connector)
+
+
+@router.post("/api/connectors/{connector_id}/resume", response_model=ConnectorResponse)
+def resume_connector(
+    connector_id: uuid.UUID,
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> ConnectorResponse:
+    del api_key
+    service = ConnectorService(db)
+    try:
+        connector = service.resume_connector(connector_id)
+    except LookupError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    db.commit()
+    return _connector_response(connector)
+
+
+@router.post("/api/connectors/{connector_id}/disconnect", response_model=ConnectorResponse)
+def disconnect_connector(
+    connector_id: uuid.UUID,
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> ConnectorResponse:
+    del api_key
+    service = ConnectorService(db)
+    try:
+        connector = service.disconnect_connector(connector_id)
+    except LookupError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    db.commit()
+    return _connector_response(connector)
+
+
+@router.post("/api/connectors/{connector_id}/rescan", response_model=ConnectorScanResponse)
+def rescan_connector(
+    connector_id: uuid.UUID,
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+) -> ConnectorScanResponse:
+    del api_key
+    service = ConnectorService(db)
+    try:
+        scan = service.rescan_connector(connector_id)
+    except LookupError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    db.commit()
+    return ConnectorScanResponse(
+        connector_id=uuid.UUID(scan.connector_id),
+        session_count=scan.session_count,
+        newest_session_id=scan.newest_session_id,
+        newest_session_path=scan.newest_session_path,
+        newest_modified_at=_ensure_utc(scan.newest_modified_at),
+    )

driftshield/api/routes/health.py

@@ -0,0 +1,13 @@
+from fastapi import APIRouter
+
+from driftshield import __version__
+
+router = APIRouter()
+
+
+@router.get("/api/health")
+def health_check():
+    return {
+        "status": "ok",
+        "version": __version__,
+    }

driftshield/api/routes/ingest.py

@@ -0,0 +1,39 @@
+from fastapi import APIRouter, Depends, File, Form, Response, UploadFile
+from sqlalchemy.orm import Session as DBSession
+
+from driftshield.api.auth import require_api_key
+from driftshield.api.dependencies import get_db
+from driftshield.api.ingest_workflow import ingest_transcript_bytes, read_upload_bytes
+from driftshield.api.schemas import IngestResponse
+
+router = APIRouter()
+
+
+@router.post("/api/ingest", response_model=IngestResponse, status_code=201)
+def ingest_transcript(
+    response: Response,
+    file: UploadFile = File(...),
+    format: str = Form(default="auto"),
+    api_key: str = Depends(require_api_key),
+    db: DBSession = Depends(get_db),
+):
+    del api_key
+    raw_bytes = read_upload_bytes(file)
+    outcome, _, _ = ingest_transcript_bytes(
+        db,
+        raw_bytes=raw_bytes,
+        format_name=format,
+        filename=file.filename,
+    )
+
+    if outcome.deduplicated:
+        response.status_code = 200
+
+    return IngestResponse(
+        session_id=outcome.session_id,
+        total_events=outcome.total_events,
+        flagged_events=outcome.flagged_events,
+        has_inflection=outcome.has_inflection,
+        status=outcome.status,
+        deduplicated=outcome.deduplicated,
+    )