traceledger 0.1.0

Python SDK for TraceLedger — immutable audit trails for AI agent decisions

TraceLedger Python SDK

Immutable audit trails for AI agent decisions.

Installation

pip install traceledger

Quick Start

from traceledger import TraceLedger

tl = TraceLedger(api_key="tlk_your_api_key_here")

with tl.trace(agent_name="my-agent", task_description="Process loan application") as trace:
    trace.anchor_input(
        data_type="loan_application",
        description="Applicant application data",
        data={"applicant_id": "APP-1234", "amount": 450000}
    )

    trace.capture_decision(
        decision="Approved at 5.2% APR",
        reasoning="DTI ratio 28%, credit score 740, stable employment",
        alternatives=["Deny", "Approve at higher rate"],
        confidence="high"
    )

    trace.anchor_output(
        output_type="loan_decision",
        description="Loan approval with terms",
        data={"decision": "approved", "apr": 5.2}
    )

Every trace entry is cryptographically hash-chained. The audit trail is immutable and independently verifiable.

Features

• Session-scoped traces via context manager — automatic session_start/session_end
• Decision capture with reasoning, alternatives, and confidence
• Input/output anchoring — record what data went in and what came out
• Tool call tracking — record external API calls and their results
• Reasoning steps — capture the evidence chain as it's built
• Hash-chained immutability — every entry is cryptographically sealed

API Reference

TraceLedger(api_key, base_url, timeout)

Initialize the client.

• api_key (str): Your API key (starts with tlk_).
• base_url (str): API URL. Defaults to https://app.traceledger.io.
• timeout (float): Request timeout in seconds. Defaults to 30.

TraceLedger.trace(agent_name, agent_version, task_description, metadata)

Returns a TraceSession context manager.

TraceSession methods

• capture_decision(decision, reasoning, alternatives, confidence) — Record a decision
• anchor_input(data_type, description, data) — Record input data
• anchor_output(output_type, description, data) — Record output/artifact
• capture_tool_call(tool_name, arguments, result) — Record a tool call
• capture_reasoning(step, observation, conclusion, evidence) — Record a reasoning step

License

MIT — TraceLedger, Inc.