fact0-sdk 1.0.0__tar.gz

fact0_sdk-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,35 @@
+# 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/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"]

fact0_sdk-1.0.0/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_sdk-1.0.0/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_sdk-1.0.0/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_sdk-1.0.0/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")