Metadata-Version: 2.4
Name: traceact
Version: 0.1.1
Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
Author: Mohammed Shehu
License-Expression: MIT
Project-URL: Homepage, https://github.com/traceact/traceact
Project-URL: Repository, https://github.com/traceact/traceact
Project-URL: Documentation, https://github.com/traceact/traceact/blob/main/USAGE.md
Project-URL: Issues, https://github.com/traceact/traceact/issues
Project-URL: Author, https://mohammedshehu.com
Keywords: tracing,observability,debugging,devtools,ai-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Logging
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Dynamic: license-file

# TraceAct

[![PyPI version](https://img.shields.io/pypi/v/traceact.svg)](https://pypi.org/project/traceact/)
[![Python versions](https://img.shields.io/pypi/pyversions/traceact.svg)](https://pypi.org/project/traceact/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

X-ray vision for Python code.

TraceAct is a lightweight Python package for action-level tracing. It records the full story of what happens when a function runs, including every step taken, resource touched, event recorded, and failure encountered, so you or your agent can understand what actually happened.

## Install

```bash
pip install traceact
```

Or from source:

```bash
pip install -e .
```

## Quick start

```python
from traceact import traced_action, configure, TraceConfig, JsonlSink

configure(
    config=TraceConfig(sink_mode="blocking"),
    sinks=[JsonlSink("data/traces.jsonl")],
)

@traced_action(action="note.create", kind="app", actor="user")
def create_note(title, body):
    ...
```

## Manual tracing

```python
from traceact import ActionTrace

with ActionTrace.start(action="note.create", kind="app") as trace:
    trace.input({"title": "Hello"})
    trace.step("Validated input")
    trace.event(kind="db", operation="insert", target="notes")
    trace.output({"note_id": "note_123"})
```

## Concepts

| Concept | Meaning |
|---|---|
| `Trace` | The full story of one action |
| `Step` | A human-readable timeline marker |
| `Event` | A structured operation (db, http, file, model, etc.) |
| `Touch` | A resource involved in the trace |
| `Sink` | Where the trace is written |

## Requirements

Python 3.9+. No runtime dependencies.

## License

MIT

---

Built by [Mo Shehu](https://mohammedshehu.com).
