Python Server SDK

Connect Python agents to edictum-api for rulesets, approvals, session state, SSE updates, and the decision log.

Use the Python server SDK when you want remote rulesets, human approval, shared session state, SSE hot reload, and decision log delivery through edictum-api.

Quick Start

Install

pip install edictum[yaml,server]

Add verified if you want Ed25519 signature checks:

pip install edictum[yaml,server,verified]

Create a server-backed guard

import os

from edictum import Edictum

guard = await Edictum.from_server(
    url="https://api.example.com",
    api_key=os.environ["EDICTUM_API_KEY"],
    agent_id="docs-agent",
    env="production",
    bundle_name="production-rules",
)

Use it like any other guard

async def read_file(path: str) -> str:
    return f"contents of {path}"


result = await guard.run("read_file", {"path": "README.md"}, read_file)
print(result)

Close it on shutdown

await guard.close()

`Edictum.from_server()` Options

Option	Type	What it does
`url`	`str`	Base URL for edictum-api
`api_key`	`str`	Bearer credential used for every API call
`agent_id`	`str`	Stable agent identity for rulesets, session state, and approvals
`env`	`str \| None`	Environment name. Defaults to `"production"`
`bundle_name`	`str \| None`	Named ruleset to fetch immediately. Leave `None` for server-assigned mode
`tags`	`dict[str, str] \| None`	Tags used by server-side assignment rules
`mode`	`str`	Runtime mode override
`audit_sink`	`AuditSink \| None`	Override the default `ServerAuditSink`
`approval_backend`	`ApprovalBackend \| None`	Override the default `ServerApprovalBackend`
`storage_backend`	`StorageBackend \| None`	Override the default `ServerBackend`
`auto_watch`	`bool`	Start the SSE watcher. Required for server-assigned mode
`allow_insecure`	`bool`	Allow plain HTTP to non-loopback hosts. Local-only
`verify_signatures`	`bool`	Verify Ed25519 ruleset signatures
`signing_public_key`	`str \| None`	Hex-encoded Ed25519 public key
`workflow_runtime`	`WorkflowRuntime \| None`	Attach a prebuilt local workflow runtime
`workflow_path`	`str \| Path \| None`	Load the local workflow from disk
`workflow_content`	`str \| bytes \| None`	Load the local workflow from inline YAML
`workflow_exec_evaluator_enabled`	`bool`	Enable trusted `exec(...)` workflow conditions

If bundle_name is omitted, the guard starts empty, opens the SSE stream, and waits up to 30 seconds for a server assignment.

Server SDK Components

These are lazy-imported from edictum.server:

from edictum.server import (
    EdictumServerClient,
    ServerAuditSink,
    ServerBackend,
    ServerApprovalBackend,
    ServerContractSource,
    verify_bundle_signature,
)

Component	Purpose
`EdictumServerClient`	Low-level async HTTP client with auth, retries, and TLS checks
`ServerAuditSink`	Buffers and sends decision-log events to the API
`ServerBackend`	Shared session storage for counts and workflow state
`ServerApprovalBackend`	Human approval requests and polling
`ServerContractSource`	SSE client for live ruleset updates
`verify_bundle_signature`	Ed25519 verification helper for raw YAML bytes

edictum-api Integration

These integration points are source-backed in the Python SDK:

Rulesets: GET /v1/rulesets/{bundle_name}/current
Live updates: GET /v1/stream
Session state: /v1/sessions/*
Approvals: /v1/approvals
Decision log ingestion: POST /v1/events

That means Edictum.from_server() is not a separate control plane. It is the Python client for the same API surface that ruleset delivery, approvals, state, and SSE all use.

Workflow Gates With Server-Backed Rules

In M1, the API provides rulesets and runtime services. The workflow stays local and explicit:

guard = await Edictum.from_server(
    url="https://api.example.com",
    api_key=os.environ["EDICTUM_API_KEY"],
    agent_id="docs-agent",
    bundle_name="production-rules",
    workflow_path="workflow.yaml",
    workflow_exec_evaluator_enabled=True,
)

That split is deliberate:

Rulesets are remote and hot-reloadable.
Workflow Gates are attached locally.
The same session can emit workflow snapshots into the decision log.

Low-Level Client Example

from edictum.server import EdictumServerClient

client = EdictumServerClient(
    "https://api.example.com",
    api_key=os.environ["EDICTUM_API_KEY"],
    agent_id="docs-agent",
    env="production",
    bundle_name="production-rules",
)

payload = await client.get("/v1/rulesets/production-rules/current", env="production")

Use the low-level client only when you need to manage transport yourself. For most applications, Edictum.from_server() is the right entry point.

On this page