Metadata-Version: 2.4
Name: traceledger
Version: 0.1.0
Summary: Python SDK for TraceLedger — immutable audit trails for AI agent decisions
Project-URL: Homepage, https://traceledger.io
Project-URL: Documentation, https://docs.traceledger.io
Project-URL: Repository, https://github.com/traceledgerhq/traceledger-sdk-python
Author-email: "TraceLedger, Inc." <brett@traceledger.io>
License: MIT
License-File: LICENSE
Keywords: agents,ai,audit,compliance,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Description-Content-Type: text/markdown

# TraceLedger Python SDK

Immutable audit trails for AI agent decisions.

## Installation

```bash
pip install traceledger
```

## Quick Start

```python
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.
