ppx-client

Python client for the Preference Profile Exchange (PPX) reference provider and any conformant implementation.

Install

pip install ppx-client

Requires Python 3.11+. Published version: 0.1.0a1 (PyPI).

Alpha, tracking a draft specification. Expect breaking changes. The version is 0.1.0a1 on PyPI and 0.1.0-alpha.1 on npm — the same release in each ecosystem's required format.

Quick start (sync)

from ppx_client import PpxClient, GrantRequestInput, consent_redirect_url

with PpxClient(base_url="https://api.provider.app") as ppx:
    req = ppx.request_grant(GrantRequestInput(
        client_id="my-app",
        subject_id="did:example:user-123",
        purposes=["recommendation"],
        allowed_domains=["fragrance"],
        allowed_namespaces=["fragrance"],
        allowed_operations=["read"],
        cross_domain_transfer="deny",
        writeback_policy="review_required",
        requested_duration_days=30,
    ))

    # Send the user here to review and approve
    consent_url = consent_redirect_url(
        "https://app.provider.app",
        req.grant_request_id,
        return_to="https://my-app.example/callback",
    )

    # After approval, exchange for a grant-scoped token
    tok = ppx.mint_token(req.grant_request_id)

    # Use it to read scoped claims
    profile = ppx.effective_profile(
        context={"climate": "hot_humid"},
        requested_namespaces=["fragrance"],
        token=tok.access_token,
    )

Async

import asyncio
from ppx_client import PpxAsyncClient, GrantRequestInput

async def main():
    async with PpxAsyncClient(base_url="https://api.provider.app") as ppx:
        card = await ppx.discovery_card()
        print(card.name, card.supported_namespaces)

asyncio.run(main())

Grant re-use

from ppx_client import PpxGrantRevokedError

try:
    fresh = ppx.refresh("my-app", cached_grant_id)
except PpxGrantRevokedError:
    # Clear cache, re-run the full approval flow
    cached_grant_id = None

AG-UI consent event streaming

from ppx_client import subscribe_ag_ui

for event in subscribe_ag_ui(f"https://api.provider.app/v1/ag-ui/consent/{req_id}"):
    print(event["type"], event)
    if event["type"] == "RUN_FINISHED":
        break

Async variant: subscribe_ag_ui_async.

License

Apache-2.0.