Metadata-Version: 2.5
Name: decionis
Version: 0.3.0
Summary: Enterprise Decision Protocol for policy-enforced automation and verifiable audit trails.
Project-URL: Homepage, https://decionis.com
Project-URL: Documentation, https://docs.decionis.com
Author-email: Decionis <sdk@decionis.ai>
License: MIT
Keywords: audit,decionis,execution-gate,governance,interceptor,policy,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema<5,>=4.22
Requires-Dist: pydantic>=2.7
Requires-Dist: rfc3339-validator>=0.1.4
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.111; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=3; extra == 'flask'
Provides-Extra: lint
Requires-Dist: mypy>=1.10; extra == 'lint'
Requires-Dist: ruff>=0.5; extra == 'lint'
Requires-Dist: types-jsonschema>=4.22; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: respx>=0.21; extra == 'test'
Description-Content-Type: text/markdown

# Decionis Python SDK

[![PyPI version](https://img.shields.io/pypi/v/decionis.svg)](https://pypi.org/project/decionis/)
[![Python versions](https://img.shields.io/pypi/pyversions/decionis.svg)](https://pypi.org/project/decionis/)
[![License](https://img.shields.io/pypi/l/decionis.svg)](https://pypi.org/project/decionis/)

**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

```bash
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.

```python
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`.

```python
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:

```python
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.

```python
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:

```python
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](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/authority/verifying-provider.md):
  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.

```python
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](https://docs.decionis.com/policy-encoding#bundle-contract)
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.

```python
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:

```python
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

```python
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

```python
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`.
