axorum-client 0.1.0__py3-none-any.whl

axorum/__init__.py

@@ -0,0 +1,152 @@
+"""The official Python client for the Axorum agent plane.
+
+Axorum is a deontic financial-control ledger: an agent submits an *intent*, and
+the policy in force permits or refuses it. This package speaks that protocol.
+
+The one rule
+------------
+**A policy refusal is not an error.** An intent the policy in force forbids is
+still committed, still judged, and still *recorded* — and that recording is the
+product. It arrives as an :class:`AgentOutcome` with ``posted`` false and
+``verdict`` ``ForbiddenRejected``, over a ``200``::
+
+    from axorum import ActionTerm, Amount, AxorumClient, Entry, IntentDraft
+
+    with AxorumClient("http://127.0.0.1:8080") as client:
+        outcome = client.submit_pinned(
+            IntentDraft(
+                agent="agent://example.com/agent/clerk_01h455vb4pex5vsknk084sn02q",
+                attestation=token,
+                action=ActionTerm("post"),
+                entries=[
+                    Entry.debit(cash, Amount(1000, "USD")),
+                    Entry.credit(revenue, Amount(1000, "USD")),
+                ],
+                justification="settling invoice 42",
+            )
+        )
+
+        if outcome.posted:
+            print("permitted, and the entries posted")
+        else:
+            # Not a failure. The ledger recorded a refusal, which is what you
+            # asked it to do.
+            print(f"refused, and the refusal is on the ledger: {outcome.verdict}")
+
+An :class:`AxorumError` means the ledger never got to answer at all: the caller
+was not who they claimed, the pin did not hold, the cluster could not confirm,
+the wire broke.
+
+Sync or async, one protocol
+---------------------------
+:class:`AxorumClient` blocks; :class:`AsyncAxorumClient` awaits. They are shells
+over :mod:`axorum.protocol`, where every request builder, every response decoder,
+and the policy-pin loop itself are pure functions — so the two clients cannot
+drift, and the protocol is testable without a socket.
+"""
+
+from .client import DEFAULT_TIMEOUT, AsyncAxorumClient, AxorumClient
+from .errors import (
+    ApiError,
+    AttestationError,
+    AxorumError,
+    CommitUnavailableError,
+    ConfigError,
+    DecodeError,
+    NoActivePolicyError,
+    NotPrimaryError,
+    StalePolicyError,
+    TransportError,
+    UnexpectedResponseError,
+    UnknownAgentError,
+)
+from .ids import (
+    ACCOUNT_PREFIX,
+    POLICY_PREFIX,
+    TRANSACTION_PREFIX,
+    InvalidIdError,
+    new_transaction_id,
+    typeid_from_uuid,
+    uuid_from_typeid,
+)
+from .models import (
+    ActionTerm,
+    ActivePolicyResponse,
+    AgentOutcome,
+    Amount,
+    BalanceResponse,
+    Entry,
+    IntentDraft,
+    IntentEnvelope,
+    JsonValue,
+    MasterDataBasis,
+    ObligationInstance,
+    ObligationOutcomes,
+    ObligationsResponse,
+    ObligationState,
+    OutcomeProvenance,
+    Provenance,
+    ReferenceSet,
+    Side,
+    TransactionRecord,
+    Value,
+    ValueKind,
+    Verdict,
+)
+from .protocol import MAX_PINS, REQUEST_ID_HEADER, Request, error_from, interpret, pin_flow
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ACCOUNT_PREFIX",
+    "DEFAULT_TIMEOUT",
+    "MAX_PINS",
+    "POLICY_PREFIX",
+    "REQUEST_ID_HEADER",
+    "TRANSACTION_PREFIX",
+    "ActionTerm",
+    "ActivePolicyResponse",
+    "AgentOutcome",
+    "Amount",
+    "ApiError",
+    "AsyncAxorumClient",
+    "AttestationError",
+    "AxorumClient",
+    "AxorumError",
+    "BalanceResponse",
+    "CommitUnavailableError",
+    "ConfigError",
+    "DecodeError",
+    "Entry",
+    "IntentDraft",
+    "IntentEnvelope",
+    "InvalidIdError",
+    "JsonValue",
+    "MasterDataBasis",
+    "NoActivePolicyError",
+    "NotPrimaryError",
+    "ObligationInstance",
+    "ObligationOutcomes",
+    "ObligationState",
+    "ObligationsResponse",
+    "OutcomeProvenance",
+    "Provenance",
+    "ReferenceSet",
+    "Request",
+    "Side",
+    "StalePolicyError",
+    "TransactionRecord",
+    "TransportError",
+    "UnexpectedResponseError",
+    "UnknownAgentError",
+    "Value",
+    "ValueKind",
+    "Verdict",
+    "__version__",
+    "error_from",
+    "interpret",
+    "new_transaction_id",
+    "pin_flow",
+    "typeid_from_uuid",
+    "uuid_from_typeid",
+]

axorum/client.py

@@ -0,0 +1,408 @@
+"""The sync and async clients — thin shells over :mod:`axorum.protocol`.
+
+Both clients hold an httpx client and nothing else. Every decision about what to
+send and what a response means lives in :mod:`axorum.protocol` as a pure
+function, so the two are the same client twice: one that blocks and one that
+awaits. They cannot drift, because there is only one implementation of the
+protocol to drift from.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import TypeVar
+
+import httpx
+
+from .errors import ConfigError, NoActivePolicyError, StalePolicyError, TransportError
+from .models import (
+    AgentOutcome,
+    BalanceResponse,
+    IntentDraft,
+    IntentEnvelope,
+    ObligationsResponse,
+    TransactionRecord,
+)
+from .protocol import (
+    MAX_PINS,
+    Request,
+    build_active_policy,
+    build_balance,
+    build_obligations,
+    build_submit_intent,
+    build_transaction,
+    interpret_active_policy,
+    interpret_balance,
+    interpret_obligations,
+    interpret_outcome,
+    interpret_transaction,
+    normalize_base_url,
+    pin_flow,
+)
+
+__all__ = ["AsyncAxorumClient", "AxorumClient"]
+
+_Self = TypeVar("_Self", bound="AxorumClient")
+_AsyncSelf = TypeVar("_AsyncSelf", bound="AsyncAxorumClient")
+
+DEFAULT_TIMEOUT = 10.0
+"""The per-request timeout, in seconds."""
+
+
+def _auth_headers(bearer_token: str | None) -> dict[str, str]:
+    """Build the headers every request carries.
+
+    The agent plane does not *require* a bearer token — an agent authenticates
+    with the PASETO attestation *inside* the envelope, not at the transport layer.
+    This is here for a deployment that fronts the plane with a gateway that does.
+    """
+    if bearer_token is None:
+        return {}
+    if not bearer_token.strip():
+        raise ConfigError("the bearer token is empty")
+    return {"authorization": f"Bearer {bearer_token}"}
+
+
+class AxorumClient:
+    """A typed, synchronous client for the Axorum agent plane.
+
+    Usable as a context manager, which is the recommended form — it closes the
+    connection pool on the way out::
+
+        with AxorumClient("http://127.0.0.1:8080") as client:
+            outcome = client.submit_pinned(draft)
+
+            # A refusal is a RETURN VALUE, not an exception. Branch on the
+            # outcome, never on a status code.
+            if outcome.posted:
+                print("recorded and posted")
+            else:
+                print(f"recorded as refused: {outcome.verdict}")
+
+    Args:
+        base_url: The service root, e.g. ``http://127.0.0.1:8080``.
+        bearer_token: Sent as ``Authorization: Bearer …`` on every request, for a
+            deployment that fronts the plane with a gateway that wants one.
+        timeout: The per-request timeout, in seconds.
+        transport: An httpx transport to use instead of the network — the seam
+            unit tests drive the client through.
+
+    Raises:
+        ConfigError: if the base URL or the token is unusable.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        bearer_token: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        """Build a client for the service rooted at `base_url`."""
+        self._base_url = normalize_base_url(base_url)
+        self._headers = _auth_headers(bearer_token)
+        self._http = httpx.Client(timeout=timeout, transport=transport)
+
+    def __enter__(self: _Self) -> _Self:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the connection pool."""
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying connection pool."""
+        self._http.close()
+
+    def _send(self, request: Request) -> tuple[int, str]:
+        """Send one request and return ``(status, body)`` — the only I/O in this class.
+
+        The body comes back as text, never pre-parsed, so a response that will not
+        decode can be shown to a human verbatim.
+        """
+        try:
+            response = self._http.request(
+                request.method,
+                request.url,
+                headers={**self._headers, **request.headers},
+                params=dict(request.params) or None,
+                json=request.json,
+            )
+        except httpx.HTTPError as failure:
+            raise TransportError(str(failure)) from failure
+        return response.status_code, response.text
+
+    def active_policy(self) -> str | None:
+        """Read the id of the policy currently in force, or ``None`` if none is.
+
+        ``None`` is **not** an error — the service answers ``200 {"policy": null}``,
+        and "no policy is in force" is a true and useful fact about a ledger, not a
+        failure to report one.
+
+        This is the endpoint to re-read after a ``409``; :meth:`submit_pinned` does
+        that for you.
+
+        Raises:
+            TransportError: if the service cannot be reached.
+        """
+        status, body = self._send(build_active_policy(self._base_url))
+        return interpret_active_policy(status, body)
+
+    def submit_intent(self, envelope: IntentEnvelope) -> AgentOutcome:
+        """Submit an intent envelope and return the ledger's outcome.
+
+        **A refusal is a return value.** If the policy in force forbids the action,
+        this returns an :class:`~axorum.AgentOutcome` with ``posted`` false and a
+        ``ForbiddenRejected`` verdict, over a ``200``. The intent reached the commit
+        point, was judged, and the refusal was *recorded* — that record is the
+        product. Branch on ``posted``/``verdict``; an exception here means the
+        ledger never got to answer at all.
+
+        Re-submitting a ``transaction`` id that already committed replays its stored
+        outcome rather than double-posting — the id is the substrate's idempotency
+        key — which is what makes retrying a submission safe.
+
+        Raises:
+            StalePolicyError: if the pin did not hold. Use :meth:`submit_pinned` to
+                handle that automatically.
+            UnknownAgentError: if the ``agent://`` URI is not bound to a party.
+            AttestationError: if the capability attestation was rejected.
+            NotPrimaryError: if a cluster mutation reached a follower. This client
+                **never** follows the redirect for you.
+            CommitUnavailableError: if a cluster commit could not be confirmed.
+            TransportError: if the service cannot be reached.
+        """
+        status, body = self._send(build_submit_intent(self._base_url, envelope))
+        return interpret_outcome(status, body)
+
+    def submit_pinned(self, draft: IntentDraft, *, max_pins: int = MAX_PINS) -> AgentOutcome:
+        """Fetch the active policy, pin the draft to it, submit — and re-pin if it moved.
+
+        This is the loop every correct agent writes, so it ships in the client
+        rather than in each caller. It is safe to retry for one specific reason:
+        the ``transaction`` id was minted **once**, on the draft, before the first
+        attempt, and is the substrate's idempotency key. Every re-pinned attempt
+        carries the same id, so an attempt that in fact landed replays its stored
+        outcome. The loop cannot double-post.
+
+        A refusal is still a return value (see :meth:`submit_intent`), and a ``421``
+        is still raised: following a redirect to another replica is the caller's
+        decision, not the client's.
+
+        Raises:
+            NoActivePolicyError: if no policy is in force — there is nothing to pin to.
+            StalePolicyError: if the policy kept moving out from under `max_pins`
+                attempts.
+            AxorumError: anything :meth:`submit_intent` raises.
+        """
+        policy = self.active_policy()
+        if policy is None:
+            raise NoActivePolicyError("no policy is in force, so an intent cannot be pinned to one")
+        return self.submit_pinned_from(draft, policy, max_pins=max_pins)
+
+    def submit_pinned_from(
+        self, draft: IntentDraft, policy: str, *, max_pins: int = MAX_PINS
+    ) -> AgentOutcome:
+        """:meth:`submit_pinned`, but starting from a policy you already believe is in force.
+
+        This is the shape a long-running agent actually wants. Reading
+        ``GET /policies/active`` before *every* submission is a round trip spent
+        re-learning something that changes rarely; an agent can hold the last policy
+        it saw, submit straight against it, and let the ``409`` tell it when its
+        belief went stale. The recovery is the same loop either way, so caching costs
+        nothing in correctness — the service remains the authority, it is simply
+        consulted only when it disagrees.
+
+        Raises:
+            StalePolicyError: if the policy kept moving out from under `max_pins`
+                attempts.
+            AxorumError: anything :meth:`submit_intent` raises.
+        """
+        flow = pin_flow(draft, policy, max_pins=max_pins)
+        envelope = next(flow)
+        while True:
+            try:
+                return self.submit_intent(envelope)
+            except StalePolicyError as failure:
+                envelope = flow.send(failure)
+
+    def transaction(self, transaction: str) -> TransactionRecord:
+        """Read the stored record for a committed transaction.
+
+        Reading it is the idempotent replay lookup: it tells you what a
+        previously-submitted ``transaction`` id did, **without resubmitting it**. A
+        recorded refusal is here like any other record, with ``posted`` false.
+
+        The record is contractually opaque in this version of the wire contract, so
+        it comes back as parsed JSON.
+
+        Raises:
+            ApiError: with code ``unknown_transaction`` (404) if there is no such
+                transaction, or ``invalid_transaction_id`` (400) if that is not one.
+            TransportError: if the service cannot be reached.
+        """
+        status, body = self._send(build_transaction(self._base_url, transaction))
+        return interpret_transaction(status, body)
+
+    def obligations(self, actor: str) -> ObligationsResponse:
+        """Read the open obligations an actor owes.
+
+        `actor` may be a party id (``party_…``) **or** a DSL party name; the service
+        resolves either, and echoes back exactly what you supplied. An unknown or
+        duty-free actor is not an error — it answers with an empty list.
+
+        Raises:
+            TransportError: if the service cannot be reached.
+        """
+        status, body = self._send(build_obligations(self._base_url, actor))
+        return interpret_obligations(status, body)
+
+    def balance(self, account: str) -> BalanceResponse:
+        """Read an account's net balance, in minor units.
+
+        Raises:
+            ApiError: with code ``unknown_account`` (404) if there is no such account,
+                or ``invalid_account_id`` (400) if that is not one.
+            TransportError: if the service cannot be reached.
+        """
+        status, body = self._send(build_balance(self._base_url, account))
+        return interpret_balance(status, body)
+
+
+class AsyncAxorumClient:
+    """A typed, asynchronous client for the Axorum agent plane.
+
+    The same client as :class:`AxorumClient`, awaited. Every method has the same
+    name, the same arguments, and the same semantics — above all the one that
+    matters: **a refusal is a return value, not an exception**::
+
+        async with AsyncAxorumClient("http://127.0.0.1:8080") as client:
+            outcome = await client.submit_pinned(draft)
+            if not outcome.posted:
+                print(f"recorded as refused: {outcome.verdict}")
+
+    Args:
+        base_url: The service root, e.g. ``http://127.0.0.1:8080``.
+        bearer_token: Sent as ``Authorization: Bearer …`` on every request.
+        timeout: The per-request timeout, in seconds.
+        transport: An httpx transport to use instead of the network.
+
+    Raises:
+        ConfigError: if the base URL or the token is unusable.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        bearer_token: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        """Build a client for the service rooted at `base_url`."""
+        self._base_url = normalize_base_url(base_url)
+        self._headers = _auth_headers(bearer_token)
+        self._http = httpx.AsyncClient(timeout=timeout, transport=transport)
+
+    async def __aenter__(self: _AsyncSelf) -> _AsyncSelf:
+        """Enter the async context manager."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the connection pool."""
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying connection pool."""
+        await self._http.aclose()
+
+    async def _send(self, request: Request) -> tuple[int, str]:
+        """Send one request and return ``(status, body)`` — the only I/O in this class."""
+        try:
+            response = await self._http.request(
+                request.method,
+                request.url,
+                headers={**self._headers, **request.headers},
+                params=dict(request.params) or None,
+                json=request.json,
+            )
+        except httpx.HTTPError as failure:
+            raise TransportError(str(failure)) from failure
+        return response.status_code, response.text
+
+    async def active_policy(self) -> str | None:
+        """Read the id of the policy currently in force, or ``None`` if none is.
+
+        ``None`` is **not** an error. See :meth:`AxorumClient.active_policy`.
+        """
+        status, body = await self._send(build_active_policy(self._base_url))
+        return interpret_active_policy(status, body)
+
+    async def submit_intent(self, envelope: IntentEnvelope) -> AgentOutcome:
+        """Submit an intent envelope and return the ledger's outcome.
+
+        **A refusal is a return value.** See :meth:`AxorumClient.submit_intent`.
+        """
+        status, body = await self._send(build_submit_intent(self._base_url, envelope))
+        return interpret_outcome(status, body)
+
+    async def submit_pinned(self, draft: IntentDraft, *, max_pins: int = MAX_PINS) -> AgentOutcome:
+        """Fetch the active policy, pin the draft to it, submit — and re-pin if it moved.
+
+        See :meth:`AxorumClient.submit_pinned`.
+        """
+        policy = await self.active_policy()
+        if policy is None:
+            raise NoActivePolicyError("no policy is in force, so an intent cannot be pinned to one")
+        return await self.submit_pinned_from(draft, policy, max_pins=max_pins)
+
+    async def submit_pinned_from(
+        self, draft: IntentDraft, policy: str, *, max_pins: int = MAX_PINS
+    ) -> AgentOutcome:
+        """:meth:`submit_pinned`, but starting from a policy you already believe is in force.
+
+        See :meth:`AxorumClient.submit_pinned_from`.
+        """
+        flow = pin_flow(draft, policy, max_pins=max_pins)
+        envelope = next(flow)
+        while True:
+            try:
+                return await self.submit_intent(envelope)
+            except StalePolicyError as failure:
+                envelope = flow.send(failure)
+
+    async def transaction(self, transaction: str) -> TransactionRecord:
+        """Read the stored record for a committed transaction.
+
+        See :meth:`AxorumClient.transaction`.
+        """
+        status, body = await self._send(build_transaction(self._base_url, transaction))
+        return interpret_transaction(status, body)
+
+    async def obligations(self, actor: str) -> ObligationsResponse:
+        """Read the open obligations an actor owes.
+
+        See :meth:`AxorumClient.obligations`.
+        """
+        status, body = await self._send(build_obligations(self._base_url, actor))
+        return interpret_obligations(status, body)
+
+    async def balance(self, account: str) -> BalanceResponse:
+        """Read an account's net balance, in minor units.
+
+        See :meth:`AxorumClient.balance`.
+        """
+        status, body = await self._send(build_balance(self._base_url, account))
+        return interpret_balance(status, body)