verdifax 0.2.0__py3-none-any.whl

verdifax/__init__.py

@@ -0,0 +1,147 @@
+"""Verdifax — cryptographic attestation for AI inference.
+
+Three-line integration:
+
+    >>> import verdifax
+    >>> receipt = verdifax.attest(
+    ...     payload="hello verdifax",
+    ...     program_id="a" * 64,
+    ...     route_id="route-test",
+    ...     registry_record_hash="b" * 64,
+    ... )  # doctest: +SKIP
+    >>> receipt.manifest_hash  # doctest: +SKIP
+    '7f...'
+
+The SDK targets the Verdifax orchestrator REST API. By default it talks
+to ``http://localhost:9090``; override with ``$VERDIFAX_API_URL`` or by
+passing ``base_url`` to :class:`VerdifaxClient`.
+"""
+
+from __future__ import annotations
+
+from typing import Optional as _Optional, Union as _Union
+
+from ._version import __version__
+from .async_client import AsyncVerdifaxClient
+from .client import VerdifaxClient
+from .exceptions import (
+    APIError,
+    ConnectionError,
+    StageError,
+    ValidationError,
+    VerdifaxError,
+)
+from .helpers import attest_claude_response, attest_openai_response
+from .models import (
+    KERNEL_NAMES,
+    STAGE_NAMES,
+    AttestationReceipt,
+    AttestedContext,
+    ExecuteRequest,
+    ExecutionManifest,
+    StageResult,
+)
+from . import section0  # §0 cross-language canonical hash verifier
+
+
+def from_env(
+    base_url: _Optional[str] = None,
+    api_key: _Optional[str] = None,
+    timeout: _Optional[float] = None,
+) -> VerdifaxClient:
+    """Construct a :class:`VerdifaxClient` from environment variables.
+
+    Honors ``VERDIFAX_API_URL`` and ``VERDIFAX_API_KEY``. Any explicit
+    arguments override the corresponding environment variable.
+    """
+    kwargs: dict[str, object] = {}
+    if base_url is not None:
+        kwargs["base_url"] = base_url
+    if api_key is not None:
+        kwargs["api_key"] = api_key
+    if timeout is not None:
+        kwargs["timeout"] = timeout
+    return VerdifaxClient(**kwargs)  # type: ignore[arg-type]
+
+
+def attest(
+    payload: _Union[str, bytes],
+    program_id: str,
+    route_id: str,
+    registry_record_hash: str,
+    *,
+    attested_context: _Optional[AttestedContext] = None,
+    base_url: _Optional[str] = None,
+    api_key: _Optional[str] = None,
+    timeout: _Optional[float] = None,
+) -> AttestationReceipt:
+    """Module-level shortcut: attest a payload using a one-shot client.
+
+    Equivalent to ``VerdifaxClient(...).attest(...)`` with the client
+    closed automatically afterwards. For high-throughput use, instantiate
+    a :class:`VerdifaxClient` yourself and reuse its connection pool.
+
+    Pass ``attested_context`` to record a caller-attested actor / model /
+    decision block into the run's EPA artifact — see
+    :class:`AttestedContext`.
+    """
+    with from_env(base_url=base_url, api_key=api_key, timeout=timeout) as client:
+        return client.attest(
+            payload=payload,
+            program_id=program_id,
+            route_id=route_id,
+            registry_record_hash=registry_record_hash,
+            attested_context=attested_context,
+        )
+
+
+def verify(
+    manifest_hash: str,
+    payload: _Union[str, bytes],
+    program_id: str,
+    route_id: str,
+    registry_record_hash: str,
+    *,
+    attested_context: _Optional[AttestedContext] = None,
+    base_url: _Optional[str] = None,
+    api_key: _Optional[str] = None,
+    timeout: _Optional[float] = None,
+) -> bool:
+    """Module-level shortcut: verify a previously issued manifest hash.
+
+    ``attested_context`` must match the value used on the original
+    ``attest`` call.
+    """
+    with from_env(base_url=base_url, api_key=api_key, timeout=timeout) as client:
+        return client.verify(
+            manifest_hash=manifest_hash,
+            payload=payload,
+            program_id=program_id,
+            route_id=route_id,
+            registry_record_hash=registry_record_hash,
+            attested_context=attested_context,
+        )
+
+
+__all__ = [
+    "APIError",
+    "AsyncVerdifaxClient",
+    "AttestationReceipt",
+    "AttestedContext",
+    "ConnectionError",
+    "ExecuteRequest",
+    "ExecutionManifest",
+    "KERNEL_NAMES",
+    "STAGE_NAMES",
+    "StageError",
+    "StageResult",
+    "ValidationError",
+    "VerdifaxClient",
+    "VerdifaxError",
+    "__version__",
+    "attest",
+    "attest_claude_response",
+    "attest_openai_response",
+    "from_env",
+    "verify",
+]

verdifax/_transport.py

@@ -0,0 +1,61 @@
+"""Shared response handling for sync and async clients.
+
+Centralizing this logic keeps :class:`VerdifaxClient` and
+:class:`AsyncVerdifaxClient` from duplicating error-translation code.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from .exceptions import APIError, ConnectionError as VerdifaxConnectionError, StageError
+
+
+def parse_response(response: httpx.Response) -> dict[str, Any]:
+    """Validate an HTTP response and return its decoded JSON body.
+
+    Raises :class:`StageError` for orchestrator stage failures (HTTP 422
+    with an ``error_stage`` in the body), :class:`APIError` for any other
+    non-2xx response, and returns the JSON body on success.
+    """
+    try:
+        body: dict[str, Any] = response.json()
+    except ValueError:
+        body = {}
+
+    if response.is_success:
+        return body
+
+    message = _extract_message(body) or response.reason_phrase or "request failed"
+    stage = body.get("error_stage") if isinstance(body, dict) else None
+    if response.status_code == 422 and stage:
+        raise StageError(
+            message=message,
+            status_code=response.status_code,
+            stage=str(stage),
+            response_body=body if isinstance(body, dict) else None,
+        )
+    raise APIError(
+        message=message,
+        status_code=response.status_code,
+        response_body=body if isinstance(body, dict) else None,
+    )
+
+
+def _extract_message(body: Any) -> Optional[str]:
+    if isinstance(body, dict):
+        for key in ("error", "message", "detail"):
+            value = body.get(key)
+            if isinstance(value, str) and value:
+                return value
+    return None
+
+
+def wrap_transport_error(exc: httpx.HTTPError) -> VerdifaxConnectionError:
+    """Translate an httpx transport error into a Verdifax ``ConnectionError``."""
+    return VerdifaxConnectionError(f"verdifax: failed to reach API: {exc}")
+
+
+__all__ = ["parse_response", "wrap_transport_error"]

verdifax/_validation.py

@@ -0,0 +1,61 @@
+"""Client-side validation helpers shared by the sync and async clients.
+
+These mirror the validation the Verdifax API performs server-side (see
+``cmd/api/main.go``). Performing the check client-side gives callers an
+immediate :class:`~verdifax.exceptions.ValidationError` instead of an
+HTTP 400 round-trip.
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+from .exceptions import ValidationError
+
+_HEX_CHARS = frozenset("0123456789abcdef")
+
+
+def validate_hex64(value: str, field_name: str) -> None:
+    """Raise ``ValidationError`` unless ``value`` is 64 lowercase hex chars."""
+    if not isinstance(value, str):
+        raise ValidationError(f"{field_name} must be a string, got {type(value).__name__}")
+    if len(value) != 64:
+        raise ValidationError(
+            f"{field_name} must be 64-char hex, got {len(value)} chars"
+        )
+    lowered = value.lower()
+    if lowered != value:
+        raise ValidationError(f"{field_name} must be lowercase hex")
+    for c in lowered:
+        if c not in _HEX_CHARS:
+            raise ValidationError(f"{field_name} must be lowercase hex (offending char: {c!r})")
+
+
+def validate_route_id(value: str) -> None:
+    """Raise ``ValidationError`` unless ``value`` is a non-empty string."""
+    if not isinstance(value, str) or not value:
+        raise ValidationError("route_id must be a non-empty string")
+
+
+def normalize_payload(payload: Union[str, bytes]) -> tuple[str, str]:
+    """Return ``(payload_text, payload_b64)`` exactly one of which is non-empty.
+
+    Strings are sent as ``payload_text``. Bytes are decoded as UTF-8 if
+    possible so the API can hash them deterministically; otherwise they are
+    base64-encoded into the ``payload`` field.
+    """
+    if isinstance(payload, str):
+        return payload, ""
+    if isinstance(payload, bytes):
+        try:
+            return payload.decode("utf-8"), ""
+        except UnicodeDecodeError:
+            import base64
+
+            return "", base64.b64encode(payload).decode("ascii")
+    raise ValidationError(
+        f"payload must be str or bytes, got {type(payload).__name__}"
+    )
+
+
+__all__ = ["normalize_payload", "validate_hex64", "validate_route_id"]

verdifax/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "0.2.0"

verdifax/async_client.py

@@ -0,0 +1,208 @@
+"""Asynchronous Verdifax API client.
+
+Mirrors :class:`verdifax.VerdifaxClient` but uses ``httpx.AsyncClient``.
+
+Example:
+    >>> import asyncio
+    >>> from verdifax import AsyncVerdifaxClient
+    >>>
+    >>> async def main():
+    ...     async with AsyncVerdifaxClient() as client:
+    ...         receipt = await client.attest(
+    ...             payload="hello verdifax",
+    ...             program_id="a" * 64,
+    ...             route_id="route-test",
+    ...             registry_record_hash="b" * 64,
+    ...         )
+    ...         return receipt.manifest_hash
+"""
+
+from __future__ import annotations
+
+import os
+from types import TracebackType
+from typing import Any, Optional, Type, Union
+
+import httpx
+
+from ._transport import parse_response, wrap_transport_error
+from ._validation import normalize_payload, validate_hex64, validate_route_id
+from ._version import __version__
+from .client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    ENV_API_KEY,
+    ENV_BASE_URL,
+)
+from .exceptions import APIError
+from .models import (
+    AttestationReceipt,
+    AttestedContext,
+    ExecuteRequest,
+    ExecutionManifest,
+)
+
+
+class AsyncVerdifaxClient:
+    """Async client for the Verdifax pipeline REST API.
+
+    Args:
+        base_url: Base URL of the Verdifax API. Falls back to
+            ``$VERDIFAX_API_URL`` and finally to ``http://localhost:9090``.
+        api_key: Optional API key sent as the ``X-Verdifax-Key`` header.
+            Falls back to ``$VERDIFAX_API_KEY``.
+        timeout: Request timeout in seconds. Defaults to 30.
+        transport: Optional custom ``httpx.AsyncBaseTransport`` for tests.
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        self.base_url = (base_url or os.environ.get(ENV_BASE_URL) or DEFAULT_BASE_URL).rstrip("/")
+        self.api_key = api_key or os.environ.get(ENV_API_KEY)
+        self.timeout = timeout
+
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"verdifax-python/{__version__} (async)",
+        }
+        if self.api_key:
+            headers["X-Verdifax-Key"] = self.api_key
+
+        self._http = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=headers,
+            transport=transport,
+        )
+
+    # ── lifecycle ──────────────────────────────────────────────────────────
+    async def close(self) -> None:
+        """Release the underlying HTTP connection pool."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncVerdifaxClient":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        await self.close()
+
+    # ── public API ─────────────────────────────────────────────────────────
+    async def health(self) -> dict[str, Any]:
+        """Liveness check. Returns the JSON body of ``GET /health``."""
+        try:
+            response = await self._http.get("/health")
+        except httpx.HTTPError as exc:
+            raise wrap_transport_error(exc) from exc
+        return parse_response(response)
+
+    async def attest(
+        self,
+        payload: Union[str, bytes],
+        program_id: str,
+        route_id: str,
+        registry_record_hash: str,
+        attested_context: Optional[AttestedContext] = None,
+    ) -> AttestationReceipt:
+        """Async version of :meth:`VerdifaxClient.attest`.
+
+        Accepts the same optional ``attested_context`` block —
+        see :class:`verdifax.models.AttestedContext`.
+        """
+        request_body = self._build_execute_body(
+            payload=payload,
+            program_id=program_id,
+            route_id=route_id,
+            registry_record_hash=registry_record_hash,
+            attested_context=attested_context,
+        )
+        try:
+            response = await self._http.post("/execute", json=request_body)
+        except httpx.HTTPError as exc:
+            raise wrap_transport_error(exc) from exc
+        body = parse_response(response)
+        if "manifest" not in body:
+            raise APIError(
+                message="API response missing 'manifest'",
+                status_code=response.status_code,
+                response_body=body,
+            )
+        return AttestationReceipt.from_api_response(body)
+
+    async def verify(
+        self,
+        manifest_hash: str,
+        payload: Union[str, bytes],
+        program_id: str,
+        route_id: str,
+        registry_record_hash: str,
+        attested_context: Optional[AttestedContext] = None,
+    ) -> bool:
+        """Async version of :meth:`VerdifaxClient.verify`."""
+        validate_hex64(manifest_hash, "manifest_hash")
+        receipt = await self.attest(
+            payload=payload,
+            program_id=program_id,
+            route_id=route_id,
+            registry_record_hash=registry_record_hash,
+            attested_context=attested_context,
+        )
+        return receipt.manifest_hash == manifest_hash
+
+    async def execute(
+        self,
+        payload: Union[str, bytes],
+        program_id: str,
+        route_id: str,
+        registry_record_hash: str,
+        attested_context: Optional[AttestedContext] = None,
+    ) -> ExecutionManifest:
+        """Async lower-level alternative returning just the manifest."""
+        receipt = await self.attest(
+            payload=payload,
+            program_id=program_id,
+            route_id=route_id,
+            registry_record_hash=registry_record_hash,
+            attested_context=attested_context,
+        )
+        return receipt.manifest
+
+    # ── internal helpers ───────────────────────────────────────────────────
+    @staticmethod
+    def _build_execute_body(
+        payload: Union[str, bytes],
+        program_id: str,
+        route_id: str,
+        registry_record_hash: str,
+        attested_context: Optional[AttestedContext] = None,
+    ) -> dict[str, Any]:
+        validate_hex64(program_id, "program_id")
+        validate_hex64(registry_record_hash, "registry_record_hash")
+        validate_route_id(route_id)
+        payload_text, payload_b64 = normalize_payload(payload)
+        # Auto-derive `attested = True` if any field carries a value, so
+        # callers don't have to remember to set the boolean explicitly.
+        if attested_context is not None:
+            attested_context = attested_context.with_auto_attested()
+        request = ExecuteRequest(
+            payload_text=payload_text or None,
+            payload=payload_b64 or None,
+            program_id=program_id,
+            route_id=route_id,
+            registry_record_hash=registry_record_hash,
+            attested_context=attested_context,
+        )
+        return request.model_dump_request()
+
+
+__all__ = ["AsyncVerdifaxClient"]