Decionis Python SDK

Decionis: The Governance Protocol for Automated Enterprise Decisions.

Decionis is the Decision Protocol infrastructure for encoding, evaluating, and auditing organizational policy at scale. The Python SDK acts as an execution interceptor: it captures execution intent, sends it to Decionis, and locally continues, stops, or hands off based on the signed decision.

Core Concept

• Trust: Every governed action receives a deterministic Decionis decision: ALLOW, BLOCK, ESCALATE, REVIEW_REQUIRED, or ERROR.
• Automation: Applications, bots, API routes, and workflows keep moving only after Decionis returns a signed policy evaluation.
• Auditability: Decision Dossiers preserve the execution intent, reason codes, cryptographic signature, and verification trail for enterprise review.

Installation

pip install decionis

Quickstart

Set DECIONIS_API_KEY in your server-side runtime. Get a key by subscribing at https://decionis.com or by requesting an API key from Decionis. API-key registration can include an industry such as financial_services, healthcare, retail, or technology; Decionis can provision a default encoded policy binding for that industry in shadow mode.

import os

from decionis import DecionisClient

client = DecionisClient(
    api_key=os.environ["DECIONIS_API_KEY"],
    base_url="https://api.decionis.com",
    tenant_id="bank_001",
)

def execute_transfer():
    return {"submitted": True}

execution = client.enforce(
    {
        "actor": {"id": "agent_42", "type": "AI_AGENT"},
        "action": {"type": "TRANSFER_FUNDS", "resource": "liquidity_pool"},
        "context": {"workflow": "treasury_ops", "environment": "production"},
        "policy_refs": ["treasury-transfer-policy-v3"],
        "idempotency_key": "txn_<unique_execution_id>",
    },
    execute=lambda decision: execute_transfer(),
)

decision = execution.decision
dossier = client.create_dossier(decision.decision_id)
health = client.ping()

print(decision.status.value)
print(decision.dossier_url)
print(dossier["decision_id"])
print(health["status"])

Use one idempotency key per execution intent. Reusing the same key returns the same Decionis decision replay instead of creating a new governed decision record.

Use evaluate for decision-only diagnostics, simulations, or pre-flight observability. Production gates should bind the Decionis decision to the code that performs the action by passing execute=... into enforce.

decision = client.evaluate(
    {
        "actor": {"id": "checkout-worker", "type": "SERVICE"},
        "action": {"type": "CAPTURE_PAYMENT", "resource": "order_9812"},
        "context": {"surface": "shopify", "channel": "checkout"},
        "policy_refs": ["commerce-integrity-policy-v1"],
    }
)

enforce fails closed for non-allowed decisions before the callback runs:

from decionis import DecionisBlockedException

try:
    execution = client.enforce(
        {
            "actor": {"id": "checkout-worker", "type": "SERVICE"},
            "action": {"type": "CAPTURE_PAYMENT", "resource": "order_9812"},
            "context": {"surface": "shopify", "channel": "checkout"},
            "policy_refs": ["commerce-integrity-policy-v1"],
        },
        execute=lambda decision: payment_gateway.capture("order_9812"),
    )
except DecionisBlockedException as exc:
    print(exc.decision_id)
    print(exc.status.value)
    print(exc.dossier_url)

Decision-only enforce(request) remains available during the 0.x transition, but it is deprecated. Use evaluate(request) for diagnostics and bound enforce(request, execute=...) for production gates.

execution = client.enforce(request, execute=lambda decision: run_job(), shadow=True)
assert execution.shadow_mode is True

Execution authority: no grant, no execution

ExecutionAuthorityClient runs a consequential action only after Decionis authorizes that exact intent and issues a single-use grant, and only after you claim that grant. A changed amount, account or target is a different intent, and its grant does not claim.

Step	Call	Route
Ask for a grant	issue_grant(request)	POST /v1/authority/grants
Check it without using it	verify_grant(token, request)	GET /v1/authority/grants/{grantId}
Claim it once, bound to the exact parameters	claim_grant(token, request)	POST /v1/authority/grants/{grantId}/claims
Record what happened	record_receipt(receipt)	POST /v1/authority/grants/{grantId}/receipts
Follow a managed Presence escalation	get_escalation, wait_for_authorization	GET /v1/authority/escalations/{escalationId}

enforce_and_execute runs the whole sequence and fails closed:

from decimal import Decimal

from decionis import AuthorityRequest, ExecutionAuthorityClient, ExecutorKey

authority = ExecutionAuthorityClient(api_key=os.environ["DECIONIS_API_KEY"])

request = AuthorityRequest.create(
    tenant_id=org_id,
    actor={"id": "ap-bot", "type": "SERVICE"},
    action={
        "type": "create_vendor_payment",
        "resource": "erp:vendor:V-1009",
        "parameters": {"amount": Decimal("18000.50"), "currency": "EUR", "vendor_id": "V-1009"},
    },
    downstream_target={"system": "sap", "operation": "create_payment"},
)

# The key your payments API issued to this executor.
executor_key = ExecutorKey.ed25519("payments-executor-1", os.environ["EXECUTOR_KEY_PEM"])


def release(grant):
    dispatch = grant.sign_dispatch(executor_key, path="/v1/wires")
    return payments_api.post(dispatch.path, content=dispatch.body, headers=dispatch.headers)


run = authority.enforce_and_execute(request, release)
if not run.executed:
    # BLOCKED_BY_POLICY, NO_EXECUTION_GRANT, GRANT_NOT_REDEEMABLE or AUTHORITY_ERROR
    log.warning("Payment not released: %s", run.block_reason)

• The action runs at most once, inside the claimed grant's lease.
• grant.sign_dispatch(key, path=...) signs the effecting request so the system of record can verify it at VP-2 of AgentSafe's Verifying Provider Profile: an RFC 9421 signature, with the executor key the provider issued you (ExecutorKey.ed25519 or ExecutorKey.hmac_sha256), over the method, path, body digest, idempotency key, intent hash, grant id, decision id and the authority's claim attestation. The provider then checks the attestation against /.well-known/decionis-execution-grant-jwks.json, refuses a second presentation of the grant, and checks that the body is the parameters the authority bound. So the body defaults to the intent's parameters as RFC 8785 JSON: send dispatch.body and dispatch.headers exactly. The headers match the AgentSafe executor's byte for byte, and AgentSafe's own verifier accepts them.
• If the action raises, an INDETERMINATE receipt is recorded and the exception propagates. Classify a certain failure with ExecutionOptions(classify_failure=lambda error: "FAILED").
• A returned value is digested as RFC 8785 JSON into the receipt's effect evidence. A Protocol 1.1 grant records the receipt without that confirmation and notes PROTOCOL_1_1_EFFECT_EVIDENCE_REQUIRED.
• SHADOW and PARALLEL requests observe only: they never authorize.
• With escalation=ManagedEscalationRequest(), an ESCALATE decision carries a managed-escalation locator. wait_for_authorization polls it until Presence approves (GRANT_READY, with the decision whose grant you claim) or the intent expires.

Numbers are hashed as Decionis reads them. An int beyond 2^53 or a Decimal with more precision than a double holds is refused with DECIONIS_INTENT_NUMBER_INEXACT, so the amount Decionis authorizes is the amount you send. Pass such values as strings. The intent hash, execution payload digest and grant id are held to the shared vectors in sdks/test/authority-vectors.json, the same ones @decionis/sdk and the Decionis server pass.

Interceptors

Decorators keep execution policy outside the application while giving Decionis a clear interception point.

import os

from decionis import DecionisClient, decionis_gate

client = DecionisClient(
    api_key=os.environ["DECIONIS_API_KEY"],
    tenant_id="trading_client_001",
)


@decionis_gate(
    client=client,
    action="OPEN_POSITION",
    policy="cfd-risk-policy",
    actor={"id": "cfd_bot_7", "type": "TRADING_BOT"},
)
def open_position(order):
    return broker.open_position(order)

Policy Encoding

Most applications should not call policy encoding. Use it only from an internal policy authoring or deployment pipeline that already has a reviewed Decionis policy bundle artifact. The SDK forwards that artifact to Decionis and returns the accepted artifact metadata; it does not evaluate policy rules locally.

Commerce policy authoring in this checkout is an unreleased source candidate. The published 0.2.0 package predates this support. The optional commerce_preflight field carries reviewed server-owned policy configuration, not facts for an action or client-side policy logic. Its spelling remains commerce_preflight. Omitted configuration stays omitted; a present invalid block is rejected before submission, including on a modified PolicyBundle instance.

Save a reviewed canonical bundle as reviewed-commerce-policy.json. The policy encoding documentation includes a complete synthetic example with P01 enabled and P02–P11 explicitly disabled; those settings are not production recommendations. Configure the authoring client with a credential for that bundle's organization.

import json
import os

from decionis import DecionisClient

with open("reviewed-commerce-policy.json", encoding="utf-8") as source:
    reviewedBundle = json.load(source)
authoring = DecionisClient(
    api_key=os.environ["DECIONIS_POLICY_API_KEY"],
    base_url="https://api.decionis.com",
    tenant_id=reviewedBundle["org_id"],
)
encoding = authoring.encode_policy(
    reviewedBundle,
    idempotency_key="commerce-review-example-v1",
)

print(encoding.artifact_id)

A successful artifact submission does not establish activation or which policy a later evaluation selects. With the matching backend, a credential with VIEWER access and policy:read (or accepted broader scope) can inspect the selected configuration:

report = authoring.policies.commerceReadiness({
    "org_id": reviewedBundle["org_id"],
    "policy_version": reviewedBundle["version"],
})
print(report["checks"], report["counts"])

This is a read-only GET to /v1/protocol/policies/commerce/readiness, not a new MCP tool or AWS facade route. Its sixteen rows distinguish enabled, disabled, missing, unsupported and unavailable. configuration_complete means all sixteen checks are explicit; all_disabled means all sixteen are false. Neither flag approves an action, activates policy or establishes connector or release readiness. HTTP 200 may report missing, unsupported or unavailable configuration. The SDK rejects invalid or mismatched reports; it returns accepted reports unchanged.

FastAPI

import os

from fastapi import FastAPI

from decionis import DecionisClient
from decionis.middleware.fastapi import FastAPIDecionisMiddleware

app = FastAPI()
client = DecionisClient(api_key=os.environ["DECIONIS_API_KEY"], tenant_id="bank_001")

app.add_middleware(
    FastAPIDecionisMiddleware,
    client=client,
    build_request=lambda scope: {
        "actor": {"id": "api", "type": "SERVICE"},
        "action": {"type": "HTTP_REQUEST"},
        "context": {"path": scope["path"]},
        "policy_refs": ["api-execution-policy-v1"],
    },
)

Configuration

client = DecionisClient(
    api_key=os.environ["DECIONIS_API_KEY"],
    base_url="https://api.decionis.com",
    timeout=10.0,
    max_retries=2,
    retry_backoff=0.25,
    tenant_id="bank_001",
)

Changelog

v0.3.0

• Added grant-required execution authority (ExecutionAuthorityClient) at parity with @decionis/sdk: issue a grant for an exact intent, claim it once with the same binding checks, run the action, record a receipt; managed Presence escalation with bounded backoff; fail-closed enforce_and_execute.
• Added decionis.canonical: the intent hash and RFC 8785 execution payload digest the Decionis server computes, held to sdks/test/authority-vectors.json.
• Added executor request signing (ExecutorKey, GrantContext.sign_dispatch): RFC 9421 signatures a VP-2 verifying provider accepts, matching the AgentSafe executor's headers byte for byte.
• Additive: evaluate, enforce, decorators and middleware are unchanged.

v0.2.0

• Introduced bound enforcement with enforce(request, execute=..., shadow=...) so execution happens inside the SDK-controlled gate.
• Deprecated decision-only enforce(request) in favor of evaluate(request) for diagnostics and bound enforce for production execution.
• Updated decorators and middleware to execute handlers only from the SDK-controlled enforcement callback.

v0.1.3

• Routed SDK evaluation through the canonical /v1/protocol/evaluate-decision endpoint.
• Normalized protocol outcomes into SDK decision statuses while preserving the protocol response for audit/debug context.
• Kept policy validation and bundle encoding aligned with the API gateway routes used for SDK provisioning.

v0.1.2

• Focused the package description on SDK installation, client usage, interception, enforcement, FastAPI middleware, and policy encoding.

v0.1.1

• Published the professional PyPI project description and package metadata for the Decision Protocol positioning.
• Added ping() as a connectivity alias for health().
• Updated default SDK API routing to https://api.decionis.com.

v0.1.0

• Introduced Decionis execution interceptors for Python applications and FastAPI services.
• Introduced Cryptographic Decision Dossiers for verifiable audit trails, signed decisions, dossier URLs, and local signature verification.
• Released the initial Protocol Logic Engine integration surface for policy bundle encoding, validation, evaluation, and enforcement.

Release

The package is ready for PyPI Trusted Publishing from GitHub Actions. Releases are triggered from GitHub Releases and start at 0.1.0.