driftshield-sdk 0.2.0__tar.gz

driftshield_sdk-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.env
+.venv/
+venv/
+*.db
+*.sqlite
+.coverage
+htmlcov/

driftshield_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: driftshield-sdk
+Version: 0.2.0
+Summary: Open-source AI decision forensics toolkit
+Project-URL: Homepage, https://github.com/tborys/driftshield
+Project-URL: Changelog, https://github.com/tborys/driftshield/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/tborys/driftshield/blob/main/docs/public-api.md
+Project-URL: Issues, https://github.com/tborys/driftshield/issues
+Author: Tomasz Borys, Devinder Pharar
+License-Expression: AGPL-3.0-or-later
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: alembic>=1.13.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: psycopg2-binary>=2.9.9
+Requires-Dist: pydantic-settings>=2.14.2
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: python-multipart>=0.0.31
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# driftshield
+
+Find where an AI agent first went wrong.
+
+DriftShield reconstructs a failed agent run as a decision graph, shows where
+reasoning first drifted and matches the failure against known community
+signatures. It reads Claude Code, Codex CLI, Claude Desktop, Codex Desktop,
+OpenClaw, CrewAI and LangChain transcripts.
+
+```bash
+pip install driftshield-sdk
+driftshield analyze session.jsonl
+```
+
+The distribution is called `driftshield-sdk` on PyPI because the name
+`driftshield` was already too close to an unrelated project. The import
+package and the command are still `driftshield`.
+
+The library surface is two calls:
+
+```python
+from driftshield import analyse_run, submit
+
+run = analyse_run(open("session.jsonl", "rb").read(), source="session.jsonl")
+print(run.qualification_state, run.findings)
+
+receipt = submit(run)  # community lane: redacted, no key needed
+```
+
+`analyse_run` works offline and touches nothing outside the process. `submit`
+is the only call that sends anything off the machine, and it only ever sends
+`run.redacted_transcript`.
+
+Documentation, the self hosted web UI and the full CLI reference live in the
+repository: https://github.com/tborys/driftshield
+
+Licensed under AGPL-3.0-or-later.

driftshield_sdk-0.2.0/README.md

@@ -0,0 +1,37 @@
+# driftshield
+
+Find where an AI agent first went wrong.
+
+DriftShield reconstructs a failed agent run as a decision graph, shows where
+reasoning first drifted and matches the failure against known community
+signatures. It reads Claude Code, Codex CLI, Claude Desktop, Codex Desktop,
+OpenClaw, CrewAI and LangChain transcripts.
+
+```bash
+pip install driftshield-sdk
+driftshield analyze session.jsonl
+```
+
+The distribution is called `driftshield-sdk` on PyPI because the name
+`driftshield` was already too close to an unrelated project. The import
+package and the command are still `driftshield`.
+
+The library surface is two calls:
+
+```python
+from driftshield import analyse_run, submit
+
+run = analyse_run(open("session.jsonl", "rb").read(), source="session.jsonl")
+print(run.qualification_state, run.findings)
+
+receipt = submit(run)  # community lane: redacted, no key needed
+```
+
+`analyse_run` works offline and touches nothing outside the process. `submit`
+is the only call that sends anything off the machine, and it only ever sends
+`run.redacted_transcript`.
+
+Documentation, the self hosted web UI and the full CLI reference live in the
+repository: https://github.com/tborys/driftshield
+
+Licensed under AGPL-3.0-or-later.

driftshield_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,110 @@
+[project]
+name = "driftshield-sdk"
+version = "0.2.0"
+description = "Open-source AI decision forensics toolkit"
+authors = [
+    { name = "Tomasz Borys" },
+    { name = "Devinder Pharar" },
+]
+readme = "README.md"
+license = "AGPL-3.0-or-later"
+requires-python = ">=3.12"
+classifiers = [
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "fastapi>=0.109.0",
+    "uvicorn[standard]>=0.27.0",
+    "sqlalchemy>=2.0.0",
+    "alembic>=1.13.0",
+    "psycopg2-binary>=2.9.9",
+    "pydantic>=2.5.0",
+    "pydantic-settings>=2.14.2",
+    "python-multipart>=0.0.31",
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "jinja2>=3.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/tborys/driftshield"
+Changelog = "https://github.com/tborys/driftshield/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/tborys/driftshield/blob/main/docs/public-api.md"
+Issues = "https://github.com/tborys/driftshield/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "pytest-asyncio>=0.23.0",
+    "httpx>=0.27.0",
+    "ruff>=0.1.0",
+    "mypy>=1.8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/driftshield"]
+include = [
+    "src/driftshield/signatures/packs/*.json",
+]
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "README.md",
+    "src/driftshield",
+    "tests",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[project.scripts]
+driftshield = "driftshield.cli.main:app"
+driftshield-api = "driftshield.api.server:main"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
+[[tool.mypy.overrides]]
+module = [
+    "driftshield.api.ingest_workflow",
+    "driftshield.api.routes.health",
+    "driftshield.api.routes.ingest",
+    "driftshield.api.security",
+    "driftshield.cli.commands.connectors",
+    "driftshield.cli.commands.ingest",
+    "driftshield.cli.commands.list",
+    "driftshield.cli.commands.report",
+    "driftshield.connectors.watcher",
+    "driftshield.core.analysis.heuristics",
+    "driftshield.core.analysis.risk",
+    "driftshield.core.analysis.session",
+    "driftshield.core.graph.models",
+    "driftshield.core.models",
+    "driftshield.db.ingest_service",
+    "driftshield.db.migrations.versions.9b3d7e1a4c2f_remove_recurrence_tables_from_oss",
+    "driftshield.db.models",
+    "driftshield.db.validation_service",
+    "driftshield.fixtures.transcript_generator",
+    "driftshield.parsers.claude_code",
+    "driftshield.parsers.crewai",
+    "driftshield.parsers.langchain",
+    "driftshield.parsers.local_chat",
+    "driftshield.parsers.openclaw",
+    "driftshield.signatures.community",
+    "tests.fixtures.scenarios",
+]
+ignore_errors = true

driftshield_sdk-0.2.0/src/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_sdk-0.2.0/src/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_sdk-0.2.0/src/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_sdk-0.2.0/src/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_sdk-0.2.0/src/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_sdk-0.2.0/src/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,
+    )