EctoLedger SDK — Python

A typed async REST client for EctoLedger with built-in LangChain and AutoGen support.

EctoLedger is a tamper-proof audit trail for AI agents. It helps you prove what your AI did, in what order, and whether actions stayed within policy.

This is not a crypto trading product. Here, "ledger" means an auditable evidence log for AI behavior.

This SDK lets you create sessions, append events, and export verifiable .elc audit certificates from your Python applications.

Installation

# Core client only
pip install ectoledger-sdk

# With LangChain support
pip install 'ectoledger-sdk[langchain]'

# With AutoGen support
pip install 'ectoledger-sdk[autogen]'

Quick start

import asyncio
from ectoledger_sdk import LedgerClient

async def main():
    async with LedgerClient("http://localhost:3000", bearer_token="your_token") as client:
        sessions = await client.list_sessions()
        print(f"Found {len(sessions)} active sessions.")

asyncio.run(main())

Constructor

LedgerClient(
    base_url="http://localhost:3000",  # Server URL (required in production)
    bearer_token=None,                 # Optional RBAC token
    timeout=30.0,                      # HTTP timeout in seconds
)

Note: The default base_url only works for local development. In Docker Compose or Kubernetes you must pass the correct service URL.

Error handling

All methods raise LedgerSdkError on non-2xx responses:

from ectoledger_sdk import LedgerSdkError

try:
    await client.verify_chain(session_id)
except LedgerSdkError as exc:
    print(exc.status_code, exc.body)

LangChain integration

from ectoledger_sdk.langchain import LedgerTool

ledger_tool = LedgerTool(
    session_id="your-session-uuid",
    base_url="http://localhost:3000",
)
# Add ledger_tool to your agent's tool list

AutoGen integration

from ectoledger_sdk.autogen import LedgerHook

hook = LedgerHook(session_id="your-session-uuid")
hook.attach(my_agent)

Testing

cd sdk/python
pip install ".[dev]"
pytest tests/ -v

Troubleshooting

Connection errors or timeouts

• Ensure base_url points to the running EctoLedger server (http://localhost:3000 in local default setups).
• In Docker/Kubernetes, use the correct service hostname instead of localhost.
• Check that your network path allows access to /api/status.

Authentication failures (401/403)

• Verify bearer_token is valid and has sufficient RBAC scope.
• Confirm token creation/revocation status in the server UI/API.

Unexpected API errors

• Catch LedgerSdkError and inspect status_code + body for exact server response.
• Check backend mode constraints (some commands/features require PostgreSQL backend).

API Reference

Status

Sessions

Chat

Events

Chain Verification & Compliance

Reports & Verifiable Credentials

Metrics

Configuration

Tripwire Configuration

Policies

RBAC Tokens

Webhooks

Approval Gates

Admin

Licensing & Contact

Licensed under the Apache License 2.0.

Maintained by Björn Roman Kohlberger.