Kora Python SDK

Python SDK for the Kora authorization engine. Handles Ed25519 signing, nonce generation, canonical JSON serialization, idempotent retry, and offline seal verification.

Installation

pip install kora-sdk

Or install from source:

pip install -e sdk/python

Requirements: Python 3.9+, PyNaCl >= 1.5.0, requests >= 2.28.0

Quick Start

from kora import Kora

# Initialize with the secret key returned from agent creation
kora = Kora("kora_agent_sk_...")

# Authorize a spend
auth = kora.authorize(
    mandate="mandate_abc123",
    amount=50_00,        # EUR 50.00
    currency="EUR",
    vendor="aws",
    category="compute",  # required if mandate has category_allowlist
)

if auth.approved:
    print(f"Approved: {auth.decision_id}")
    print(f"Daily remaining: {auth.limits_after_approval['daily_remaining_cents']}")
else:
    print(f"Denied: {auth.reason_code}")
    print(f"Hint: {auth.denial.hint}")

Usage

Authorize a Spend

from kora import Kora

kora = Kora(
    "kora_agent_sk_...",
    base_url="http://localhost:8000",  # default
    ttl=300,          # default TTL in seconds
    max_retries=2,    # automatic idempotent retry on network error
)

result = kora.authorize(
    mandate="mandate_abc123",
    amount=50_00,
    currency="EUR",
    vendor="aws",
    category="compute",
)

Result Properties

result.approved        # bool — True if APPROVED
result.decision        # "APPROVED" or "DENIED"
result.decision_id     # UUID of the authorization decision
result.reason_code     # "OK", "DAILY_LIMIT_EXCEEDED", etc.
result.executable      # bool — True if payment can be executed
result.is_valid        # bool — True if TTL has not expired
result.is_enforced     # bool — True if enforcement_mode == "enforce"
result.enforcement_mode  # "enforce" or "log_only"

# On denial:
result.denial.hint            # Human-readable suggestion
result.denial.actionable      # Machine-readable corrective values
result.denial.failed_check    # Which pipeline step failed

# On approval:
result.limits_after_approval  # Remaining daily/monthly budget

# Evaluation trace:
result.evaluation_trace.steps        # List of pipeline step results
result.evaluation_trace.total_duration_ms  # Total evaluation time

# Notary seal:
result.notary_seal.signature    # Ed25519 signature (base64)
result.notary_seal.public_key_id
result.notary_seal.algorithm    # "Ed25519"

# Trace URL (for debugging denials):
result.trace_url  # e.g. http://localhost:8000/v1/authorizations/<id>/trace

Handle Denials

result = kora.authorize(
    mandate="mandate_abc123",
    amount=999_99,
    currency="EUR",
    vendor="aws",
)

if not result.approved:
    print(f"Denied: {result.reason_code}")
    print(f"Hint: {result.denial.hint}")

    # Machine-readable corrective values
    if result.reason_code == "DAILY_LIMIT_EXCEEDED":
        available = result.denial.actionable["available_cents"]
        print(f"Available budget: {available} cents")

    if result.reason_code == "VENDOR_NOT_ALLOWED":
        allowed = result.denial.actionable["allowed_vendors"]
        print(f"Allowed vendors: {allowed}")

    # Full trace URL for debugging
    print(f"Trace: {result.trace_url}")

Verify Notary Seal (Offline)

from base64 import b64decode

# Kora's public key (from your deployment)
kora_public_key = b64decode("...")

is_valid = kora.verify_seal(result, kora_public_key)
print(f"Seal valid: {is_valid}")

Simulation Mode

Test denial scenarios without affecting state. Requires an admin key with simulation_access=true.

result = kora.authorize(
    mandate="mandate_abc123",
    amount=100,
    currency="EUR",
    vendor="aws",
    simulate="DAILY_LIMIT_EXCEEDED",
    admin_key="kora_admin_...",
)

assert result.simulated is True
assert result.decision == "DENIED"
assert result.reason_code == "DAILY_LIMIT_EXCEEDED"
assert result.notary_seal is None  # no seal in simulation

OpenAI Function Tool Schema

Generate an OpenAI-compatible function tool definition for use with LLM agents:

tool = kora.as_tool("mandate_abc123")
# Returns:
# {
#     "type": "function",
#     "function": {
#         "name": "kora_authorize_spend",
#         "description": "Authorize a spend against a Kora mandate...",
#         "parameters": {
#             "type": "object",
#             "properties": {
#                 "amount_cents": {"type": "integer", "description": "..."},
#                 "currency": {"type": "string", "description": "..."},
#                 "vendor_id": {"type": "string", "description": "..."},
#             },
#             "required": ["amount_cents", "currency", "vendor_id"]
#         }
#     }
# }

# With category enum constraint:
tool = kora.as_tool("mandate_abc123", category_enum=["compute", "api_services"])

Use with OpenAI:

import openai

client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Buy $50 of AWS compute"}],
    tools=[kora.as_tool("mandate_abc123")],
)

Agent Self-Correction Pattern

from kora import Kora

kora = Kora("kora_agent_sk_...")

# First attempt — too large
auth = kora.authorize(mandate="mandate_abc123", amount=999_99, currency="EUR", vendor="aws")

if not auth.approved and auth.reason_code == "DAILY_LIMIT_EXCEEDED":
    # Read the actionable hint
    available = auth.denial.actionable["available_cents"]
    print(f"Budget available: {available} cents, retrying...")

    # Retry with corrected amount
    auth = kora.authorize(mandate="mandate_abc123", amount=available, currency="EUR", vendor="aws")
    print(f"Second attempt: {auth.decision}")  # APPROVED

API Reference

Kora(key_string, base_url=None, ttl=300, max_retries=2)

kora.authorize(**kwargs) -> AuthorizationResult

kora.verify_seal(result, public_key) -> bool

Verify the Ed25519 notary seal offline.

kora.as_tool(mandate, category_enum=None) -> dict

Generate OpenAI function tool schema.