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

agentscore_py-2.7.1/.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.7.1}/.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.7.1}/.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.7.1}/.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.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentscore-py
-Version: 2.7.0
+Version: 2.7.1
 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.7.1}/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.7.1}/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:
@@ -257,7 +257,9 @@ class AgentScore:
         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
@@ -303,9 +305,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 +369,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:
@@ -406,7 +407,9 @@ class AgentScore:
         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`.
@@ -445,9 +448,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 +516,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 +529,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.7.1}/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.7.1}/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.7.1}/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.
@@ -190,8 +190,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
 
 
@@ -240,7 +240,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 +384,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 +422,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",
@@ -453,7 +453,7 @@ 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.
     """
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentscore-py"
-version = "2.7.0"
+version = "2.7.1"
 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"

{agentscore_py-2.7.0 → agentscore_py-2.7.1}/tests/test_client.py

@@ -674,7 +674,7 @@ def test_connect_error_raises_agentscore_error():
     client = AgentScore(api_key=API_KEY)
     with pytest.raises(AgentScoreError) as exc_info:
         client.list_credentials()
-    # All httpx-layer errors (Timeout, Connect, Protocol, Network) are wrapped — parity with node-sdk.
+    # All httpx-layer errors (Timeout, Connect, Protocol, Network) are wrapped: parity with node-sdk.
     # ConnectError specifically maps to network_error; TimeoutException is the only one that becomes TimeoutError.
     assert exc_info.value.code == "network_error"
     assert exc_info.value.status_code == 0
@@ -1413,7 +1413,7 @@ def test_associate_wallet_omits_idempotency_key_when_not_provided():
 
 @respx.mock
 def test_associate_wallet_omits_empty_string_idempotency_key():
-    """Empty string is not a valid key — match node-sdk behavior and skip forwarding."""
+    """Empty string is not a valid key: match node-sdk behavior and skip forwarding."""
     route = respx.post(f"{BASE_URL}/v1/credentials/wallets").mock(
         return_value=httpx.Response(200, json={"associated": True, "first_seen": True}),
     )
@@ -1800,7 +1800,7 @@ def test_unknown_4xx_falls_through_to_generic_agentscore_error():
     client = AgentScore(api_key=API_KEY)
     with pytest.raises(AgentScoreError) as exc_info:
         client.assess(address=ADDRESS)
-    # Not a typed subclass — generic AgentScoreError.
+    # Not a typed subclass: generic AgentScoreError.
     assert type(exc_info.value) is AgentScoreError
     assert exc_info.value.status_code == 403
     assert exc_info.value.code == "account_cancelled"
@@ -2119,7 +2119,7 @@ def test_unknown_400_invalid_request_falls_through_to_generic_agentscore_error()
     assert not isinstance(err, QuotaExceededError)
     assert not isinstance(err, RateLimitedError)
     assert not isinstance(err, AgentScoreTimeoutError)
-    # Generic — type is exactly AgentScoreError, not a subclass.
+    # Generic: type is exactly AgentScoreError, not a subclass.
     assert type(err) is AgentScoreError
     assert err.code == "invalid_request"
     assert err.status_code == 400
@@ -2129,7 +2129,7 @@ def test_unknown_400_invalid_request_falls_through_to_generic_agentscore_error()
 @respx.mock
 def test_token_expired_error_fields_undefined_when_api_omits_them():
     """If API returns 401 token_expired with no verify_url / session_id / poll_secret /
-    next_steps / agent_memory in the body, the instance fields stay None — error is still
+    next_steps / agent_memory in the body, the instance fields stay None: error is still
     a TokenExpiredError (not falling through to generic)."""
     from agentscore.errors import TokenExpiredError
 
@@ -2169,7 +2169,7 @@ def test_token_expired_error_ignores_wrong_typed_body_fields():
     with pytest.raises(TokenExpiredError) as exc_info:
         client.assess(address=ADDRESS)
     err = exc_info.value
-    # Strings only — wrong types ignored, instance fields stay None.
+    # Strings only: wrong types ignored, instance fields stay None.
     assert err.verify_url is None
     assert err.session_id is None
     # Raw values still in details for inspection.
@@ -2339,7 +2339,7 @@ async def test_aassess_forwards_chain_refresh_and_policy():
 @pytest.mark.asyncio
 @respx.mock
 async def test_acreate_credential_omits_unset_fields():
-    """Both `label` and `ttl_days` default to None — the body must stay empty (covers the
+    """Both `label` and `ttl_days` default to None: the body must stay empty (covers the
     falsy side of both `is not None` branches)."""
     route = respx.post(f"{BASE_URL}/v1/credentials").mock(
         return_value=httpx.Response(200, json=CREDENTIAL_CREATE_PAYLOAD)
@@ -2354,7 +2354,7 @@ async def test_acreate_credential_omits_unset_fields():
 @pytest.mark.asyncio
 @respx.mock
 async def test_acreate_credential_forwards_label_and_ttl():
-    """Truthy side of both branches — label and ttl_days are forwarded."""
+    """Truthy side of both branches: label and ttl_days are forwarded."""
     route = respx.post(f"{BASE_URL}/v1/credentials").mock(
         return_value=httpx.Response(200, json=CREDENTIAL_CREATE_PAYLOAD)
     )

{agentscore_py-2.7.0 → agentscore_py-2.7.1}/tests/test_types.py

@@ -110,6 +110,6 @@ def test_session_create_response_accepts_agent_memory() -> None:
 
 
 def test_sdk_exports_new_symbols() -> None:
-    # Importability check — covered above via imports, but also guard the AgentScore class itself.
+    # Importability check: covered above via imports, but also guard the AgentScore class itself.
     assert AgentScore is not None
     assert AgentScoreError is not None

{agentscore_py-2.7.0 → agentscore_py-2.7.1}/uv.lock

@@ -2,12 +2,9 @@ version = 1
 revision = 5
 requires-python = ">=3.11"
 
-[options]
-prerelease-mode = "disallow"
-
 [[package]]
 name = "agentscore-py"
-version = "2.7.0"
+version = "2.7.1"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

{agentscore_py-2.7.0 → agentscore_py-2.7.1}/vulture_whitelist.py

@@ -1,4 +1,4 @@
-# Vulture whitelist — false positives for required function signatures
+# Vulture whitelist: false positives for required function signatures
 
 # Context manager __exit__ requires (*args) signature
 args  # noqa: F821

agentscore_py-2.7.0/.claude/CLAUDE.md

@@ -1,76 +0,0 @@
-# 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.