English | 简体中文

ActLedger Python SDK

Receipt verifier, local ledger client, and an optional LangGraph adapter. The runtime dependency is cryptography. There is no console script with the same name as the npm packages. The entry point is python -m actledger.

Install

From a clone of this repository:

python3 -m venv .venv
.venv/bin/python -m pip install -e "./python[test]"

With the LangGraph adapter:

.venv/bin/python -m pip install -e "./python[test,langgraph]"

With the Claude Agent SDK adapter:

.venv/bin/python -m pip install -e "./python[test,claude]"

With the OpenAI Agents SDK adapter:

.venv/bin/python -m pip install -e "./python[test,openai-agents]"

Python >=3.10. Use the stdlib venv and pip. This package is not uploaded to PyPI yet.

Verify

python -m actledger verify receipts.jsonl --keys keys.json [--secrets secrets.jsonl] [--json]

On success, stdout is OK .... On failure, stderr is FAIL seq=.... Exit codes match the TypeScript CLI. --json keeps the engine's camelCase field names (byMode, byAssurance, byVersion) so the report can be compared with TypeScript.

Local client

Ledger(mode="local", dir=...) does not implement the ledger in Python. It starts the TypeScript CLI command actledger rpc and calls the same engine with one JSON object per line on stdio. Approve and reject still run in another process as actledger approve / actledger reject.

The command is chosen in this order:

1. Ledger(..., command=["..."])
2. ACTLEDGER_RPC_COMMAND, split with shell rules, for example npx -y @actledger/cli rpc
3. During development: walk up from the installed package to a repository root that contains both packages/cli/src/main.ts and node_modules/tsx/dist/cli.mjs, then run the CLI source with node and tsx. The working directory is the repository root, and --dir is an absolute path.
4. After publication: actledger rpc on PATH (from npm i -g @actledger/cli)

The child process sets NODE_OPTIONS=--disable-warning=ExperimentalWarning. Diagnostics on stderr are not treated as failure.

Remote client

Ledger(mode="remote") calls @actledger/server with urllib. Set ACTLEDGER_URL and ACTLEDGER_API_KEY, or pass url and api_key. call_timeout is the per-request timeout. poll_interval defaults to 1.0 second. sweep() does not send a request. Async code uses ToolGate.async_before, async_after, and async_resume, or asyncio.to_thread. There is no AsyncLedger.

Differences from the TypeScript SDK

Public methods use snake_case. rpc params and results stay in the engine's camelCase. The mapping lives in actledger._wire.

Tests

From the repository root, run pnpm install first (parity checks and rpc need tsx):

python3 -m venv python/.venv
python/.venv/bin/python -m pip install -e "./python[test,langgraph,claude,openai-agents]"
python/.venv/bin/python -m pytest python/tests

Vector checks that do not need Node:

python/.venv/bin/python -m pytest python/tests/test_vectors.py

If langgraph is not installed, tests marked langgraph are skipped and the core package still imports. CI sets ACTLEDGER_REQUIRE_NODE=1. The job that installs langgraph also sets ACTLEDGER_REQUIRE_LANGGRAPH=1. Tests marked claude are skipped unless claude-agent-sdk is installed. The job that installs the Claude extra sets ACTLEDGER_REQUIRE_CLAUDE=1. Tests marked openai_agents are skipped unless the openai-agents distribution is installed. The job that installs that extra sets ACTLEDGER_REQUIRE_OPENAI=1. Smoke tests that call a real model also need ANTHROPIC_API_KEY or OPENAI_API_KEY and are skipped when the matching key is absent.

Longer guide: https://github.com/GEON-tt/ActLedger/blob/main/docs/en/sdk-python.md.

简体中文

回执校验器、本地账本客户端，以及可选的 LangGraph、Claude Agent SDK 和 OpenAI Agents SDK 适配器。入口是 python -m actledger，不是和 npm 包同名的 console script。Claude 适配器需要 pip install -e "./python[claude]"。OpenAI Agents 适配器需要 pip install -e "./python[openai-agents]"。没装对应 extra 时，标了 claude 或 openai_agents 的测试会跳过；CI 里安装了这些 extra 的任务会设置 ACTLEDGER_REQUIRE_CLAUDE=1 和 ACTLEDGER_REQUIRE_OPENAI=1。真实模型冒烟测试还需要 ANTHROPIC_API_KEY 或 OPENAI_API_KEY，没有密钥就跳过。

在仓库根：

python3 -m venv python/.venv
python/.venv/bin/pip install -e "./python[dev]"
python/.venv/bin/python -m actledger verify receipts.jsonl --keys keys.json

Ledger(mode="local") 通过 actledger rpc 调用 TypeScript 引擎。Ledger(mode="remote") 用标准库请求 @actledger/server，环境变量是 ACTLEDGER_URL 和 ACTLEDGER_API_KEY。批准和拒绝在本地仍用 actledger approve / actledger reject；远端用审批台。用法说明：https://github.com/GEON-tt/ActLedger/blob/main/docs/zh-CN/sdk-python.md。仓库说明：https://github.com/GEON-tt/ActLedger/blob/main/README.zh-CN.md。