specora-runtime 0.2.0

Python SDK for Specora Runtime Authority enforcement

Specora Runtime SDK (Python)

Thin Python client SDK for Specora Runtime Authority enforcement. Wrap your AI agent tool calls with deterministic runtime governance.

Installation

pip install specora-runtime

Quickstart

from specora_runtime import SpecoraClient, CompletionStatus

client = SpecoraClient(
    base_url="https://api.specora.ai",
    api_key="sk_...",
    org_id="your-org-uuid",
)

# Wrap tool execution with enforcement
with client.enforced(
    action_type="db_write",
    scope={"table": "users"},
    args={"where": {"id": 1}, "set": {"name": "Alice"}},
    estimated_cost=0.02,
    is_write_op=True,
) as ctx:
    # Your tool execution here
    result = execute_database_write()
    ctx.complete(status=CompletionStatus.SUCCESS)

Features

• enforce() - Request enforcement decision before execution
• enforced() - Context manager with auto-completion reporting
• simulate() - Dry-run enforcement check (no reservations)
• Fail-closed by default - Network errors block execution
• Idempotency - request_id ensures exactly-once processing
• Typed exceptions - SpecoraBlockedError, SpecoraSuspendedError

Usage

enforce() - Direct Enforcement

result = client.enforce(
    action_type="api_call",
    scope={"service": "stripe"},
    args={"method": "charge"},
    estimated_cost=0.50,
    estimated_volume=1,
    is_write_op=True,
)

if result.is_allowed:
    # Execute the action
    pass

enforced() - Context Manager

The context manager handles completion reporting automatically:

from specora_runtime import CompletionStatus

with client.enforced(
    action_type="file_mutation",
    scope={"repo": "infra", "path": "prod.tf"},
    args={"op": "write"},
    estimated_cost=0.01,
    is_write_op=True,
) as ctx:
    # Execute your tool
    write_file()

    # Explicit completion (optional - auto-completes on exit)
    ctx.complete(status=CompletionStatus.SUCCESS, cost_actual=0.008)

Behavior:

• Raises SpecoraBlockedError if action is blocked
• Raises SpecoraSuspendedError if approval is required
• Auto-completes with SUCCESS on normal exit
• Auto-completes with FAILURE if exception occurs

simulate() - Dry-Run

sim = client.simulate(
    action_type="schema_migration",
    scope={"db": "prod"},
    args={"migration": "2026_03_add_idx"},
    estimated_cost=5.0,
    is_write_op=True,
)

print(f"Would be: {sim.decision}")  # allow, block, or suspend
print(f"Blocked reason: {sim.blocked_reason}")

Simulation mode:

• Returns decision without making reservations
• Does NOT require completion reporting
• Does NOT raise on block/suspend

Fail Mode

from specora_runtime import FailMode

# Default: CLOSED - errors raise FailClosedError
client = SpecoraClient(
    base_url="https://api.specora.ai",
    api_key="sk_...",
    org_id="...",
    fail_mode=FailMode.CLOSED,
)

# Alternative: OPEN - errors return allow (with warning)
client = SpecoraClient(
    base_url="https://api.specora.ai",
    api_key="sk_...",
    org_id="...",
    fail_mode=FailMode.OPEN,
)

CLOSED (default):

• Network timeouts raise FailClosedError
• Server errors (5xx) raise FailClosedError
• Action is NOT executed

OPEN:

• Network/server errors return EnforcementResult(decision=ALLOW, source="fail_open")
• Action MAY proceed (caller decides)

Note: 4xx client errors (400, 401, 403) always raise regardless of fail_mode.

Idempotency

All requests support idempotency via request_id:

from uuid import uuid4

request_id = uuid4()

# First call
result1 = client.enforce(
    action_type="payment",
    scope={"account": "123"},
    args={"amount": 100},
    request_id=request_id,
)

# Duplicate call with same request_id returns same journal entry
result2 = client.enforce(
    action_type="payment",
    scope={"account": "123"},
    args={"amount": 100},
    request_id=request_id,
)

assert result1.journal_id == result2.journal_id

If request_id is omitted, a UUID is auto-generated.

Error Handling

from specora_runtime import (
    SpecoraBlockedError,
    SpecoraSuspendedError,
    FailClosedError,
)

try:
    with client.enforced(...) as ctx:
        do_something()
except SpecoraBlockedError as e:
    print(f"Blocked: {e.reason}")
    print(f"Journal ID: {e.journal_id}")
except SpecoraSuspendedError as e:
    print(f"Approval required: {e.approval_source}")
except FailClosedError as e:
    print(f"Service unavailable: {e}")

Callbacks

Register callbacks for observability:

def on_decision(result):
    print(f"Decision: {result.decision}")
    metrics.record_enforcement(result)

def on_error(exc):
    logging.error(f"Specora error: {exc}")

client = SpecoraClient(
    base_url="https://api.specora.ai",
    api_key="sk_...",
    org_id="...",
    on_decision=on_decision,
    on_error=on_error,
)

Configuration

Parameter	Default	Description
base_url	-	Specora API URL
api_key	-	API key (Bearer token)
org_id	-	Organization UUID
project_id	None	Project scope (optional)
agent_id	None	Agent identifier (optional)
fail_mode	CLOSED	CLOSED or OPEN
timeout_seconds	10	Request timeout
retries	2	Retry attempts for transient errors

Security Notes

• Scope must be explicit - Always specify meaningful scope for audit trail
• request_id is idempotent - Use for exactly-once semantics
• API key is Bearer token - Store securely, never log

Versioning

This SDK follows Semantic Versioning:

• MAJOR: Breaking changes to public API
• MINOR: New features, backward compatible
• PATCH: Bug fixes, backward compatible

API contract: The SDK is compatible with Specora Runtime Authority v1.x.

License

Apache 2.0 - See LICENSE for details.