agentscore-py 2.7.0__tar.gz → 2.8.0__tar.gz

agentscore_py-2.8.0/.claude/CLAUDE.md

@@ -0,0 +1,76 @@
+# agentscore-py
+
+Python client for the AgentScore APIs.
+
+## Identity Model
+
+Two identity paths: `X-Wallet-Address` (wallet-based) and `X-Operator-Token` (credential-based). Wallet addresses accept both EVM (`0x...` 40-hex) and Solana (base58, 32–44 chars) formats; network is auto-detected from the address shape. `assess` responses include `resolved_operator` and `linked_wallets[]` (same-operator sibling wallets, normalized per network, EVM lowercased, Solana base58 verbatim; may mix chains for cross-chain operators). `create_session` and `create_credential` responses include an `agent_memory` cross-merchant pattern hint. `create_session` also returns `next_steps.action="deliver_verify_url_and_poll"` + polling instructions. `poll_session` returns `next_steps.action` values: `continue_polling`, `retry_merchant_request_with_operator_token`, `use_stored_operator_token`, `create_new_session`, `verification_failed`, `contact_support`.
+
+## Methods (sync + async)
+
+- `assess` / `aassess`: identity gate with policy (paid). Accepts `operator_token` for non-wallet agents. Response includes `linked_wallets[]` and `resolved_operator`. Optional `signer: { address, network }` opts into server-side wallet-signer-match AND OFAC SDN wallet-address screening; the response then carries both a `signer_match` block (wallet-binding verdict: `pass` / `wallet_signer_mismatch` / `wallet_auth_requires_wallet_signing`) and a `signer_sanctions` block (discriminated union: `{status: "clear"}` | `{sanctioned: True, ofac_label, sdn_uid, listed_at}` | `{status: "unavailable"}`). Wallet-OFAC SDN enforcement on the `signer` block is unconditional whenever a signer is supplied, no `policy.require_sanctions_clear` opt-in required. A `sanctioned: True` OR `status: "unavailable"` verdict flips the response `decision` to `deny` with `decision_reasons` including `sanctions_flagged` or `sanctions_check_unavailable` respectively (fail-closed; OFAC strict-liability). `policy.require_sanctions_clear` is the separate NAME-based screen on the resolved operator's KYC identity.
+- `create_session` / `acreate_session`: create verification session. Returns `agent_memory` + `next_steps`.
+- `poll_session` / `apoll_session`: poll session status, returns credential when verified, plus `next_steps.action`.
+- `create_credential` / `acreate_credential`: create operator credential (24h TTL default). Response includes `agent_memory`.
+- `list_credentials` / `alist_credentials`: list active credentials
+- `revoke_credential` / `arevoke_credential`: revoke a credential
+- `associate_wallet` / `aassociate_wallet`: report a signer wallet seen paying under a credential. Accepts optional `idempotency_key` (payment intent id / tx hash) so retries don't inflate transaction_count.
+- `telemetry_signer_match` / `atelemetry_signer_match`: fire-and-forget POST to `/v1/telemetry/signer-match`; commerce gate uses this to report `pass` / `wallet_signer_mismatch` / `wallet_auth_requires_wallet_signing` verdicts.
+
+## Errors + observability
+
+Typed error subclasses of `AgentScoreError` so callers can `except` on the specific class without parsing `err.code`: `PaymentRequiredError` (402), `TokenExpiredError` (401 token_expired, exposes parsed `verify_url` / `session_id` / `poll_secret` / `poll_url` / `next_steps` / `agent_memory` instance attributes), `InvalidCredentialError` (401 invalid_credential), `QuotaExceededError` (429 quota_exceeded, don't retry), `RateLimitedError` (429 rate_limited, retry after Retry-After), `TimeoutError` (httpx.TimeoutException, note: subclasses `AgentScoreError`, not the builtin; import explicitly from `agentscore.errors` to disambiguate). All non-timeout `httpx.HTTPError` (ConnectError, ProtocolError, NetworkError, etc.) wrap to `AgentScoreError(code="network_error", status_code=0)` for parity with node-sdk.
+
+`assess()` / `aassess()` responses include an optional `quota` field captured from `X-Quota-Limit` / `X-Quota-Used` / `X-Quota-Reset` response headers, so callers can monitor approach-to-cap proactively before hitting 429.
+
+## Architecture
+
+Single-package Python library published to PyPI.
+
+| File | Purpose |
+|------|---------|
+| `agentscore/` | Source code |
+| `tests/` | pytest tests |
+
+## Tooling
+
+- **uv**: package manager. Use `uv sync`, `uv run`.
+- **ruff**: linting + formatting. `uv run ruff check .` and `uv run ruff format --check .`.
+- **ty**: type checker (Astral). `uv run ty check agentscore/`.
+- **vulture**: dead code detection.
+- **pytest**: tests. `uv run pytest tests/`.
+- **Lefthook**: git hooks. Pre-commit: ruff. Pre-push: ty + vulture (parallel).
+
+## Key Commands
+
+```bash
+uv sync --all-extras
+uv run lefthook install   # one-time per clone, wires pre-commit + pre-push
+uv run ruff check .
+uv run ruff format .
+uv run ty check agentscore/
+uv run pytest tests/
+```
+
+## Workflow
+
+1. Create a branch
+2. Make changes
+3. Lefthook runs ruff on commit, ty + vulture on push
+4. Open a PR, CI runs automatically
+5. Merge (squash)
+
+## Rules
+
+- **No silent refactors**
+- **Never commit .env files or secrets**
+- **Use PRs**: never push directly to main
+
+## Releasing
+
+1. Update `version` in `pyproject.toml`
+2. Commit: `git commit -am "chore: bump to vX.Y.Z"`
+3. Tag: `git tag vX.Y.Z`
+4. Push: `git push && git push origin vX.Y.Z`
+
+The publish workflow runs on `ubuntu-latest` (required for PyPI trusted publishing), builds, publishes to PyPI via OIDC, and creates a GitHub Release.

{agentscore_py-2.7.0 → agentscore_py-2.8.0}/.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
       - uses: useblacksmith/checkout@v1
       - uses: astral-sh/setup-uv@v10.2.0
         with:
-          version: "0.12.22"
+          version: "0.12.23"
       - run: uv python install 3.12
       - uses: actions/cache@v6
         with:
@@ -49,7 +49,7 @@ jobs:
       - uses: useblacksmith/checkout@v1
       - uses: astral-sh/setup-uv@v10.2.0
         with:
-          version: "0.12.22"
+          version: "0.12.23"
       - run: uv python install ${{ matrix.python }}
       - run: uv sync --frozen --all-extras --all-groups --python ${{ matrix.python }}
       - run: uv run --python ${{ matrix.python }} pytest tests/ -q

{agentscore_py-2.7.0 → agentscore_py-2.8.0}/.github/workflows/publish.yml

@@ -21,7 +21,7 @@ jobs:
 
       - uses: astral-sh/setup-uv@v10.2.0
         with:
-          version: "0.12.22"
+          version: "0.12.23"
 
       - name: Set version from tag
         run: sed -i "s/^version = .*/version = \"${GITHUB_REF_NAME#v}\"/" pyproject.toml

{agentscore_py-2.7.0 → agentscore_py-2.8.0}/.github/workflows/security.yml

@@ -38,7 +38,7 @@ jobs:
       - uses: useblacksmith/checkout@v1
       - uses: astral-sh/setup-uv@v10.2.0
         with:
-          version: "0.12.22"
+          version: "0.12.23"
       - uses: actions/setup-python@v7
         with:
           python-version: "3.13"

{agentscore_py-2.7.0 → agentscore_py-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentscore-py
-Version: 2.7.0
+Version: 2.8.0
 Summary: Python client for the AgentScore APIs
 Project-URL: Homepage, https://www.agentscore.com
 Project-URL: Repository, https://github.com/agentscore/python-sdk
@@ -86,11 +86,8 @@ status = client.poll_session(session["session_id"], session["poll_secret"])
 if status["status"] == "verified":
     print(status["operator_token"])  # "opc_...", use for future requests
 
-# Optional pre-association: attach the session to a known wallet or refresh KYC
-# for an existing operator credential.
-client.create_session(address="0x...")
-client.create_session(operator_token="opc_...")  # KYC refresh
-client.create_session(kind="sign_in")  # registration-only: account sign-in, no identity documents
+# Registration-only session: the buyer signs in with an AgentScore account, no identity documents.
+client.create_session(kind="sign_in")
 ```
 
 ### Wallet resolution

{agentscore_py-2.7.0 → agentscore_py-2.8.0}/README.md

@@ -58,11 +58,8 @@ status = client.poll_session(session["session_id"], session["poll_secret"])
 if status["status"] == "verified":
     print(status["operator_token"])  # "opc_...", use for future requests
 
-# Optional pre-association: attach the session to a known wallet or refresh KYC
-# for an existing operator credential.
-client.create_session(address="0x...")
-client.create_session(operator_token="opc_...")  # KYC refresh
-client.create_session(kind="sign_in")  # registration-only: account sign-in, no identity documents
+# Registration-only session: the buyer signs in with an AgentScore account, no identity documents.
+client.create_session(kind="sign_in")
 ```
 
 ### Wallet resolution

{agentscore_py-2.7.0 → agentscore_py-2.8.0}/agentscore/__init__.py

@@ -15,8 +15,6 @@ from agentscore.types import (
     AccountVerification,
     AgentMemoryHint,
     AgentMemoryIdentityPaths,
-    AipProvenance,
-    AipSignatureMaterial,
     AssessResponse,
     AssociateWalletResponse,
     CredentialCreateErrorNextSteps,
@@ -61,8 +59,6 @@ __all__ = [
     "AgentMemoryIdentityPaths",
     "AgentScore",
     "AgentScoreError",
-    "AipProvenance",
-    "AipSignatureMaterial",
     "AssessResponse",
     "AssociateWalletResponse",
     "CredentialCreateErrorNextSteps",

{agentscore_py-2.7.0 → agentscore_py-2.8.0}/agentscore/client.py

@@ -111,7 +111,7 @@ def _build_error_from_response(response: httpx.Response) -> AgentScoreError:
             # verify_url, linked_wallets, reasons, etc. for granular denial recovery.
             details = {k: v for k, v in body.items() if k != "error"}
     except ValueError:
-        # Body wasn't JSON or didn't have the expected shape — keep defaults.
+        # Body wasn't JSON or didn't have the expected shape: keep defaults.
         pass
 
     if response.status_code == 402:
@@ -133,7 +133,6 @@ if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
 
     from agentscore.types import (
-        AipSignatureMaterial,
         AssessResponse,
         AssociateWalletResponse,
         CredentialCreateResponse,
@@ -254,30 +253,20 @@ class AgentScore:
         policy: DecisionPolicy | None = None,
         operator_token: str | None = None,
         signer: Signer | None = None,
-        aip_token: str | None = None,
-        aip_signature: AipSignatureMaterial | None = None,
     ) -> AssessResponse:
-        """Assess a wallet or operator (paid, writes score on-the-fly).
+        """Assess a wallet or operator against a compliance policy.
+
+        ``refresh`` is deprecated: the API ignores it, and every assess is evaluated live.
 
         ``signer`` opts into server-side wallet-signer-match: when supplied,
         the API resolves the signer wallet against the claimed ``address`` and emits
         a ``signer_match`` block on the response. See :class:`Signer`.
-
-        ``aip_token`` (+ ``aip_signature``) supplies an AIP Agent Identity Token in place of
-        ``address`` / ``operator_token``: the API re-verifies the issuer signature, the RFC 9421
-        proof-of-possession, and the attested claims, then evaluates policy against them.
         """
         body: dict[str, Any] = {}
         if address:
             body["address"] = address
         if operator_token:
             body["operator_token"] = operator_token
-        # AIP Agent Identity Token path: the API re-verifies the IdP signature + claims
-        # server-side and evaluates policy against the attested identity.
-        if aip_token:
-            body["aip_token"] = aip_token
-        if aip_signature is not None:
-            body["aip_signature"] = dict(aip_signature)
         if chain:
             body["chain"] = chain
         if refresh is not None:
@@ -303,9 +292,8 @@ class AgentScore:
     ) -> SessionCreateResponse:
         """Create a verification or sign-in session.
 
-        ``address`` pre-associates the session with a known wallet (EVM ``0x...`` or
-        Solana base58). ``operator_token`` pre-associates with an existing ``opc_...`` —
-        e.g. refresh KYC for a credential. ``kind`` selects the session kind: ``"kyc"``
+        ``address`` and ``operator_token`` are deprecated: the API ignores them, so a
+        session is never pre-associated with a wallet or credential. ``kind`` selects the session kind: ``"kyc"``
         (the API default) runs identity verification; ``"sign_in"`` is registration-only
         (the buyer signs in with an AgentScore account, no identity documents) and mints a
         ``sign_in``-scoped credential, for merchants that key durable state on the account
@@ -368,20 +356,20 @@ class AgentScore:
     ) -> AssociateWalletResponse:
         """Report that a wallet paid under an operator credential.
 
-        ``network`` is the key-derivation family (``"evm"`` or ``"solana"``) — EVM EOAs share
+        ``network`` is the key-derivation family (``"evm"`` or ``"solana"``): EVM EOAs share
         identity across every EVM chain (Base, Tempo, Ethereum, …) so one value covers them all.
 
-        ``idempotency_key`` is optional — pass a stable per-payment key (e.g., payment intent id,
+        ``idempotency_key`` is optional: pass a stable per-payment key (e.g., payment intent id,
         x402 tx hash) so agent retries of the same logical payment don't inflate transaction_count.
 
-        Fire-and-forget friendly — the returned ``first_seen`` boolean is informational only.
+        Fire-and-forget friendly: the returned ``first_seen`` boolean is informational only.
         """
         body: dict[str, Any] = {
             "operator_token": operator_token,
             "wallet_address": wallet_address,
             "network": network,
         }
-        # Truthy check (not `is not None`) so empty strings don't ship a useless key —
+        # Truthy check (not `is not None`) so empty strings don't ship a useless key:
         # only forward when the key actually has content.
         if idempotency_key:
             if len(idempotency_key) > _IDEMPOTENCY_KEY_MAX:
@@ -403,23 +391,18 @@ class AgentScore:
         policy: DecisionPolicy | None = None,
         operator_token: str | None = None,
         signer: Signer | None = None,
-        aip_token: str | None = None,
-        aip_signature: AipSignatureMaterial | None = None,
     ) -> AssessResponse:
-        """Assess a wallet or operator (paid, writes score on-the-fly).
+        """Assess a wallet or operator against a compliance policy.
+
+        ``refresh`` is deprecated: the API ignores it, and every assess is evaluated live.
 
-        ``signer`` opts into server-side wallet-signer-match; ``aip_token`` (+ ``aip_signature``)
-        supplies an AIP Agent Identity Token. Async mirror of :meth:`assess`.
+        ``signer`` opts into server-side wallet-signer-match. Async mirror of :meth:`assess`.
         """
         body: dict[str, Any] = {}
         if address:
             body["address"] = address
         if operator_token:
             body["operator_token"] = operator_token
-        if aip_token:
-            body["aip_token"] = aip_token
-        if aip_signature is not None:
-            body["aip_signature"] = dict(aip_signature)
         if chain:
             body["chain"] = chain
         if refresh is not None:
@@ -445,9 +428,8 @@ class AgentScore:
     ) -> SessionCreateResponse:
         """Create a verification or sign-in session.
 
-        ``address`` pre-associates the session with a known wallet (EVM ``0x...`` or
-        Solana base58). ``operator_token`` pre-associates with an existing ``opc_...`` —
-        e.g. refresh KYC for a credential. ``kind`` selects the session kind: ``"kyc"``
+        ``address`` and ``operator_token`` are deprecated: the API ignores them, so a
+        session is never pre-associated with a wallet or credential. ``kind`` selects the session kind: ``"kyc"``
         (the API default) runs identity verification; ``"sign_in"`` is registration-only
         (the buyer signs in with an AgentScore account, no identity documents) and mints a
         ``sign_in``-scoped credential, for merchants that key durable state on the account
@@ -514,7 +496,7 @@ class AgentScore:
             "wallet_address": wallet_address,
             "network": network,
         }
-        # Truthy check (not `is not None`) so empty strings don't ship a useless key —
+        # Truthy check (not `is not None`) so empty strings don't ship a useless key:
         # only forward when the key actually has content.
         if idempotency_key:
             if len(idempotency_key) > _IDEMPOTENCY_KEY_MAX:
@@ -527,7 +509,7 @@ class AgentScore:
         return await self._send_async(lambda: client.post("/v1/credentials/wallets", json=body))
 
     def telemetry_signer_match(self, payload: dict[str, Any]) -> None:
-        """Fire-and-forget telemetry — report a wallet-signer-match verdict.
+        """Fire-and-forget telemetry: report a wallet-signer-match verdict.
 
         Tracks aggregate signer-binding behavior across merchants. Does not raise;
         failures are logged at warning level so persistent telemetry outages are visible

{agentscore_py-2.7.0 → agentscore_py-2.8.0}/agentscore/errors.py

@@ -12,7 +12,7 @@ class AgentScoreError(Exception):
         super().__init__(message)
         self.code = code
         self.status_code = status_code
-        # Response-body fields beyond `error.{code,message}` — e.g. verify_url,
+        # Response-body fields beyond `error.{code,message}`: e.g. verify_url,
         # linked_wallets, claimed_operator, actual_signer, reasons. Consumers
         # branch on these for granular recovery. Defaults to {} so callers
         # constructing this error by hand without a body can omit it.
@@ -25,17 +25,17 @@ class AgentScoreError(Exception):
 
 
 class PaymentRequiredError(AgentScoreError):
-    """HTTP 402 — the endpoint is not enabled for this account."""
+    """HTTP 402: the endpoint is not enabled for this account."""
 
     def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
         super().__init__("payment_required", message, 402, details)
 
 
 class TokenExpiredError(AgentScoreError):
-    """HTTP 401 with ``error.code = 'token_expired'`` — credential is no longer valid.
+    """HTTP 401 with ``error.code = 'token_expired'``: credential is no longer valid.
 
     Covers both revoked and TTL-expired credentials; the API does not distinguish
-    which. Body carries an auto-minted verification session — exposed here so callers recover
+    which. Body carries an auto-minted verification session: exposed here so callers recover
     without re-parsing ``details``.
     """
 
@@ -51,7 +51,7 @@ class TokenExpiredError(AgentScoreError):
 
 
 class InvalidCredentialError(AgentScoreError):
-    """HTTP 401 with ``error.code = 'invalid_credential'`` — operator_token doesn't exist.
+    """HTTP 401 with ``error.code = 'invalid_credential'``: operator_token doesn't exist.
 
     Permanent: no auto-session is issued. Caller should switch tokens or restart.
     """
@@ -61,7 +61,7 @@ class InvalidCredentialError(AgentScoreError):
 
 
 class QuotaExceededError(AgentScoreError):
-    """HTTP 429 with ``error.code = 'quota_exceeded'`` — account-level cap reached.
+    """HTTP 429 with ``error.code = 'quota_exceeded'``: account-level cap reached.
 
     Don't retry; the cap won't lift through retry alone. Distinct from per-second
     :class:`RateLimitedError`.
@@ -72,7 +72,7 @@ class QuotaExceededError(AgentScoreError):
 
 
 class RateLimitedError(AgentScoreError):
-    """HTTP 429 with ``error.code = 'rate_limited'`` — per-second sliding-window cap hit.
+    """HTTP 429 with ``error.code = 'rate_limited'``: per-second sliding-window cap hit.
 
     Retry after the interval indicated by the ``Retry-After`` header (typically <= 1s).
     """

{agentscore_py-2.7.0 → agentscore_py-2.8.0}/agentscore/test_mode.py

@@ -2,7 +2,7 @@
 
 AgentScore's ``/v1/assess`` endpoint recognizes seven EVM addresses
 (``0x0000…0001`` through ``0x0000…0007``) as test fixtures with deterministic
-policy outcomes — KYC verified, sanctions clear, age gates passing — so dev/test
+policy outcomes (KYC verified, sanctions clear, age gates passing) so dev/test
 interactions don't burn real KYC credits and produce predictable results.
 
 Use this in test suites and dev/staging tooling to label test-mode interactions

{agentscore_py-2.7.0 → agentscore_py-2.8.0}/agentscore/types.py

@@ -40,12 +40,12 @@ class Signer(TypedDict):
     When passed to ``assess()`` / ``aassess()``, the API resolves this signer wallet
     against the claimed ``address`` and emits a ``signer_match`` block on the response.
     Lets commerce gates collapse the legacy 2 follow-up assess calls (one per wallet)
-    into the gate's primary assess call. Strictly additive — old clients that don't
+    into the gate's primary assess call. Strictly additive: old clients that don't
     pass this field see no ``signer_match`` on the response.
     """
 
     # Recovered payment-signer wallet. ``None`` indicates the rail carries no wallet
-    # signature (Stripe SPT, card) — produces
+    # signature (Stripe SPT, card): produces
     # ``signer_match.kind = "wallet_auth_requires_wallet_signing"``.
     address: str | None
     # Key-derivation family of the signer wallet.
@@ -63,24 +63,24 @@ class SignerMatch(TypedDict):
     ``kind`` is always present; other fields depend on which kind was emitted.
     """
 
-    # ``pass`` — claimed wallet and signer wallet resolve to the same operator (or are
-    # byte-equal). ``wallet_signer_mismatch`` — operators differ.
-    # ``wallet_auth_requires_wallet_signing`` — request supplied ``address: None`` (rail
+    # ``pass``: claimed wallet and signer wallet resolve to the same operator (or are
+    # byte-equal). ``wallet_signer_mismatch``: operators differ.
+    # ``wallet_auth_requires_wallet_signing``: request supplied ``address: None`` (rail
     # has no wallet signer); agent should switch to operator_token auth.
     kind: Literal["pass", "wallet_signer_mismatch", "wallet_auth_requires_wallet_signing"]
     # Operator the claimed wallet resolves to. ``None`` if unlinked.
     claimed_operator: NotRequired[str | None]
     # Operator the signer wallet resolves to. ``None`` if unlinked.
     signer_operator: NotRequired[str | None]
-    # Echoed only on ``wallet_auth_requires_wallet_signing`` — the claimed wallet from
+    # Echoed only on ``wallet_auth_requires_wallet_signing``: the claimed wallet from
     # the request. Helps agents construct the recovery message.
     claimed_wallet: NotRequired[str]
-    # Echoed on ``wallet_signer_mismatch`` — the claimed wallet, normalized.
+    # Echoed on ``wallet_signer_mismatch``: the claimed wallet, normalized.
     expected_signer: NotRequired[str]
-    # Echoed on ``wallet_signer_mismatch`` — the signer wallet, normalized.
+    # Echoed on ``wallet_signer_mismatch``: the signer wallet, normalized.
     actual_signer: NotRequired[str]
     # Same-operator linked wallets the agent could re-sign from to satisfy the claim.
-    # Mirrors the top-level ``linked_wallets`` deny-guard — omitted on ``deny`` verdicts.
+    # Mirrors the top-level ``linked_wallets`` deny-guard: omitted on ``deny`` verdicts.
     linked_wallets: NotRequired[list[str]]
     # JSON-encoded ``{action, steps, user_message}`` envelope for SDK denial bodies.
     # SDK consumers spread this into their 403
@@ -89,13 +89,13 @@ class SignerMatch(TypedDict):
 
 
 class SignerSanctionsClear(TypedDict):
-    """Server-side wallet-sanctions verdict — address NOT on the OFAC SDN list."""
+    """Server-side wallet-sanctions verdict: address NOT on the OFAC SDN list."""
 
     status: Literal["clear"]
 
 
 class SignerSanctionsHit(TypedDict):
-    """Server-side wallet-sanctions verdict — address IS on the OFAC SDN list.
+    """Server-side wallet-sanctions verdict: address IS on the OFAC SDN list.
 
     Wallet-OFAC enforcement on the ``signer`` block is unconditional whenever
     a signer is supplied. This verdict flips the response ``decision`` to
@@ -119,7 +119,7 @@ class SignerSanctionsHit(TypedDict):
 
 
 class SignerSanctionsUnavailable(TypedDict):
-    """Server-side wallet-sanctions verdict — lookup itself failed.
+    """Server-side wallet-sanctions verdict: lookup itself failed.
 
     Fail-closed: the gate denies whenever a signer was supplied and the OFAC
     lookup couldn't resolve, because OFAC sanctions screening is strict-liability.
@@ -132,43 +132,10 @@ class SignerSanctionsUnavailable(TypedDict):
 SignerSanctions = SignerSanctionsClear | SignerSanctionsHit | SignerSanctionsUnavailable
 
 
-class AipSignatureMaterial(TypedDict):
-    """RFC 9421 HTTP Message Signature material proving possession of the AIT-bound ``cnf`` key.
-
-    Forwarded alongside ``aip_token`` so ``/v1/assess`` can re-verify proof-of-possession
-    authoritatively; the API never sees the original agent-to-merchant request itself.
-    """
-
-    method: str  # HTTP method of the original agent-to-merchant request (``@method``)
-    authority: str  # Authority/host the agent signed (``@authority``)
-    path: str  # Request path the agent signed (``@path``)
-    signature_input: str  # Raw ``Signature-Input`` header value the agent sent
-    signature: str  # Raw ``Signature`` header value the agent sent
-
-
-class _AipProvenanceRequired(TypedDict):
-    issuer: str  # Canonical issuer URL of the AIT
-    subject: str  # The token's ``sub``: the IdP's subject identifier for the verified human
-
-
-class AipProvenance(_AipProvenanceRequired, total=False):
-    """Provenance block returned when the identity input was an AIP Agent Identity Token.
-
-    Surfaces which issuer attested the identity and the trust level it asserted.
-    """
-
-    trust_level: Literal["autonomous", "human_present", "human_confirmed"]
-    agent_provider: str
-    # True when /v1/assess re-verified the RFC 9421 proof-of-possession. Always true on a
-    # success response: the API fail-closes with an HTTP 400/401 error (not a 200 deny)
-    # when possession can't be proven.
-    pop_verified: bool
-
-
 class _AssessResponseRequired(TypedDict):
     decision: str | None
     decision_reasons: list[str]
-    identity_method: Literal["wallet", "operator_token", "aip_token"]
+    identity_method: Literal["wallet", "operator_token"]
 
 
 class PolicyExplanation(TypedDict, total=False):
@@ -190,8 +157,8 @@ class QuotaInfo(TypedDict):
 
     limit: int | None
     used: int | None
-    # ``X-Quota-Reset`` is an ISO-8601 timestamp, or the literal string "never" for lifetime
-    # caps. The API emits "never" for tiers without a reset.
+    # ``X-Quota-Reset`` is the UTC date (``YYYY-MM-DD``) the calendar-month quota resets,
+    # e.g. "2026-06-01", or "never" when the API has no reset date for the account.
     reset: str | None
 
 
@@ -223,8 +190,6 @@ class AssessResponse(_AssessResponseRequired, total=False):
     # Server-side OFAC SDN wallet-address verdict, returned only when the request supplied
     # ``signer``. Empty otherwise.
     signer_sanctions: NotRequired[SignerSanctions]
-    # Issuer provenance, returned only when ``identity_method == "aip_token"``.
-    aip: NotRequired[AipProvenance]
     # Quota state for this account, captured from response headers on the success path.
     # Use to monitor approach-to-cap proactively (warn at 80%, alert at 95%) before 429.
     quota: NotRequired[QuotaInfo]
@@ -240,7 +205,7 @@ class SessionCreateRequest(TypedDict, total=False):
 class SessionCreateNextSteps(TypedDict, total=False):
     """Structured action guidance on POST /v1/sessions success.
 
-    action is always ``deliver_verify_url_and_poll`` — tells the agent to share verify_url
+    action is always ``deliver_verify_url_and_poll``: tells the agent to share verify_url
     with the user and poll poll_url with X-Poll-Secret until an operator_token is issued.
     """
 
@@ -384,27 +349,27 @@ DenialCode = Literal[
     # Gate-emitted codes from commerce middleware (canonical 9-element union)
     "missing_identity",
     "identity_verification_required",
-    # Credential is no longer valid (revoked or past its TTL — the two cases share this
+    # Credential is no longer valid (revoked or past its TTL: the two cases share this
     # code deliberately so the API doesn't leak which one). The 401 body carries an
     # auto-minted session so agents recover without holding an API key.
     "token_expired",
     # Credential doesn't exist at all (typo, fabricated, never minted). Permanent state;
     # no auto-session is issued because the agent may have other valid tokens to try.
     "invalid_credential",
-    # Wallet-signer binding — claimed X-Wallet-Address must resolve to the same operator
+    # Wallet-signer binding: claimed X-Wallet-Address must resolve to the same operator
     # as the payment signer; wallet-auth is rejected on rails with no wallet signer.
     "wallet_signer_mismatch",
     "wallet_auth_requires_wallet_signing",
     "wallet_not_trusted",
     "api_error",
     "payment_required",
-    # Merchant-emitted convenience codes — not emitted by the AgentScore API itself,
+    # Merchant-emitted convenience codes: not emitted by the AgentScore API itself,
     # but may appear in 4xx bodies passing through the SDK from merchants whose gate
     # `on_denied` hook wraps AgentScore denials into business-domain codes.
     "operator_verification_required",
     "compliance_denied",
     "compliance_error",
-    # Decision-reason code surfaced in error.code by some merchants — kept for back-compat
+    # Decision-reason code surfaced in error.code by some merchants: kept for back-compat
     # with merchants that flatten policy reasons into the error envelope.
     "kyc_required",
 ]
@@ -422,15 +387,15 @@ NextStepsAction = Literal[
     "done",
     "use_operator_token",
     "regenerate_payment_from_linked_wallet",
-    # Gate-emitted probe strategy — try wallet on signing rails, fall back to stored
+    # Gate-emitted probe strategy: try wallet on signing rails, fall back to stored
     # opc_..., fall back to session flow. Emitted on bare missing_identity 403s.
     "probe_identity_then_session",
-    # Wallet signer mismatch — re-sign from expected_signer / any linked_wallets entry,
+    # Wallet signer mismatch: re-sign from expected_signer / any linked_wallets entry,
     # or drop X-Wallet-Address and retry with X-Operator-Token.
     "resign_or_switch_to_operator_token",
-    # Non-signing rail (Stripe SPT, card) — drop X-Wallet-Address, use X-Operator-Token.
+    # Non-signing rail (Stripe SPT, card): drop X-Wallet-Address, use X-Operator-Token.
     "switch_to_operator_token",
-    # POST /v1/sessions success — deliver verify_url + poll poll_url.
+    # POST /v1/sessions success: deliver verify_url + poll poll_url.
     "deliver_verify_url_and_poll",
     # Session poll states.
     "continue_polling",
@@ -446,14 +411,13 @@ NextStepsAction = Literal[
 class AgentMemoryIdentityPaths(TypedDict):
     wallet: str
     operator_token: str
-    agent_identity: NotRequired[str]
 
 
 class AgentMemoryHint(TypedDict):
     """Structured hint emitted on bootstrap denials and POST /v1/sessions success.
 
     LLM-hosted agents should save this to their long-term memory so future AgentScore encounters
-    skip the cold-start session flow. Contents are the pattern, not secrets —
+    skip the cold-start session flow. Contents are the pattern, not secrets:
     do_not_persist_in_memory names bearer credentials that belong in a credential store.
     """
 
@@ -463,8 +427,6 @@ class AgentMemoryHint(TypedDict):
     identity_check_endpoint: str
     list_wallets_endpoint: NotRequired[str]
     identity_paths: AgentMemoryIdentityPaths
-    # Issuer allowlist a merchant accepts for AIP Agent Identity Tokens, when advertised.
-    aip_trusted_issuers: NotRequired[list[str]]
     bootstrap: str
     do_not_persist_in_memory: list[str]
     persist_in_credential_store: list[str]

{agentscore_py-2.7.0 → agentscore_py-2.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentscore-py"
-version = "2.7.0"
+version = "2.8.0"
 description = "Python client for the AgentScore APIs"
 readme = "README.md"
 license = "MIT"
@@ -63,7 +63,8 @@ include = ["agentscore"]
 required-version = ">=0.11.0"
 # An unbounded transitive requirement lets a routine refresh resolve a BETA and
 # drag a subtree with it, and the tests pass either way, so nothing reports it.
-# That is how python-commerce once resolved web3 8.0.0b3 through three
-# unbounded parents. Blocking prereleases outright beats pinning whichever
-# package surfaced last, since the same shape exists on several transitives.
-prerelease = "disallow"
+# `if-necessary` admits a prerelease only for a package that has never shipped
+# a stable release; a package that reaches for a beta it does not need gets its
+# own constraint (python-commerce pins web3 below 8). A blanket `disallow` also
+# refuses the never-stable packages and silently holds back whatever needs them.
+prerelease = "if-necessary"