Python SDK Overview

The Parmana Python SDK lets you integrate authorization into Python applications, AI agents, and microservices. Before any consequential action executes, your code asks Parmana: “is this allowed?” — and gets back either a signed proof of what happened, or a rejection with a reason.

What it solves

Your AI agent wants to refund a payment. The naive integration hands it the payment provider’s credentials directly and trusts its judgment. Instead, with Parmana:

Your code proposes the action (who, what, why, with what supporting facts).
A policy decides, deterministically, based on the facts you supplied (amount limits, verification status, risk score, whatever the named policy actually checks).
Your system executes only if approved — a rejected proposal raises an exception before any downstream call happens.
Proof is recorded: a cryptographically signed Execution Trust Record, independently verifiable without trusting Parmana’s word for it.

The agent never holds the vendor’s credentials. Policy decides, not the agent’s own judgment call.

When to use it

Reach for the SDK if:

You have an AI agent (LangChain, CrewAI, a custom loop) that takes actions with real consequences.
You need a durable, signed record of who did what and why, for audit or compliance.
You want a named, versioned policy to make the call, not inline if statements scattered through agent code.
You’re wiring an agent into a payment, CRM, or infrastructure connector.

Skip it if the action is read-only or has no real consequence — plain application logging is enough there; The gateway exists to guard actions that actually change something.

Core concepts

Three objects, one call in between:

BusinessTransaction  →  client.execution.execute(transaction)  →  ExecutionTrustRecord
 (what you propose)         (policy runs, connector executes)      (signed proof of what happened)

There’s no separate “authorize” step to call — execute() runs the policy decision and the connector call in one request. If the policy denies the transaction, execute() raises ExecutionRejectedError instead of returning; if it approves, the connector runs and you get back a signed ExecutionTrustRecord with the decision embedded.

BusinessTransaction

What you propose, built with create_business_transaction() rather than assembled by hand — see Why the builder function, not five nested objects for what it protects you from:

from parmana import PolicyReference, create_business_transaction

transaction = create_business_transaction(
    principal_id="ai-customer-service-001",  # must match your API key's allowed_principal_ids
    purpose="Customer-requested refund",
    action="paytm:refund",
    target="payment/pay_LiZx3eWa",
    parameters={"amount": 50000, "currency": "INR"},
    policy=PolicyReference(name="customer-refund", version="1.0.0", schema_version="1.0.0"),
    signals={
        "fraudScore": 0.05,
        "customerTenureDays": 180,
        "paymentVerified": True,
    },
)

principal_id — who’s proposing this (an agent id, service name, or user id); checked against your API key’s own allowed_principal_ids server-side before anything else runs.
action — the capability being invoked, e.g. "paytm:refund".
parameters — the business data for the action itself (amount, currency, whatever the connector needs).
policy — which named, versioned policy evaluates this transaction.
signals — the facts the named policy actually checks. Every fact a policy rule references must be present here, or the policy has nothing to evaluate.

ExecutionTrustRecord

What comes back once execute() succeeds — a signed record of the decision, the connector’s evidence, and the resulting proof:

trust_record = client.execution.execute(transaction)

print(trust_record.trust_record_id)
print(trust_record.trust_record_hash)
print(trust_record.signature.algorithm)                 # e.g. "ED25519"
print(trust_record.executions[0].decision.outcome)       # "APPROVED"
print(trust_record.executions[0].evidence)               # what the connector actually did

You can verify this independently without trusting Parmana’s word for it — the signature is checkable against a public key you control.

Rejection is an exception, not a status field to check

A denied transaction never produces a 200 response with a “REJECTED” status embedded in it — the server returns a real 403 and the SDK raises:

from parmana import ExecutionRejectedError

try:
    trust_record = client.execution.execute(transaction)
except ExecutionRejectedError as exc:
    print(f"Denied: {exc}")  # "Execution rejected: <policy-specific reason>"

See Errors, correctly mapped to real conditions for the full exception taxonomy — connection failures, malformed requests, and auth failures each raise their own distinct exception, not a generic one you have to string-match.

Installation

pip install parmana

Real PyPI package, confirmed against the live registry (see Python SDK for the current published version). Requires Python 3.8+.

Quick example

from parmana import ParmanaClient, PolicyReference, create_business_transaction

client = ParmanaClient(endpoint="http://localhost:3000", api_key="my-secret-api-key")

transaction = create_business_transaction(
    principal_id="python-sdk",
    purpose="Quickstart demo",
    action="test:fixture-execute",
    target="vendor://payments",
    parameters={"amount": 1000, "currency": "USD"},
    policy=PolicyReference(name="vendor-payment", version="2.0.0", schema_version="1.0.0"),
    signals={
        "vendorVerified": True,
        "invoiceVerified": True,
        "paymentApproved": True,
        "sufficientFunds": True,
        "paymentAmount": 1000,
        "riskScore": 5,
        "vendorId": "vendor://payments",
    },
)

trust_record = client.execution.execute(transaction)
print(trust_record.trust_record_hash)

This is the exact call Quickstart walks through against a local server, with real captured output — see there for the full step-by-step (installing, generating a local Gateway keypair, starting the Runtime) if you haven’t set up a local server yet.

Real-world example: a refund an agent proposes

from parmana import ExecutionRejectedError, ParmanaClient, PolicyReference, create_business_transaction

client = ParmanaClient(endpoint="http://localhost:3000", api_key="my-secret-api-key")

transaction = create_business_transaction(
    principal_id="ai-customer-service",
    purpose="Customer requested a refund after a duplicate charge",
    action="paytm:refund",
    target="payment/pay_LiZx3eWa",
    parameters={"amount": 50000, "currency": "INR"},
    policy=PolicyReference(name="customer-refund", version="1.0.0", schema_version="1.0.0"),
    signals={
        "fraudScore": 0.05,
        "customerTenureDays": 180,
        "paymentVerified": True,
    },
)

try:
    trust_record = client.execution.execute(transaction)
    print(f"Approved: {trust_record.trust_record_hash}")
except ExecutionRejectedError as exc:
    print(f"Denied: {exc}")

No separate credential ever reaches the agent — the paytm:refund connector holds its own credentials, resolved server-side; see Credential isolation.

What Parmana guarantees

The agent never holds the connector’s own credentials — see Credential isolation.
The same transaction, evaluated against the same policy version, produces the same decision — policy decides, not agent judgment; see Policies and the decision.
Every authorization is single-use and time-bounded — see The gateway.
Execution produces a cryptographically signed proof, independently verifiable — see Execution Trust Records and Verify independently.
What’s explicitly not guaranteed (compliance certifications, unscoped “non-bypassable” claims, and more) is listed plainly in Limitations — read that before making claims of your own downstream.

Python SDK Quickstart

Get running end-to-end in under 10 minutes.

Python SDK for AI Agents

Wire this into LangChain, CrewAI, FastAPI, and async agent code.

Python SDK Production

Error handling, audit logging, and a deployment checklist.

Python SDK reference

The complete, verified API surface: every method, every error, the test suite backing it.

Get Started

Core Concepts

Guides

SDKs

REST API

Security & Deployment

Integrations

Tutorials

Advanced

Support

Changelog

Python SDK Overview

What it solves

When to use it

Core concepts

BusinessTransaction

ExecutionTrustRecord

Rejection is an exception, not a status field to check

Installation

Quick example

Real-world example: a refund an agent proposes

What Parmana guarantees

Next

Python SDK Quickstart

Python SDK for AI Agents

Python SDK Production

Python SDK reference

​What it solves

​When to use it

​Core concepts

​BusinessTransaction

​ExecutionTrustRecord

​Rejection is an exception, not a status field to check

​Installation

​Quick example

​Real-world example: a refund an agent proposes

​What Parmana guarantees

​Next

Python SDK Quickstart

Python SDK for AI Agents

Python SDK Production

Python SDK reference

What it solves

When to use it

Core concepts

BusinessTransaction

ExecutionTrustRecord

Rejection is an exception, not a status field to check

Installation

Quick example

Real-world example: a refund an agent proposes

What Parmana guarantees

Next