truststate 0.2.0__py3-none-any.whl

truststate/__init__.py

@@ -0,0 +1,40 @@
+"""
+TrustState Python SDK
+~~~~~~~~~~~~~~~~~~~~~
+
+A Python SDK for TrustState compliance validation.
+
+Basic usage::
+
+    import asyncio
+    from truststate import TrustStateClient
+
+    client = TrustStateClient(api_key="your-api-key")
+
+    async def main():
+        result = await client.check(
+            entity_type="AgentResponse",
+            data={"responseText": "Hello!", "confidenceScore": 0.95}
+        )
+        print(result.passed, result.record_id)
+
+    asyncio.run(main())
+"""
+
+from .client import TrustStateClient
+from .types import ComplianceResult, BatchResult, EvidenceItem
+from .decorators import compliant
+from .middleware import TrustStateMiddleware
+from .exceptions import TrustStateError
+
+__all__ = [
+    "TrustStateClient",
+    "ComplianceResult",
+    "BatchResult",
+    "EvidenceItem",
+    "compliant",
+    "TrustStateMiddleware",
+    "TrustStateError",
+]
+
+__version__ = "0.2.0"

truststate/client.py

@@ -0,0 +1,500 @@
+"""TrustStateClient — async HTTP client for the TrustState compliance API.
+
+Usage::
+
+    from truststate import TrustStateClient
+
+    client = TrustStateClient(api_key="your-key")
+    result = await client.check("AgentResponse", {"text": "...", "score": 0.9})
+"""
+
+from __future__ import annotations
+
+import random
+import uuid
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .exceptions import TrustStateError
+from .types import BatchResult, ComplianceResult, EvidenceItem
+
+
+class TrustStateClient:
+    """Async client for the TrustState compliance validation API.
+
+    Args:
+        api_key: Your TrustState API key (used as X-API-Key header for writes).
+        base_url: Override the default API base URL.
+        default_schema_version: Schema version applied when not specified per-call.
+        default_actor_id: Actor ID applied when not specified per-call.
+        mock: If True, all HTTP calls are skipped and synthetic results are returned.
+        mock_pass_rate: Probability (0.0–1.0) that a mock check returns passed=True.
+            1.0 = always pass, 0.0 = always fail, 0.8 = 80% pass rate.
+        timeout: HTTP request timeout in seconds.
+    """
+
+    DEFAULT_BASE_URL = "https://truststate-api.apps.trustchainlabs.com"
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        default_schema_version: Optional[str] = None,
+        default_actor_id: str = "",
+        mock: bool = False,
+        mock_pass_rate: float = 1.0,
+        timeout: int = 30,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._default_schema_version = default_schema_version
+        self._default_actor_id = default_actor_id
+        self._mock = mock
+        self._mock_pass_rate = float(mock_pass_rate)
+        self._timeout = timeout
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def check(
+        self,
+        entity_type: str,
+        data: Dict[str, Any],
+        action: str = "CREATE",
+        entity_id: Optional[str] = None,
+        schema_version: Optional[str] = None,
+        actor_id: Optional[str] = None,
+    ) -> ComplianceResult:
+        """Submit a single record for compliance checking.
+
+        Internally wraps the record in a one-item batch and calls POST /v1/write/batch.
+
+        Args:
+            entity_type: The type/category of the entity (e.g. "AgentResponse").
+            data: The record payload to validate.
+            action: The action being performed — "CREATE", "UPDATE", or "DELETE".
+            entity_id: Optional stable identifier for this entity. Auto-generated (uuid4)
+                if not provided.
+            schema_version: Override the client's default schema version.
+            actor_id: Override the client's default actor ID.
+
+        Returns:
+            ComplianceResult with pass/fail status and, if passed, a record_id.
+
+        Raises:
+            TrustStateError: On HTTP 4xx/5xx responses.
+        """
+        eid = entity_id or str(uuid.uuid4())
+
+        if self._mock:
+            return self._mock_single_result(eid)
+
+        batch_result = await self.check_batch(
+            items=[
+                {
+                    "entity_type": entity_type,
+                    "data": data,
+                    "action": action,
+                    "entity_id": eid,
+                    "schema_version": schema_version,
+                    "actor_id": actor_id,
+                }
+            ],
+            default_schema_version=schema_version,
+            default_actor_id=actor_id,
+        )
+        return batch_result.results[0]
+
+    async def check_batch(
+        self,
+        items: List[Dict[str, Any]],
+        default_schema_version: Optional[str] = None,
+        default_actor_id: Optional[str] = None,
+        feed_label: Optional[str] = None,
+    ) -> BatchResult:
+        """Submit multiple records for compliance checking in a single API call.
+
+        Args:
+            items: List of item dicts. Each may contain:
+                - entity_type (required)
+                - data (required)
+                - action (optional, default "upsert")
+                - entity_id (optional, auto-generated if absent)
+                - schema_version (optional — server auto-resolves to active schema if omitted)
+                - actor_id (optional)
+            default_schema_version: Fallback schema version for items that don't specify one.
+                If None, the server auto-resolves to the active schema for each entity type.
+            default_actor_id: Fallback actor ID for items that don't specify one.
+            feed_label: Optional label identifying this feed/source (e.g. "core-banking-feed").
+                Echoed back on every item result — useful for multi-feed pipelines.
+
+        Returns:
+            BatchResult summarising acceptance/rejection counts and per-item results.
+
+        Raises:
+            TrustStateError: On HTTP 4xx/5xx responses.
+        """
+        schema_ver = default_schema_version or self._default_schema_version
+        actor = default_actor_id or self._default_actor_id
+
+        # Normalise items and assign missing entity IDs
+        normalised = []
+        for item in items:
+            eid = item.get("entity_id") or str(uuid.uuid4())
+            entry: Dict[str, Any] = {
+                "entityType": item["entity_type"],
+                "data": item["data"],
+                "action": item.get("action", "upsert"),
+                "entityId": eid,
+                "actorId": item.get("actor_id") or actor or "sdk-writer",
+            }
+            sv = item.get("schema_version") or schema_ver
+            if sv:
+                entry["schemaVersion"] = sv
+            normalised.append(entry)
+
+        if self._mock:
+            return self._mock_batch_result(normalised, feed_label=feed_label)
+
+        payload: Dict[str, Any] = {"items": normalised}
+        if default_actor_id or self._default_actor_id:
+            payload["defaultActorId"] = default_actor_id or self._default_actor_id
+        if schema_ver:
+            payload["defaultSchemaVersion"] = schema_ver
+        if feed_label:
+            payload["feedLabel"] = feed_label
+
+        response_json = await self._post("/v1/write/batch", payload)
+        return self._parse_batch_response(response_json)
+
+    # ------------------------------------------------------------------
+    # BYOP Evidence fetch helpers
+    # ------------------------------------------------------------------
+
+    async def fetch_fx_rate(
+        self,
+        from_currency: str,
+        to_currency: str,
+        provider_id: str = "reuters-fx",
+        max_age_seconds: int = 300,
+    ) -> EvidenceItem:
+        """Fetch an FX rate oracle evidence item.
+
+        In mock mode returns a deterministic stub value (MYR/USD = 4.72).
+
+        Args:
+            from_currency: Source currency code (e.g. "MYR").
+            to_currency:   Target currency code (e.g. "USD").
+            provider_id:   Oracle provider ID (default "reuters-fx").
+            max_age_seconds: Max acceptable age in seconds (default 300).
+
+        Returns:
+            EvidenceItem ready to pass to check() or check_batch().
+        """
+        subject = {"from": from_currency, "to": to_currency}
+        if self._mock:
+            stub_rates = {"MYR_USD": 0.2119, "USD_MYR": 4.72, "EUR_USD": 1.085, "GBP_USD": 1.267}
+            key = f"{from_currency}_{to_currency}"
+            value = stub_rates.get(key, 1.0)
+            return EvidenceItem(
+                provider_id=provider_id,
+                provider_type="fx_rate",
+                subject=subject,
+                observed_value=value,
+                observed_at=__import__("datetime").datetime.now(__import__("datetime").timezone.utc).isoformat(),
+                max_age_seconds=max_age_seconds,
+                mock=True,
+            )
+        data = await self._get(f"/v1/oracle/fx-rate?from={from_currency}&to={to_currency}&providerId={provider_id}")
+        return EvidenceItem(
+            provider_id=data.get("providerId", provider_id),
+            provider_type="fx_rate",
+            subject=subject,
+            observed_value=data["observedValue"],
+            observed_at=data["observedAt"],
+            max_age_seconds=max_age_seconds,
+            proof_hash=data.get("proofHash"),
+            raw_proof_uri=data.get("rawProofUri"),
+            attestation=data.get("attestation"),
+        )
+
+    async def fetch_kyc_status(
+        self,
+        subject_id: str,
+        provider_id: str = "sumsub-kyc",
+        max_age_seconds: int = 86400,
+    ) -> EvidenceItem:
+        """Fetch a KYC status oracle evidence item.
+
+        Args:
+            subject_id:    The entity/wallet/account being KYC-checked.
+            provider_id:   Oracle provider ID (default "sumsub-kyc").
+            max_age_seconds: Max acceptable age (default 86400 = 24h).
+        """
+        subject = {"id": subject_id}
+        if self._mock:
+            return EvidenceItem(
+                provider_id=provider_id,
+                provider_type="kyc_status",
+                subject=subject,
+                observed_value="PASS",
+                observed_at=__import__("datetime").datetime.now(__import__("datetime").timezone.utc).isoformat(),
+                max_age_seconds=max_age_seconds,
+                mock=True,
+            )
+        data = await self._get(f"/v1/oracle/kyc-status?subjectId={subject_id}&providerId={provider_id}")
+        return EvidenceItem(
+            provider_id=data.get("providerId", provider_id),
+            provider_type="kyc_status",
+            subject=subject,
+            observed_value=data["observedValue"],
+            observed_at=data["observedAt"],
+            max_age_seconds=max_age_seconds,
+            proof_hash=data.get("proofHash"),
+            attestation=data.get("attestation"),
+        )
+
+    async def fetch_credit_score(
+        self,
+        subject_id: str,
+        provider_id: str = "coface-credit",
+        max_age_seconds: int = 86400,
+    ) -> EvidenceItem:
+        """Fetch a credit score oracle evidence item.
+
+        Args:
+            subject_id:    Entity being scored.
+            provider_id:   Oracle provider ID (default "coface-credit").
+            max_age_seconds: Max acceptable age (default 86400 = 24h).
+        """
+        subject = {"id": subject_id}
+        if self._mock:
+            return EvidenceItem(
+                provider_id=provider_id,
+                provider_type="credit_score",
+                subject=subject,
+                observed_value=720,
+                observed_at=__import__("datetime").datetime.now(__import__("datetime").timezone.utc).isoformat(),
+                max_age_seconds=max_age_seconds,
+                mock=True,
+            )
+        data = await self._get(f"/v1/oracle/credit-score?subjectId={subject_id}&providerId={provider_id}")
+        return EvidenceItem(
+            provider_id=data.get("providerId", provider_id),
+            provider_type="credit_score",
+            subject=subject,
+            observed_value=data["observedValue"],
+            observed_at=data["observedAt"],
+            max_age_seconds=max_age_seconds,
+            proof_hash=data.get("proofHash"),
+            attestation=data.get("attestation"),
+        )
+
+    async def fetch_sanctions(
+        self,
+        subject_id: str,
+        provider_id: str = "refinitiv-sanct",
+        max_age_seconds: int = 3600,
+    ) -> EvidenceItem:
+        """Fetch a sanctions screening oracle evidence item."""
+        subject = {"id": subject_id}
+        if self._mock:
+            return EvidenceItem(
+                provider_id=provider_id,
+                provider_type="sanctions",
+                subject=subject,
+                observed_value="CLEAR",
+                observed_at=__import__("datetime").datetime.now(__import__("datetime").timezone.utc).isoformat(),
+                max_age_seconds=max_age_seconds,
+                mock=True,
+            )
+        data = await self._get(f"/v1/oracle/sanctions?subjectId={subject_id}&providerId={provider_id}")
+        return EvidenceItem(
+            provider_id=data.get("providerId", provider_id),
+            provider_type="sanctions",
+            subject=subject,
+            observed_value=data["observedValue"],
+            observed_at=data["observedAt"],
+            max_age_seconds=max_age_seconds,
+            proof_hash=data.get("proofHash"),
+            attestation=data.get("attestation"),
+        )
+
+    async def check_with_evidence(
+        self,
+        entity_type: str,
+        data: Dict[str, Any],
+        evidence: List[EvidenceItem],
+        action: str = "CREATE",
+        entity_id: Optional[str] = None,
+        schema_version: Optional[str] = None,
+        actor_id: Optional[str] = None,
+    ) -> ComplianceResult:
+        """Submit a compliance check with oracle evidence attached.
+
+        Convenience wrapper around check() that serialises EvidenceItem objects
+        and bundles them in the write payload.
+
+        Example::
+
+            fx = await client.fetch_fx_rate("MYR", "USD")
+            kyc = await client.fetch_kyc_status("0x1234abcd")
+            result = await client.check_with_evidence(
+                "SukukBond",
+                {"issuerId": "...", "faceValue": 500000, "currency": "MYR"},
+                evidence=[fx, kyc],
+            )
+        """
+        eid = entity_id or str(uuid.uuid4())
+        schema_ver = schema_version or self._default_schema_version
+        actor = actor_id or self._default_actor_id
+
+        if self._mock:
+            return self._mock_single_result(eid)
+
+        item: Dict[str, Any] = {
+            "entityType": entity_type,
+            "data":       data,
+            "action":     action,
+            "entityId":   eid,
+            "actorId":    actor or "sdk-writer",
+            "evidence":   [e.to_dict() for e in evidence],
+        }
+        if schema_ver:
+            item["schemaVersion"] = schema_ver
+        payload = {"items": [item]}
+        response_json = await self._post("/v1/write/batch", payload)
+        return self._parse_batch_response(response_json).results[0]
+
+    async def verify(self, record_id: str, bearer_token: str) -> Dict[str, Any]:
+        """Retrieve an immutable compliance record from the ledger.
+
+        Args:
+            record_id: The record ID returned by a previous check() that passed.
+            bearer_token: A valid Bearer token for the TrustState API.
+
+        Returns:
+            The full record dict from the API.
+
+        Raises:
+            TrustStateError: On HTTP 4xx/5xx responses.
+        """
+        url = f"{self._base_url}/v1/records/{record_id}"
+        headers = {"Authorization": f"Bearer {bearer_token}"}
+
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            try:
+                resp = await client.get(url, headers=headers)
+            except httpx.RequestError as exc:
+                raise TrustStateError(f"Network error: {exc}") from exc
+
+        if resp.status_code >= 400:
+            raise TrustStateError(
+                f"API error {resp.status_code}: {resp.text}", resp.status_code
+            )
+
+        return resp.json()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _get(self, path: str) -> Dict[str, Any]:
+        """Make an authenticated GET request and return the JSON response body."""
+        url = f"{self._base_url}{path}"
+        headers = {"X-API-Key": self._api_key}
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            try:
+                resp = await client.get(url, headers=headers)
+            except httpx.RequestError as exc:
+                raise TrustStateError(f"Network error: {exc}") from exc
+        if resp.status_code >= 400:
+            raise TrustStateError(f"API error {resp.status_code}: {resp.text}", resp.status_code)
+        return resp.json()
+
+    async def _post(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Make an authenticated POST request and return the JSON response body."""
+        url = f"{self._base_url}{path}"
+        headers = {
+            "Content-Type": "application/json",
+            "X-API-Key": self._api_key,
+        }
+
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            try:
+                resp = await client.post(url, json=payload, headers=headers)
+            except httpx.RequestError as exc:
+                raise TrustStateError(f"Network error: {exc}") from exc
+
+        if resp.status_code >= 400:
+            raise TrustStateError(
+                f"API error {resp.status_code}: {resp.text}", resp.status_code
+            )
+
+        return resp.json()
+
+    def _parse_batch_response(self, data: Dict[str, Any]) -> BatchResult:
+        """Convert raw API JSON into a BatchResult."""
+        raw_results = data.get("results", [])
+        results = []
+        for r in raw_results:
+            accepted = r.get("status") == "accepted"
+            results.append(
+                ComplianceResult(
+                    passed=accepted,
+                    record_id=r.get("recordId"),
+                    request_id=r.get("requestId", ""),
+                    entity_id=r.get("entityId", ""),
+                    fail_reason=r.get("failReason"),
+                    failed_step=r.get("failedStep"),
+                    feed_label=r.get("feedLabel"),
+                    mock=False,
+                )
+            )
+
+        return BatchResult(
+            batch_id=data.get("batchId", str(uuid.uuid4())),
+            total=data.get("total", len(results)),
+            accepted=data.get("accepted", sum(1 for r in results if r.passed)),
+            rejected=data.get("rejected", sum(1 for r in results if not r.passed)),
+            results=results,
+            feed_label=data.get("feedLabel"),
+            mock=False,
+        )
+
+    # ------------------------------------------------------------------
+    # Mock helpers (no network calls)
+    # ------------------------------------------------------------------
+
+    def _mock_single_result(self, entity_id: str) -> ComplianceResult:
+        """Generate a synthetic ComplianceResult for mock mode."""
+        passed = random.random() < self._mock_pass_rate
+        return ComplianceResult(
+            passed=passed,
+            record_id=f"mock-rec-{uuid.uuid4()}" if passed else None,
+            request_id=f"mock-req-{uuid.uuid4()}",
+            entity_id=entity_id,
+            fail_reason=None if passed else "Mock: simulated policy failure",
+            failed_step=None if passed else 9,
+            mock=True,
+        )
+
+    def _mock_batch_result(self, normalised_items: List[Dict[str, Any]], feed_label: Optional[str] = None) -> BatchResult:
+        """Generate a synthetic BatchResult for mock mode."""
+        results = [
+            self._mock_single_result(item["entityId"]) for item in normalised_items
+        ]
+        for r in results:
+            r.feed_label = feed_label
+        accepted = sum(1 for r in results if r.passed)
+        return BatchResult(
+            batch_id=f"mock-batch-{uuid.uuid4()}",
+            total=len(results),
+            accepted=accepted,
+            rejected=len(results) - accepted,
+            results=results,
+            feed_label=feed_label,
+            mock=True,
+        )

truststate/decorators.py

@@ -0,0 +1,118 @@
+"""Decorators for automatic TrustState compliance checking.
+
+Usage::
+
+    from truststate import TrustStateClient, compliant
+
+    ts = TrustStateClient(api_key="your-key")
+
+    @compliant(ts, entity_type="AgentResponse", action="CREATE")
+    async def generate_response(customer_id: str) -> dict:
+        return {"responseText": "Hello!", "confidenceScore": 0.95}
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+import warnings
+from typing import Any, Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def compliant(
+    client: Any,  # TrustStateClient — avoid circular import
+    entity_type: str,
+    action: str = "CREATE",
+    data_fn: Optional[Callable[[Any], dict]] = None,
+    on_fail: str = "raise",
+) -> Callable:
+    """Decorator that submits the wrapped function's return value to TrustState.
+
+    The decorated function runs first; its return value is then submitted for
+    compliance validation. Depending on ``on_fail``, a failed check either raises
+    an exception, logs a warning, or returns None.
+
+    Args:
+        client: A TrustStateClient instance.
+        entity_type: The entity type to register with TrustState.
+        action: The action string — "CREATE", "UPDATE", or "DELETE".
+        data_fn: Optional mapping function: ``data_fn(return_value) -> dict``.
+            If omitted, the return value must already be a dict (or have ``__dict__``).
+        on_fail: Behaviour when compliance check fails:
+            - ``"raise"`` — raise TrustStateError (default).
+            - ``"warn"``  — log a warning and return the original value anyway.
+            - ``"return_none"`` — silently return None.
+
+    Returns:
+        Decorated async function.
+
+    Raises:
+        ValueError: If on_fail is not a recognised value.
+        TrustStateError: (when on_fail="raise") if the compliance check fails.
+    """
+    if on_fail not in ("raise", "warn", "return_none"):
+        raise ValueError(f"on_fail must be 'raise', 'warn', or 'return_none'; got {on_fail!r}")
+
+    def decorator(func: Callable) -> Callable:
+        if not inspect.iscoroutinefunction(func):
+            raise TypeError(
+                f"@compliant requires an async function; {func.__name__} is not async."
+            )
+
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Run the original function
+            result = await func(*args, **kwargs)
+
+            # Convert result to dict for submission
+            if data_fn is not None:
+                data = data_fn(result)
+            elif isinstance(result, dict):
+                data = result
+            elif hasattr(result, "__dict__"):
+                data = result.__dict__
+            else:
+                raise TypeError(
+                    f"Cannot extract dict from return value of {func.__name__}. "
+                    "Provide a data_fn or return a dict/dataclass."
+                )
+
+            # Submit to TrustState
+            compliance = await client.check(
+                entity_type=entity_type,
+                data=data,
+                action=action,
+            )
+
+            if compliance.passed:
+                return result
+
+            # Handle failure
+            if on_fail == "raise":
+                from .exceptions import TrustStateError
+                raise TrustStateError(
+                    f"Compliance check failed for {entity_type}: "
+                    f"{compliance.fail_reason} (step {compliance.failed_step})"
+                )
+            elif on_fail == "warn":
+                warnings.warn(
+                    f"TrustState compliance failed for {entity_type} "
+                    f"(entity_id={compliance.entity_id}): {compliance.fail_reason}",
+                    stacklevel=2,
+                )
+                return result
+            else:  # return_none
+                logger.debug(
+                    "Compliance failed for %s entity_id=%s reason=%s — returning None",
+                    entity_type,
+                    compliance.entity_id,
+                    compliance.fail_reason,
+                )
+                return None
+
+        return wrapper
+
+    return decorator

truststate/exceptions.py

@@ -0,0 +1,18 @@
+"""Custom exceptions for the TrustState SDK."""
+
+
+class TrustStateError(Exception):
+    """Raised when the TrustState API returns an error response.
+
+    Attributes:
+        message: Human-readable description of the error.
+        status_code: HTTP status code returned by the API (if applicable).
+    """
+
+    def __init__(self, message: str, status_code: int = 0) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+    def __repr__(self) -> str:
+        return f"TrustStateError(message={self.message!r}, status_code={self.status_code})"

truststate/middleware.py

@@ -0,0 +1,127 @@
+"""FastAPI middleware for automatic TrustState compliance checking.
+
+Usage::
+
+    from fastapi import FastAPI
+    from truststate import TrustStateClient, TrustStateMiddleware
+
+    app = FastAPI()
+    client = TrustStateClient(api_key="your-key")
+    app.add_middleware(TrustStateMiddleware, client=client)
+
+Any request that includes the ``X-Compliance-Entity-Type`` header will have its
+body submitted to TrustState before being passed to the route handler.
+A failed compliance check returns HTTP 422.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+try:
+    from starlette.middleware.base import BaseHTTPMiddleware
+    from starlette.requests import Request
+    from starlette.responses import JSONResponse, Response
+    from starlette.types import ASGIApp
+
+    _STARLETTE_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _STARLETTE_AVAILABLE = False
+    BaseHTTPMiddleware = object  # type: ignore[misc,assignment]
+
+
+class TrustStateMiddleware(BaseHTTPMiddleware):  # type: ignore[misc]
+    """FastAPI/Starlette middleware that gates requests on TrustState compliance.
+
+    Inspects two custom headers on every incoming request:
+
+    - ``X-Compliance-Entity-Type``: The TrustState entity type to validate against.
+    - ``X-Compliance-Action``: The action string (default "CREATE").
+
+    If ``X-Compliance-Entity-Type`` is present, the raw request body is parsed as
+    JSON and submitted to TrustState. The request is allowed through only if the
+    compliance check passes; otherwise a 422 response is returned immediately.
+
+    Args:
+        app: The ASGI application to wrap.
+        client: A TrustStateClient instance.
+        entity_id_header: Optional request header that carries a stable entity ID.
+            If absent, one is auto-generated per request.
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        client: Any,  # TrustStateClient — avoid circular import
+        entity_id_header: str = "X-Compliance-Entity-Id",
+    ) -> None:
+        if not _STARLETTE_AVAILABLE:
+            raise ImportError(
+                "starlette is required for TrustStateMiddleware. "
+                "Install it with: pip install starlette"
+            )
+        super().__init__(app)
+        self._client = client
+        self._entity_id_header = entity_id_header
+
+    async def dispatch(self, request: Request, call_next: Any) -> Response:
+        entity_type: Optional[str] = request.headers.get("X-Compliance-Entity-Type")
+
+        # Pass through if the compliance header is absent
+        if not entity_type:
+            return await call_next(request)
+
+        action = request.headers.get("X-Compliance-Action", "CREATE")
+        entity_id = request.headers.get(self._entity_id_header)
+
+        # Read and parse the request body
+        try:
+            raw_body = await request.body()
+            data = json.loads(raw_body) if raw_body else {}
+        except (json.JSONDecodeError, ValueError) as exc:
+            logger.warning("TrustStateMiddleware: failed to parse request body: %s", exc)
+            return JSONResponse(
+                {"error": "Invalid JSON body for compliance check"},
+                status_code=400,
+            )
+
+        # Run compliance check
+        try:
+            result = await self._client.check(
+                entity_type=entity_type,
+                data=data,
+                action=action,
+                entity_id=entity_id or None,
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.error("TrustStateMiddleware: compliance check error: %s", exc)
+            return JSONResponse(
+                {"error": "Compliance service unavailable", "detail": str(exc)},
+                status_code=503,
+            )
+
+        if not result.passed:
+            logger.info(
+                "TrustStateMiddleware: blocked request — entity_type=%s reason=%s",
+                entity_type,
+                result.fail_reason,
+            )
+            return JSONResponse(
+                {
+                    "error": "Compliance check failed",
+                    "fail_reason": result.fail_reason,
+                    "failed_step": result.failed_step,
+                    "entity_id": result.entity_id,
+                },
+                status_code=422,
+            )
+
+        # Attach the record ID so downstream handlers can use it
+        response = await call_next(request)
+        if result.record_id:
+            response.headers["X-Compliance-Record-Id"] = result.record_id
+        return response

truststate/types.py

@@ -0,0 +1,112 @@
+"""Data types for the TrustState SDK.
+
+This module defines the result dataclasses returned by TrustStateClient.
+"""
+
+from __future__ import annotations
+
+import uuid as _uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ComplianceResult:
+    """Result of a single compliance check.
+
+    Attributes:
+        passed: True if the record passed all compliance checks.
+        record_id: Immutable ledger record ID — only set when passed=True.
+        request_id: Unique ID for this API request (useful for support/debugging).
+        entity_id: The entity ID that was submitted (caller-supplied or auto-generated).
+        fail_reason: Human-readable reason for failure — only set when passed=False.
+        failed_step: Numeric step that failed (8=schema validation, 9=policy check).
+        feed_label: The feed label from the batch request — useful for multi-feed pipelines.
+        mock: True when the result was synthesised locally in mock mode (no HTTP call made).
+    """
+
+    passed: bool
+    record_id: Optional[str]
+    request_id: str
+    entity_id: str
+    fail_reason: Optional[str]
+    failed_step: Optional[int]
+    feed_label: Optional[str] = None
+    mock: bool = False
+
+
+@dataclass
+class EvidenceItem:
+    """A single oracle evidence item to be submitted alongside a write.
+
+    Attributes:
+        evidence_id: Unique ID for this evidence item (auto-generated if not provided).
+        provider_id: Registered oracle provider ID (e.g. "reuters-fx").
+        provider_type: Oracle provider type (e.g. "fx_rate", "kyc_status").
+        subject: Key-value dict identifying the data subject (e.g. {"from": "MYR", "to": "USD"}).
+        observed_value: The oracle-reported value (numeric or string).
+        observed_at: ISO-8601 timestamp when the value was observed by the oracle.
+        retrieved_at: ISO-8601 timestamp when you fetched this value (defaults to now).
+        max_age_seconds: Maximum acceptable age of this evidence in seconds (default 300).
+        proof_hash: Optional sha256:<hex> hash of the raw proof document.
+        raw_proof_uri: Optional URL to the raw proof document for background verification.
+        attestation: Optional dict with ``type``, ``algorithm``, ``signature`` fields.
+        mock: True when synthesised locally (no real oracle call).
+    """
+
+    provider_id: str
+    provider_type: str
+    subject: Dict[str, Any]
+    observed_value: Any
+    observed_at: str
+    evidence_id: str = field(default_factory=lambda: str(_uuid.uuid4()))
+    retrieved_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    max_age_seconds: int = 300
+    proof_hash: Optional[str] = None
+    raw_proof_uri: Optional[str] = None
+    attestation: Optional[Dict[str, Any]] = None
+    mock: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialise to the wire format expected by the TrustState API."""
+        d: Dict[str, Any] = {
+            "evidenceId":     self.evidence_id,
+            "providerId":     self.provider_id,
+            "providerType":   self.provider_type,
+            "subject":        self.subject,
+            "observedValue":  self.observed_value,
+            "observedAt":     self.observed_at,
+            "retrievedAt":    self.retrieved_at,
+            "maxAgeSeconds":  self.max_age_seconds,
+        }
+        if self.proof_hash:
+            d["proofHash"] = self.proof_hash
+        if self.raw_proof_uri:
+            d["rawProofUri"] = self.raw_proof_uri
+        if self.attestation:
+            d["attestation"] = self.attestation
+        return d
+
+
+@dataclass
+class BatchResult:
+    """Aggregated result for a batch compliance submission.
+
+    Attributes:
+        batch_id: Unique ID for this batch request.
+        total: Total number of items submitted.
+        accepted: Number of items that passed compliance checks.
+        rejected: Number of items that failed compliance checks.
+        results: Per-item ComplianceResult list (same order as submitted items).
+        feed_label: The feed label for this batch (echoed from request).
+        mock: True when running in mock mode (no HTTP calls made).
+    """
+
+    batch_id: str
+    total: int
+    accepted: int
+    rejected: int
+    results: List[ComplianceResult]
+    feed_label: Optional[str] = None
+    mock: bool = False

truststate-0.2.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: truststate
+Version: 0.2.0
+Summary: Python SDK for TrustState compliance validation
+License: MIT
+Project-URL: Homepage, https://trustchainlabs.com
+Project-URL: Repository, https://github.com/MyreneBot/truststate-py
+Project-URL: Bug Tracker, https://github.com/MyreneBot/truststate-py/issues
+Keywords: compliance,AI governance,truststate,audit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: dataclasses-json>=0.6
+Provides-Extra: fastapi
+Requires-Dist: starlette>=0.27; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# TrustState Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/truststate.svg)](https://pypi.org/project/truststate/)
+[![Python](https://img.shields.io/pypi/pyversions/truststate.svg)](https://pypi.org/project/truststate/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Python SDK for the [TrustState](https://truststate.apps.trustchainlabs.com) compliance API — validate, audit, and enforce compliance rules on any entity or data record. Built for financial services, AI governance, and regulated industries.
+
+## Install
+
+```bash
+pip install truststate
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+import asyncio
+from truststate import TrustStateClient
+
+client = TrustStateClient(api_key="ts_your_api_key")
+
+async def main():
+    result = await client.check(
+        entity_type="SukukBond",
+        data={
+            "id": "BOND-001",
+            "issuerId": "ISS-001",
+            "currency": "MYR",
+            "faceValue": 5_000_000,
+            "maturityDate": "2030-06-01",
+            "status": "DRAFT",
+        },
+    )
+
+    if result.passed:
+        print(f"✅ Passed — record ID: {result.record_id}")
+    else:
+        print(f"❌ Failed — {result.fail_reason} (step {result.failed_step})")
+
+asyncio.run(main())
+```
+
+## Batch Writes
+
+Submit multiple records in a single API call. Useful for feed-based pipelines.
+
+```python
+result = await client.check_batch(
+    items=[
+        {"entity_type": "SukukBond", "data": {"id": "BOND-001", ...}},
+        {"entity_type": "SukukBond", "data": {"id": "BOND-002", ...}},
+        {"entity_type": "SukukBond", "data": {"id": "BOND-003", ...}},
+    ],
+    feed_label="core-banking-feed",   # echoed on every item result
+)
+
+print(f"Accepted: {result.accepted}/{result.total}")
+for item in result.results:
+    print(f"  {item.entity_id}: {'✅' if item.passed else '❌'} {item.feed_label}")
+```
+
+## BYOP Evidence (Oracle Data)
+
+Attach oracle evidence to compliance checks — FX rates, KYC status, credit scores, sanctions screening.
+
+```python
+# Fetch evidence from registered oracle providers
+fx    = await client.fetch_fx_rate("MYR", "USD")
+kyc   = await client.fetch_kyc_status("actor-jasim")
+score = await client.fetch_credit_score("actor-jasim")
+
+# Submit with evidence attached
+result = await client.check_with_evidence(
+    entity_type="SukukBond",
+    data={"id": "BOND-001", "issuerId": "ISS-001", "currency": "MYR", "faceValue": 5_000_000},
+    evidence=[fx, kyc, score],
+)
+```
+
+## Mock Mode
+
+Test without making any API calls. Useful for unit tests and local development.
+
+```python
+client = TrustStateClient(
+    api_key="any",
+    mock=True,
+    mock_pass_rate=0.8,   # 80% of checks will pass
+)
+
+result = await client.check("SukukBond", {"id": "TEST-001", ...})
+print(result.mock)   # True
+```
+
+## Django / FastAPI Middleware
+
+Automatically validate every incoming request body against TrustState policies.
+
+```python
+# FastAPI
+from truststate import TrustStateMiddleware
+
+app.add_middleware(
+    TrustStateMiddleware,
+    api_key="ts_your_api_key",
+    entity_type="AgentResponse",
+)
+
+# Django
+MIDDLEWARE = [
+    "truststate.middleware.TrustStateMiddleware",
+    ...
+]
+TRUSTSTATE_API_KEY = "ts_your_api_key"
+TRUSTSTATE_ENTITY_TYPE = "AgentResponse"
+```
+
+## `@compliant` Decorator
+
+Wrap any async function to automatically submit its return value for compliance checking.
+
+```python
+from truststate import compliant, TrustStateClient
+
+client = TrustStateClient(api_key="ts_your_api_key")
+
+@compliant(client=client, entity_type="AgentResponse")
+async def generate_response(prompt: str) -> dict:
+    return {"text": "Hello!", "score": 0.95}
+
+result = await generate_response("What is TrustState?")
+# result is a ComplianceResult — .passed, .record_id, etc.
+```
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str` | required | Your TrustState API key |
+| `base_url` | `str` | production URL | Override the API base URL |
+| `default_schema_version` | `str \| None` | `None` | Schema version (auto-resolved if omitted) |
+| `default_actor_id` | `str` | `""` | Actor ID for the audit trail |
+| `mock` | `bool` | `False` | Enable mock mode (no HTTP calls) |
+| `mock_pass_rate` | `float` | `1.0` | Pass probability in mock mode (0.0–1.0) |
+| `timeout` | `int` | `30` | HTTP timeout in seconds |
+
+## API Reference
+
+### `check(entity_type, data, *, action, entity_id, schema_version, actor_id)`
+
+Submit a single record for compliance checking.
+
+Returns: `ComplianceResult`
+
+### `check_batch(items, *, default_schema_version, default_actor_id, feed_label)`
+
+Submit up to 500 records in a single call.
+
+Returns: `BatchResult`
+
+### `check_with_evidence(entity_type, data, evidence, *, action, entity_id, schema_version, actor_id)`
+
+Submit a record with oracle evidence attached.
+
+Returns: `ComplianceResult`
+
+### `fetch_fx_rate(from_currency, to_currency, *, provider_id, max_age_seconds)`
+### `fetch_kyc_status(subject_id, *, provider_id, max_age_seconds)`
+### `fetch_credit_score(subject_id, *, provider_id, max_age_seconds)`
+### `fetch_sanctions(subject_id, *, provider_id, max_age_seconds)`
+
+Fetch oracle evidence items from registered providers.
+
+Returns: `EvidenceItem`
+
+### `verify(record_id, bearer_token)`
+
+Retrieve an immutable compliance record from the ledger.
+
+Returns: `dict`
+
+## ComplianceResult
+
+| Field | Type | Description |
+|---|---|---|
+| `passed` | `bool` | True if all checks passed |
+| `record_id` | `str \| None` | Immutable ledger record ID (only when passed) |
+| `request_id` | `str` | Unique API request ID |
+| `entity_id` | `str` | Entity ID that was submitted |
+| `fail_reason` | `str \| None` | Human-readable failure reason |
+| `failed_step` | `int \| None` | Step that failed (8=schema, 9=policy) |
+| `feed_label` | `str \| None` | Feed label from batch request |
+| `mock` | `bool` | True if synthesised in mock mode |
+
+## Requirements
+
+- Python 3.9+
+- `httpx>=0.27`
+
+## License
+
+MIT © Trustchain Labs

truststate-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+truststate/__init__.py,sha256=RkDdM4_OqTgHIZVmMj1mOF7eCuJ8xtf7jJf8WGSa25c,903
+truststate/client.py,sha256=aq_KXiXivXFpeYcWZFo5ZxlAtMVrdDvK5ydoHXnJVQU,19577
+truststate/decorators.py,sha256=oWImPCKN64X8bGs-ABXrn2hFdQHOgWzNpKudNesqOTs,4214
+truststate/exceptions.py,sha256=gm27qY_kq3vbULR-7ZxP2anqC-DO8nEItcOM2g1kauU,604
+truststate/middleware.py,sha256=Zv2aHgJY8oIXLWhfN-AK9GTboHD_IU2gQeGgSf8_mvI,4607
+truststate/types.py,sha256=buX2PI9C-DfWLwc5DM8ja64ebiE21A6hb4NjN5R_MJg,4398
+truststate-0.2.0.dist-info/licenses/LICENSE,sha256=3kMyI1A8h3bMejvRDgRx58bQT1KauBLKEnqxXMZX-tk,1066
+truststate-0.2.0.dist-info/METADATA,sha256=f25K45vkgtvcJibDD5BXnRbQVGqU0Bp-6p1eWC8Pv6k,7190
+truststate-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+truststate-0.2.0.dist-info/top_level.txt,sha256=YNcW7zAANI3PMnRsT4IBqd-Z0ZDlkcSCki0hnUCLSeM,11
+truststate-0.2.0.dist-info/RECORD,,

truststate-0.2.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
+

truststate-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyreneBot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

truststate-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+truststate