fact0-sdk 1.0.0__py3-none-any.whl

auditlog/__init__.py

@@ -0,0 +1,17 @@
+"""Deprecated auditlog package - re-exports from fact0."""
+
+from __future__ import annotations
+
+import warnings
+
+from .client import (AuditLogError, Client, Transport, TransportError,
+                     ValidationError)
+
+warnings.warn(
+    "The auditlog package is deprecated; use `pip install fact0-sdk` and `import fact0`.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = ["Client", "Transport", "TransportError", "ValidationError", "AuditLogError"]
+__all__ = ["Client", "Transport", "TransportError", "ValidationError", "AuditLogError"]

auditlog/client.py

@@ -0,0 +1,53 @@
+"""Deprecated auditlog.Client - thin wrapper around fact0.audit.client."""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+from fact0._http import SyncHTTP, env_base_url
+from fact0.audit.client import AuditClient
+from fact0.exceptions import AuditLogError, TransportError, ValidationError
+
+warnings.warn(
+    "The auditlog package is deprecated; use `pip install fact0-sdk` and `import fact0`.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+
+class Client:
+    """Back-compat audit-only client (api_key + base_url constructor)."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        sync: bool = False,
+        transport: Any | None = None,
+        **audit_kwargs: Any,
+    ):
+        resolved_base = (base_url or env_base_url()).rstrip("/")
+        if transport is not None and isinstance(transport, SyncHTTP):
+            http = transport
+        else:
+            http = SyncHTTP(resolved_base, api_key, sync_ingest=sync)
+            if transport is not None:
+                audit_kwargs.setdefault("transport", transport)
+        self._audit = AuditClient(http, **audit_kwargs)
+
+    def log(self, **kwargs: Any) -> None:
+        self._audit.log(**kwargs)
+
+    def flush(self) -> None:
+        self._audit.flush()
+
+    def close(self) -> None:
+        self._audit.close()
+
+
+# Legacy alias: auditlog.Transport was SyncHTTP with positional url/key args.
+Transport = SyncHTTP
+
+__all__ = ["Client", "Transport", "TransportError", "ValidationError", "AuditLogError"]

fact0/__init__.py

@@ -0,0 +1,101 @@
+"""Fact0 Python SDK - audit log and execution telemetry."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ._http import SyncHTTP, env_api_key, env_base_url
+from .audit.async_client import AsyncAuditClient
+from .audit.client import AuditClient
+from .audit.models import Actor, ActorType, Outcome, Resource
+from .audit.transport import AuditTransport
+from .exceptions import (
+    AuditLogError,
+    Fact0Error,
+    TransportError,
+    ValidationError,
+)
+from .telemetry.client import TelemetryClient
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "AuditClient",
+    "AsyncAuditClient",
+    "TelemetryClient",
+    "Actor",
+    "Resource",
+    "Outcome",
+    "ActorType",
+    "Fact0Error",
+    "AuditLogError",
+    "ValidationError",
+    "TransportError",
+    "__version__",
+]
+
+
+class Client:
+    """Unified Fact0 client with audit and telemetry modules."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        sync: bool = False,
+        **audit_kwargs,
+    ):
+        resolved_key = api_key or env_api_key() or ""
+        resolved_base = (base_url or env_base_url()).rstrip("/")
+        custom_transport = audit_kwargs.pop("transport", None)
+        if custom_transport is not None and isinstance(custom_transport, SyncHTTP):
+            http = custom_transport
+        else:
+            http = SyncHTTP(resolved_base, resolved_key or None, sync_ingest=sync)
+            if custom_transport is not None:
+                audit_kwargs["transport"] = custom_transport
+        self._http = http
+        self.audit = AuditClient(http, **audit_kwargs)
+        self.telemetry = TelemetryClient(http)
+
+    def close(self) -> None:
+        self.audit.close()
+
+    def log(self, **kwargs) -> None:
+        self.audit.log(**kwargs)
+
+    def flush(self) -> None:
+        self.audit.flush()
+
+
+class AsyncClient:
+    """Async Fact0 client."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        sync: bool = False,
+    ):
+        resolved_key = api_key or env_api_key() or ""
+        if not resolved_key:
+            raise ValueError("api_key is required for AsyncClient audit operations")
+        resolved_base = (base_url or env_base_url()).rstrip("/")
+        self.audit = AsyncAuditClient(resolved_base, resolved_key, sync=sync)
+        self._base_url = resolved_base
+        self.telemetry = TelemetryClient(
+            SyncHTTP(resolved_base, resolved_key, sync_ingest=sync)
+        )
+
+    async def close(self) -> None:
+        await self.audit.close()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()

fact0/_http.py

@@ -0,0 +1,125 @@
+"""Shared HTTP utilities with retries and auth."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any, Mapping
+
+import requests
+
+from .exceptions import TransportError
+
+_log = logging.getLogger("fact0")
+
+_RETRYABLE = {429, 500, 502, 503, 504}
+DEFAULT_TIMEOUT_S = 30.0
+USER_AGENT = "fact0-python/1.0.0"
+
+
+def env_base_url(default: str = "https://api.fact0.io") -> str:
+    return (
+        os.environ.get("FACT0_BASE_URL")
+        or os.environ.get("FACT0_BASE_URL")
+        or default
+    ).rstrip("/")
+
+
+def env_api_key() -> str | None:
+    return (
+        os.environ.get("FACT0_API_KEY")
+        or os.environ.get("FACT0_API_KEY")
+        or os.environ.get("AUDITLOG_API_KEY")
+    )
+
+
+class SyncHTTP:
+    """Synchronous HTTP client with bounded retries."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None = None,
+        *,
+        timeout_s: float = DEFAULT_TIMEOUT_S,
+        max_retries: int = 3,
+        backoff_base_s: float = 0.2,
+        sync_ingest: bool = False,
+        session: requests.Session | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout_s = timeout_s
+        self.max_retries = max_retries
+        self.backoff_base_s = backoff_base_s
+        self.sync_ingest = sync_ingest
+        self.session = session or requests.Session()
+
+    def _headers(self, *, auth: bool = True, sync: bool | None = None) -> dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        if auth and self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        use_sync = self.sync_ingest if sync is None else sync
+        if use_sync:
+            headers["X-Fact0-Sync"] = "true"
+        return headers
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+        auth: bool = True,
+        sync: bool | None = None,
+        expect_json: bool = True,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        last_err: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = self.session.request(
+                    method,
+                    url,
+                    json=json_body,
+                    params=params,
+                    headers=self._headers(auth=auth, sync=sync),
+                    timeout=self.timeout_s,
+                )
+            except requests.RequestException as exc:
+                last_err = exc
+                _log.warning("network error (attempt %d): %s", attempt + 1, exc)
+            else:
+                retry_after = resp.headers.get("Retry-After")
+                if resp.status_code < 300:
+                    if not expect_json:
+                        return resp.content
+                    try:
+                        return resp.json()
+                    except ValueError:
+                        return {}
+                if resp.status_code not in _RETRYABLE:
+                    raise TransportError(
+                        f"{method} {path} returned {resp.status_code}: {resp.text[:200]}",
+                        status_code=resp.status_code,
+                    )
+                last_err = TransportError(
+                    f"{method} {path} returned {resp.status_code}",
+                    status_code=resp.status_code,
+                )
+                if retry_after:
+                    try:
+                        time.sleep(float(retry_after))
+                        continue
+                    except ValueError:
+                        pass
+
+            if attempt < self.max_retries:
+                time.sleep(self.backoff_base_s * (2**attempt))
+
+        raise TransportError(f"giving up after {self.max_retries + 1} attempts: {last_err}")

fact0/audit/async_client.py

@@ -0,0 +1,129 @@
+"""Async audit client using httpx."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import uuid
+from datetime import datetime
+from typing import Any, Optional
+
+import httpx
+from pydantic import ValidationError as PydanticValidationError
+
+from .._http import DEFAULT_TIMEOUT_S, USER_AGENT
+from ..exceptions import TransportError, ValidationError
+from .models import Event
+
+_log = logging.getLogger("fact0")
+
+_RETRYABLE = {429, 500, 502, 503, 504}
+
+
+class AsyncAuditClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        timeout_s: float = DEFAULT_TIMEOUT_S,
+        sync: bool = False,
+        client: httpx.AsyncClient | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.sync = sync
+        self._client = client
+        self._owned = client is None
+        self.timeout_s = timeout_s
+        self._buf: list[dict[str, Any]] = []
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self.timeout_s)
+        return self._client
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        if self.sync:
+            headers["X-Fact0-Sync"] = "true"
+        return headers
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any | None = None,
+        params: dict[str, Any] | None = None,
+        expect_json: bool = True,
+    ) -> Any:
+        client = await self._get_client()
+        url = f"{self.base_url}{path}"
+        resp = await client.request(method, url, json=json_body, params=params, headers=self._headers())
+        if resp.status_code >= 300:
+            raise TransportError(f"{method} {path} -> {resp.status_code}", status_code=resp.status_code)
+        if not expect_json:
+            return resp.content
+        try:
+            return resp.json()
+        except ValueError:
+            return {}
+
+    async def log(self, **fields: Any) -> None:
+        wire = self._validate(**fields)
+        self._buf.append(wire)
+
+    async def flush(self) -> None:
+        if not self._buf:
+            return
+        chunk, self._buf = self._buf, []
+        await self._request("POST", "/v1/events/batch", json_body={"events": chunk})
+
+    async def close(self) -> None:
+        await self.flush()
+        if self._owned and self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def get_event(self, event_id: str) -> dict[str, Any]:
+        return await self._request("GET", f"/v1/events/{event_id}")
+
+    async def list_events(self, **filters: Any) -> dict[str, Any]:
+        return await self._request("GET", "/v1/events", params={k: v for k, v in filters.items() if v is not None})
+
+    async def verify(self, **params: Any) -> dict[str, Any]:
+        return await self._request("GET", "/v1/verify", params={k: v for k, v in params.items() if v is not None})
+
+    async def verify_event(self, event_id: str) -> dict[str, Any]:
+        return await self._request("GET", f"/v1/events/{event_id}/verify")
+
+    async def get_receipt(self, receipt_id: str) -> dict[str, Any]:
+        return await self._request("GET", f"/v1/receipts/{receipt_id}")
+
+    async def wait_for_receipt(self, receipt_id: str, *, timeout_s: float = 30.0) -> dict[str, Any]:
+        import time
+
+        deadline = time.monotonic() + timeout_s
+        while time.monotonic() < deadline:
+            body = await self.get_receipt(receipt_id)
+            if body.get("status") in ("committed", "failed"):
+                return body
+            await asyncio.sleep(0.2)
+        raise TransportError(f"receipt {receipt_id} not settled within {timeout_s}s")
+
+    def _validate(self, **kwargs: Any) -> dict[str, Any]:
+        if kwargs.get("event_id"):
+            kwargs["id"] = kwargs.pop("event_id")
+        elif "id" not in kwargs:
+            kwargs["id"] = str(uuid.uuid4())
+        try:
+            evt = Event(**kwargs)
+        except PydanticValidationError as exc:
+            raise ValidationError(str(exc)) from exc
+        return evt.model_dump(exclude_none=True, mode="json")

fact0/audit/client.py

@@ -0,0 +1,220 @@
+"""Synchronous audit log client with background batching."""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import threading
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Iterator, Optional
+
+from pydantic import ValidationError as PydanticValidationError
+
+from .._http import DEFAULT_TIMEOUT_S, SyncHTTP
+from ..exceptions import AuditLogError, TransportError, ValidationError
+from .models import Event
+from .transport import AuditTransport
+
+_log = logging.getLogger("fact0")
+
+DEFAULT_BATCH_MAX_SIZE = 100
+DEFAULT_BATCH_MAX_WAIT_MS = 500
+
+
+class AuditClient:
+    """Buffered, thread-safe audit log client."""
+
+    def __init__(
+        self,
+        http: SyncHTTP,
+        *,
+        batch_max_size: int = DEFAULT_BATCH_MAX_SIZE,
+        batch_max_wait_ms: int = DEFAULT_BATCH_MAX_WAIT_MS,
+        raise_on_error: bool = False,
+        dead_letter_path: Optional[str] = None,
+        poll_receipts: bool = True,
+        transport: Any | None = None,
+    ):
+        self._http = http
+        if transport is not None and hasattr(transport, "_audit"):
+            self._transport = transport._audit
+        elif isinstance(transport, SyncHTTP):
+            self._http = transport
+            self._transport = AuditTransport(transport)
+        elif transport is not None:
+            self._transport = transport
+        else:
+            self._transport = AuditTransport(http)
+        self._batch_max_size = batch_max_size
+        self._batch_max_wait_s = batch_max_wait_ms / 1000.0
+        self._raise_on_error = raise_on_error
+        self._dead_letter_path = dead_letter_path
+        self._poll_receipts = poll_receipts
+
+        self._buf: list[dict[str, Any]] = []
+        self._cond = threading.Condition()
+        self._stopped = False
+        self._flusher = threading.Thread(target=self._run, daemon=True, name="fact0-audit-flush")
+        self._flusher.start()
+        atexit.register(self.close)
+
+    def log(
+        self,
+        *,
+        actor: dict[str, Any],
+        action: str,
+        resource: dict[str, Any],
+        outcome: str,
+        metadata: Optional[dict[str, Any]] = None,
+        timestamp: Optional[datetime] = None,
+        event_id: Optional[str] = None,
+    ) -> None:
+        wire = self._validate_event(
+            actor=actor,
+            action=action,
+            resource=resource,
+            outcome=outcome,
+            metadata=metadata,
+            timestamp=timestamp,
+            event_id=event_id,
+        )
+        with self._cond:
+            was_empty = not self._buf
+            self._buf.append(wire)
+            if was_empty or len(self._buf) >= self._batch_max_size:
+                self._cond.notify_all()
+
+    def log_batch(self, events: list[dict[str, Any]]) -> dict[str, Any]:
+        validated = [self._validate_wire(e) for e in events]
+        return self._send(validated)
+
+    def flush(self) -> None:
+        while True:
+            with self._cond:
+                if not self._buf:
+                    return
+                chunk = self._buf[: self._batch_max_size]
+                del self._buf[: self._batch_max_size]
+            self._send(chunk)
+
+    def close(self) -> None:
+        with self._cond:
+            if self._stopped:
+                return
+            self._stopped = True
+            self._cond.notify_all()
+        self._flusher.join(timeout=5.0)
+        self.flush()
+
+    def get_event(self, event_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/events/{event_id}")
+
+    def list_events(self, **filters: Any) -> dict[str, Any]:
+        params = {k: v for k, v in filters.items() if v is not None}
+        return self._http.request("GET", "/v1/events", params=params)
+
+    def get_receipt(self, receipt_id: str) -> dict[str, Any]:
+        return self._transport.get_receipt(receipt_id)
+
+    def wait_for_receipt(self, receipt_id: str, *, timeout_s: float = 30.0) -> dict[str, Any]:
+        return self._transport.poll_receipt(receipt_id, timeout_s=timeout_s)
+
+    def verify(self, **params: Any) -> dict[str, Any]:
+        return self._http.request("GET", "/v1/verify", params={k: v for k, v in params.items() if v is not None})
+
+    def verify_event(self, event_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/events/{event_id}/verify")
+
+    def export_pdf(self, **params: Any) -> bytes:
+        return self._http.request(
+            "GET", "/v1/export/pdf", params={k: v for k, v in params.items() if v is not None}, expect_json=False
+        )
+
+    def export_evidence_pack(self, **params: Any) -> bytes:
+        return self._http.request(
+            "GET",
+            "/v1/export/evidence-pack",
+            params={k: v for k, v in params.items() if v is not None},
+            expect_json=False,
+        )
+
+    def stream_events(self) -> Iterator[dict[str, Any]]:
+        import requests
+
+        url = f"{self._http.base_url}/v1/events/stream"
+        headers = self._http._headers()
+        headers["Accept"] = "text/event-stream"
+        with requests.get(url, headers=headers, stream=True, timeout=self._http.timeout_s) as resp:
+            resp.raise_for_status()
+            data_lines: list[str] = []
+            for raw in resp.iter_lines(decode_unicode=True):
+                if raw is None:
+                    continue
+                if raw.startswith("data:"):
+                    data_lines.append(raw[5:].strip())
+                elif raw == "" and data_lines:
+                    payload = "".join(data_lines)
+                    data_lines.clear()
+                    if payload and payload != "{}":
+                        yield json.loads(payload)
+
+    def _validate_event(self, **kwargs: Any) -> dict[str, Any]:
+        kwargs.pop("event_id", None)
+        if kwargs.get("metadata") is None:
+            kwargs.pop("metadata", None)
+        if "event_id" in kwargs and kwargs["event_id"]:
+            kwargs["id"] = kwargs.pop("event_id")
+        elif "id" not in kwargs:
+            kwargs["id"] = str(uuid.uuid4())
+        return self._validate_wire(kwargs)
+
+    def _validate_wire(self, fields: dict[str, Any]) -> dict[str, Any]:
+        try:
+            evt = Event(**fields)
+        except PydanticValidationError as exc:
+            raise ValidationError(str(exc)) from exc
+        return evt.model_dump(exclude_none=True, mode="json")
+
+    def _run(self) -> None:
+        while True:
+            with self._cond:
+                if self._stopped:
+                    return
+                if not self._buf:
+                    self._cond.wait()
+                    if self._stopped:
+                        return
+                if len(self._buf) < self._batch_max_size:
+                    self._cond.wait(timeout=self._batch_max_wait_s)
+                if self._stopped:
+                    return
+                chunk = self._buf[: self._batch_max_size]
+                del self._buf[: self._batch_max_size]
+            if chunk:
+                self._send(chunk)
+
+    def _send(self, buf: list[dict[str, Any]]) -> dict[str, Any]:
+        try:
+            result = self._transport.post_batch(buf)
+            receipt_id = result.get("receipt_id")
+            if receipt_id and self._poll_receipts and result.get("status") == "queued":
+                self._transport.poll_receipt(receipt_id)
+            return result
+        except (TransportError, AuditLogError) as exc:
+            self._dead_letter(buf, exc)
+            if self._raise_on_error:
+                raise
+            _log.warning("audit flush dropped %d events: %s", len(buf), exc)
+            return {}
+
+    def _dead_letter(self, buf: list[dict[str, Any]], exc: Exception) -> None:
+        if not self._dead_letter_path:
+            return
+        path = Path(self._dead_letter_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as f:
+            for evt in buf:
+                f.write(json.dumps({"error": str(exc), "event": evt}) + "\n")

fact0/audit/models.py

@@ -0,0 +1,57 @@
+"""Pydantic models for audit events."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
+
+
+class ActorType(str, Enum):
+    HUMAN = "human"
+    AGENT = "agent"
+    SYSTEM = "system"
+
+
+class Outcome(str, Enum):
+    SUCCESS = "success"
+    FAILURE = "failure"
+    ERROR = "error"
+
+
+class Actor(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    id: str = Field(min_length=1)
+    type: ActorType
+    email: Optional[str] = None
+
+
+class Resource(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    id: str = Field(min_length=1)
+    type: str = Field(min_length=1)
+    name: Optional[str] = None
+
+
+class Event(BaseModel):
+    """Wire shape of an audit event."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    actor: Actor
+    action: str = Field(min_length=1)
+    resource: Resource
+    outcome: Outcome
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    id: Optional[str] = None
+    timestamp: Optional[datetime] = None
+
+    @field_serializer("timestamp")
+    def _serialize_ts(self, v: Optional[datetime]) -> Optional[str]:
+        if v is None:
+            return None
+        if v.tzinfo is None:
+            v = v.replace(tzinfo=timezone.utc)
+        return v.isoformat()

fact0/audit/transport.py

@@ -0,0 +1,35 @@
+"""Audit HTTP transport."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from .._http import SyncHTTP
+from ..exceptions import TransportError
+
+
+class AuditTransport:
+    def __init__(self, http: SyncHTTP):
+        self._http = http
+
+    def post_batch(self, events: list[dict[str, Any]]) -> dict[str, Any]:
+        return self._http.request("POST", "/v1/events/batch", json_body={"events": events})
+
+    def get_receipt(self, receipt_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/receipts/{receipt_id}")
+
+    def poll_receipt(
+        self,
+        receipt_id: str,
+        *,
+        timeout_s: float = 30.0,
+        interval_s: float = 0.2,
+    ) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout_s
+        while time.monotonic() < deadline:
+            body = self.get_receipt(receipt_id)
+            if body.get("status") in ("committed", "failed"):
+                return body
+            time.sleep(interval_s)
+        raise TransportError(f"receipt {receipt_id} not settled within {timeout_s}s")

fact0/exceptions.py

@@ -0,0 +1,23 @@
+"""Public exception types raised by the Fact0 SDK."""
+
+from __future__ import annotations
+
+
+class Fact0Error(Exception):
+    """Base class for SDK errors."""
+
+
+# Back-compat aliases
+AuditLogError = Fact0Error
+
+
+class ValidationError(Fact0Error):
+    """Invalid event fields or types."""
+
+
+class TransportError(Fact0Error):
+    """HTTP failure or unreachable server."""
+
+    def __init__(self, message: str, *, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code

fact0/integrations/fastapi.py

@@ -0,0 +1,45 @@
+"""FastAPI middleware for request-level audit logging."""
+
+from __future__ import annotations
+
+import time
+from typing import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from fact0.audit.client import AuditClient
+
+
+class AuditMiddleware(BaseHTTPMiddleware):
+    """Log each HTTP request as an audit event."""
+
+    def __init__(
+        self,
+        app,
+        client_factory: Callable[[], AuditClient],
+        *,
+        action_prefix: str = "api",
+    ):
+        super().__init__(app)
+        self._client_factory = client_factory
+        self._action_prefix = action_prefix
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        start = time.perf_counter()
+        response = await call_next(request)
+        duration_ms = int((time.perf_counter() - start) * 1000)
+        client = self._client_factory()
+        client.log(
+            actor={"id": "api", "type": "system"},
+            action=f"{self._action_prefix}.request",
+            resource={"id": request.url.path, "type": "http.route"},
+            outcome="success" if response.status_code < 400 else "failure",
+            metadata={
+                "method": request.method,
+                "status": response.status_code,
+                "duration_ms": duration_ms,
+            },
+        )
+        return response

fact0/integrations/langchain.py

@@ -0,0 +1,96 @@
+"""LangChain callback handler for Fact0 telemetry and audit."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from fact0 import Client
+
+
+class Fact0CallbackHandler:
+    """Record LangChain runs to Fact0 telemetry (and optional audit events)."""
+
+    def __init__(
+        self,
+        client: Client,
+        *,
+        agent_id: str,
+        audit_sensitive_actions: bool = False,
+        execution_metadata: dict[str, str] | None = None,
+    ):
+        self._client = client
+        self._agent_id = agent_id
+        self._audit_sensitive = audit_sensitive_actions
+        self._metadata = execution_metadata or {}
+        self._execution_ctx = None
+        self._spans: dict[UUID, Any] = {}
+
+    def _ensure_execution(self):
+        if self._execution_ctx is None:
+            self._execution_ctx = self._client.telemetry.execution(
+                agent_id=self._agent_id,
+                metadata=self._metadata,
+            ).__enter__()
+            if self._audit_sensitive:
+                self._client.audit.log(
+                    actor={"id": self._agent_id, "type": "agent"},
+                    action="agent.run.start",
+                    resource={"id": self._execution_ctx.id, "type": "agent.execution"},
+                    outcome="success",
+                )
+
+    # LangChain BaseCallbackHandler-style hooks (duck typed)
+    def on_chain_start(self, serialized: dict, inputs: dict, **kwargs: Any) -> None:
+        self._ensure_execution()
+
+    def on_chain_end(self, outputs: dict, **kwargs: Any) -> None:
+        if self._execution_ctx and self._audit_sensitive:
+            self._client.audit.log(
+                actor={"id": self._agent_id, "type": "agent"},
+                action="agent.run.end",
+                resource={"id": self._execution_ctx.id, "type": "agent.execution"},
+                outcome="success",
+            )
+        if self._execution_ctx:
+            self._client.telemetry.end_execution(self._execution_ctx.id, "COMPLETED")
+            self._execution_ctx = None
+
+    def on_llm_start(self, serialized: dict, prompts: List[str], **kwargs: Any) -> None:
+        self._ensure_execution()
+        run_id = kwargs.get("run_id")
+        if self._execution_ctx and run_id:
+            span = self._execution_ctx.span(
+                serialized.get("name", "llm"), span_type="MODEL_INVOCATION"
+            )
+            span.__enter__()
+            self._spans[run_id] = span
+
+    def on_llm_end(self, response: Any, **kwargs: Any) -> None:
+        run_id = kwargs.get("run_id")
+        span = self._spans.pop(run_id, None) if run_id else None
+        if span:
+            span.complete(output={"text": str(response)[:500]})
+
+    def on_tool_start(self, serialized: dict, input_str: str, **kwargs: Any) -> None:
+        self._ensure_execution()
+        run_id = kwargs.get("run_id")
+        name = serialized.get("name", "tool")
+        if self._execution_ctx and run_id:
+            span = self._execution_ctx.span(name, span_type="TOOL_CALL")
+            span.__enter__()
+            self._spans[run_id] = span
+        if self._audit_sensitive:
+            self._client.audit.log(
+                actor={"id": self._agent_id, "type": "agent"},
+                action="agent.tool.call",
+                resource={"id": name, "type": "tool"},
+                outcome="success",
+                metadata={"input": input_str[:500]},
+            )
+
+    def on_tool_end(self, output: str, **kwargs: Any) -> None:
+        run_id = kwargs.get("run_id")
+        span = self._spans.pop(run_id, None) if run_id else None
+        if span:
+            span.complete(output={"result": output[:500]})

fact0/py.typed

@@ -0,0 +1 @@
+py.typed

fact0/telemetry/client.py

@@ -0,0 +1,78 @@
+"""Execution telemetry REST client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import SyncHTTP
+
+
+class TelemetryClient:
+    def __init__(self, http: SyncHTTP):
+        self._http = http
+
+    def start_execution(
+        self,
+        *,
+        agent_id: str,
+        agent_name: str = "",
+        trigger: str = "",
+        metadata: dict[str, str] | None = None,
+        idempotency_key: str = "",
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"agent_id": agent_id}
+        if agent_name:
+            body["agent_name"] = agent_name
+        if trigger:
+            body["trigger"] = trigger
+        if metadata:
+            body["metadata"] = metadata
+        if idempotency_key:
+            body["idempotency_key"] = idempotency_key
+        return self._http.request("POST", "/api/v1/executions", json_body=body)
+
+    def ingest_spans(self, execution_id: str, spans: list[dict[str, Any]]) -> dict[str, Any]:
+        return self._http.request(
+            "POST",
+            f"/api/v1/executions/{execution_id}/spans",
+            json_body={"spans": spans},
+        )
+
+    def ingest_events(self, execution_id: str, events: list[dict[str, Any]]) -> dict[str, Any]:
+        return self._http.request(
+            "POST",
+            f"/api/v1/executions/{execution_id}/events",
+            json_body={"events": events},
+        )
+
+    def end_execution(self, execution_id: str, status: str) -> dict[str, Any]:
+        return self._http.request(
+            "PUT",
+            f"/api/v1/executions/{execution_id}/end",
+            json_body={"status": status},
+        )
+
+    def list_executions(self, **params: Any) -> dict[str, Any]:
+        return self._http.request("GET", "/api/v1/executions", params=params)
+
+    def get_execution(self, execution_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/api/v1/executions/{execution_id}")
+
+    def get_spans(self, execution_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/api/v1/executions/{execution_id}/spans")
+
+    def get_dag(self, execution_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/api/v1/executions/{execution_id}/dag")
+
+    def replay(self, execution_id: str, **params: Any) -> dict[str, Any]:
+        return self._http.request(
+            "GET", f"/api/v1/executions/{execution_id}/replay", params=params
+        )
+
+    def get_span(self, span_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/api/v1/spans/{span_id}")
+
+    def execution(self, **kwargs: Any):
+        from .context import ExecutionContext
+
+        return ExecutionContext(self, **kwargs)

fact0/telemetry/context.py

@@ -0,0 +1,102 @@
+"""Execution and span context managers for telemetry."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from .client import TelemetryClient
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class SpanContext:
+    def __init__(self, tel: TelemetryClient, execution_id: str, name: str, span_type: str):
+        self._tel = tel
+        self._execution_id = execution_id
+        self._span_id = f"span_{uuid.uuid4().hex[:16]}"
+        self._name = name
+        self._span_type = span_type
+        self._started = _utcnow()
+        self._ended = False
+
+    def log_event(self, event_type: str, payload: dict[str, Any]) -> None:
+        self._tel.ingest_events(
+            self._execution_id,
+            [
+                {
+                    "id": f"evt_{uuid.uuid4().hex[:16]}",
+                    "execution_id": self._execution_id,
+                    "span_id": self._span_id,
+                    "event_type": event_type,
+                    "timestamp": _utcnow().isoformat(),
+                    "payload": payload,
+                }
+            ],
+        )
+
+    def complete(self, *, output: dict[str, Any] | None = None, status: str = "COMPLETED") -> None:
+        if self._ended:
+            return
+        self._ended = True
+        span: dict[str, Any] = {
+            "id": self._span_id,
+            "execution_id": self._execution_id,
+            "span_type": self._span_type,
+            "name": self._name,
+            "status": status,
+            "started_at": self._started.isoformat(),
+            "ended_at": _utcnow().isoformat(),
+        }
+        if output:
+            span["metadata"] = {"output": str(output)}
+        self._tel.ingest_spans(self._execution_id, [span])
+
+    def __enter__(self) -> SpanContext:
+        self._tel.ingest_spans(
+            self._execution_id,
+            [
+                {
+                    "id": self._span_id,
+                    "execution_id": self._execution_id,
+                    "span_type": self._span_type,
+                    "name": self._name,
+                    "status": "RUNNING",
+                    "started_at": self._started.isoformat(),
+                }
+            ],
+        )
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if not self._ended:
+            status = "FAILED" if exc_type else "COMPLETED"
+            self.complete(status=status)
+
+
+class ExecutionContext:
+    def __init__(self, tel: TelemetryClient, **kwargs: Any):
+        self._tel = tel
+        self._kwargs = kwargs
+        self._execution: dict[str, Any] | None = None
+
+    @property
+    def id(self) -> str:
+        if not self._execution:
+            raise RuntimeError("execution not started")
+        return self._execution["id"]
+
+    def span(self, name: str, *, span_type: str = "CUSTOM") -> SpanContext:
+        return SpanContext(self._tel, self.id, name, span_type)
+
+    def __enter__(self) -> ExecutionContext:
+        self._execution = self._tel.start_execution(**self._kwargs)
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._execution:
+            status = "FAILED" if exc_type else "COMPLETED"
+            self._tel.end_execution(self._execution["id"], status)

fact0_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: fact0-sdk
+Version: 1.0.0
+Summary: Fact0 SDK - audit log and execution telemetry for AI agents
+Author: Fact0
+License-Expression: MIT
+Project-URL: Homepage, https://fact0.io
+Project-URL: Documentation, https://docs.fact0.io
+Project-URL: Repository, https://github.com/fact0-ai/fact0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: requests<3,>=2.31
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == "fastapi"
+Requires-Dist: starlette>=0.36; extra == "fastapi"
+
+# fact0
+
+Python SDK for [Fact0](https://fact0.io) - tamper-evident audit logs and execution telemetry for AI agents.
+
+```bash
+pip install fact0-sdk
+```
+
+```python
+import fact0
+
+client = fact0.Client(api_key="alk_live_...")
+
+client.audit.log(
+    actor={"id": "user_123", "type": "human"},
+    action="document.delete",
+    resource={"id": "doc_456", "type": "document"},
+    outcome="success",
+)
+
+with client.telemetry.execution(agent_id="bot-1") as ex:
+    with ex.span("tool.search", span_type="TOOL_CALL") as span:
+        span.complete(output={"hits": 3})
+```
+
+Docs: [docs.fact0.io](https://docs.fact0.io)
+
+## Legacy imports
+
+```python
+import fact0  # deprecated shim → fact0
+import auditlog    # deprecated shim → fact0.audit
+```
+
+Both emit `DeprecationWarning` on import.

fact0_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+auditlog/__init__.py,sha256=WzK9mg9iF5G6EjpSz5dfWlfeFCfs1a4QdMzgF_4B6kc,550
+auditlog/client.py,sha256=pU271OxVjVkmn95s5iN3mbN_AgevbNPKbQkslUQb1KY,1553
+fact0/__init__.py,sha256=aozmzvJn-bjP_ombgomYoPLTmJPanGam2ESWiOzDYOc,2784
+fact0/_http.py,sha256=n859pBaFxluuiqxSwPi_JhQaoaNCwGf36Ea2zWp30uo,3951
+fact0/exceptions.py,sha256=gQqotlJ81K_aItPFHiVghdivQgTf248QSo9dXuUh7Ao,516
+fact0/py.typed,sha256=Enkyrr7t9bKZQk8ywVperZB_J3TbNaaRpp6qn8sI34s,9
+fact0/audit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fact0/audit/async_client.py,sha256=lUslD98S1bUWhM6UbbvYVWN9v_XxLltNWetc_m7KwMI,4367
+fact0/audit/client.py,sha256=-kMTyy7ZKCi5RXKW2x3E2RgoLCcvGMrjvTM7W4Ktl9E,8025
+fact0/audit/models.py,sha256=ZpZjKHCl0kJYRrxbx2HVBzCzXNjh_26BLlEYQZ93m-U,1361
+fact0/audit/transport.py,sha256=NnyEu1ekM55JUWtxZ5Zj507UNrEF8SvPTjCcqh28hzg,1075
+fact0/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fact0/integrations/fastapi.py,sha256=z3p5hWKfD9RiQF0Re8q-dPwfTAzwhaucf9O3tq2I5RU,1415
+fact0/integrations/langchain.py,sha256=m6NozNymff-NaDTkwd70cC29D7_Sg9nSarqlCtlZwi0,3693
+fact0/telemetry/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fact0/telemetry/client.py,sha256=P0qJJW9pLG-Hnf45x2B3UhuWNHy8b42vs6SBq1W6Kwg,2659
+fact0/telemetry/context.py,sha256=jFrkVTN64g9F7tXVAp1oXvWhQvaWxx9c2oMl30SVn0M,3292
+fact0_sdk-1.0.0.dist-info/METADATA,sha256=Uc4ZTfFnixdPK-Lj_Iul6YJ6AD1ERlUjF4v56X0BJu8,1612
+fact0_sdk-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fact0_sdk-1.0.0.dist-info/top_level.txt,sha256=dQi_O4dq47qwK2ohMu5UyVz7arTzaGZG8P9D8nCkKBw,15
+fact0_sdk-1.0.0.dist-info/RECORD,,

fact0_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fact0_sdk-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+auditlog
+fact0