plystra 0.0.1

Official Python SDK for the Plystra Kernel Phase 1 API.

plystra

Official Python SDK for the Plystra Kernel Phase 1 API.

PyPI package name: plystra Repository name: plystra/python-sdk

Requires Python 3.10 or newer.

Install

pip install plystra

Usage

Phase 1 is Context Mode: your trusted backend keeps its existing users, organizations, roles, and business rows, then calls Plystra to protect one action.

from plystra import Plystra

with Plystra("https://plystra.internal", api_key="ply_kernel_secret") as plystra:
    decision = plystra.authz.check(
        actor={
            "user_id": "user_external_alice",
            "member_id": "member_finance_reviewer",
            "binding_id": "binding_external_alice_finance",
            "space_id": "space_acme",
        },
        resource={
            "type": "invoice",
            "external_id": "invoice_001",
            "space_id": "space_acme",
            "group_path": "finance.apac",
            "owner_member_id": "member_invoice_creator",
        },
        grants=[{
            "role_key": "finance_approver",
            "resource": "invoice",
            "action": "approve",
            "scope": "group_tree",
            "space_id": "space_acme",
            "scope_anchor_group_path": "finance",
        }],
        action="approve",
        explain=True,
    )

Inline actor, resource, and grant context is trusted server-side input. Build it from your authenticated session and database state, never directly from browser-submitted JSON.

Async Usage

import asyncio
from plystra import AsyncPlystra


async def main() -> None:
    async with AsyncPlystra("https://plystra.internal", api_key="ply_kernel_secret") as plystra:
        print(await plystra.system.capabilities())


asyncio.run(main())

Kernel Surfaces

• system.health(), system.ready(), system.version()
• system.capabilities()
• resource_types.list()
• authz.check() and authz.explain()
• audit.list() and audit.get()
• request() for low-level calls

Attach a correlation id to a group of calls:

scoped = plystra.with_request_id("req_01HY...")
scoped.authz.explain(**context_mode_request)

Protected routes require a scoped server API key. Public health, readiness, and version checks do not send the key.