Metadata-Version: 2.4
Name: pydantic-ai-trace
Version: 0.1.5
Summary: Fast local web viewer for pydantic-ai traces (list[ModelMessage] JSON dumps)
Project-URL: Repository, https://github.com/moritzwilksch/pydantic-ai-trace
Author: Moritz Wilksch
License-Expression: MIT
License-File: LICENSE
Keywords: agent,llm,pydantic-ai,trace,viewer
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.12
Requires-Dist: starlette>=0.40
Requires-Dist: uvicorn>=0.30
Requires-Dist: watchfiles>=0.24
Description-Content-Type: text/markdown

# pydantic-ai-trace

Use `pydantic-ai-trace` when you need to inspect an agent run from a JSON dump. Give it a [pydantic-ai](https://ai.pydantic.dev) `list[ModelMessage]` dump and it opens the run in a browser view.

It is a lightweight local tool. Point it at a trace or a directory of traces and it reads the files from disk, reloads them when they change, and exports individual traces as self-contained HTML files. Your traces stay on disk, with no hosted service or account.

<img width="1323" height="1008" alt="Screenshot of a trace open in pydantic-ai-trace" src="https://github.com/user-attachments/assets/cf4f0866-ae4f-449f-8967-1ff6a26a2638" />

## What you can inspect

- The full request and response sequence, including prompts, text, thinking, tool calls, tool results, and unknown parts
- Tool calls paired with their results, including results in later messages
- Model, provider, timing, and token usage
- A searchable directory tree for `.json` and `.jsonl` traces
- Collapsible large values, rendered Markdown, and keyboard navigation
- One-click copying as a compact text transcript that preserves request and response order
- CLI rendering of the same compact transcript for use by people, scripts, and AI agents

## Run from a checkout

This project uses [pixi](https://pixi.sh). Build the bundled frontend once, then run `paitrace` with a trace file or directory.

```bash
pixi run build-frontend
pixi run paitrace trace.json
```

## Usage

```bash
# View one trace
pixi run paitrace trace.json

# Browse a directory tree of traces
pixi run paitrace ./my-traces/

# Write one trace to a standalone HTML file
pixi run paitrace export trace.json -o trace.html

# Choose a trace line when exporting a multi-trace JSONL file
pixi run paitrace export runs.jsonl --line 2

# Print the browser's compact text representation to stdout
pixi run paitrace text trace.json

# Select a trace from JSONL, or write the text to a file
pixi run paitrace text runs.jsonl --line 2
pixi run paitrace text trace.json -o trace.txt
```

`paitrace text` writes only the transcript to stdout by default, so it can be piped directly into
another command. Multi-trace JSONL files require `--line`, just as HTML export does.

The viewer binds to `127.0.0.1:1205` and opens your browser. Pass `--port`, `--host`, or `--no-open` to change that behavior.

## Trace files

The viewer reads the JSON emitted by `ModelMessagesTypeAdapter.dump_json(messages)`:

- `.json`: one bare JSON array of `ModelMessage` objects
- `.jsonl`: one such array per line

When you open a directory, each line in a multi-trace `.jsonl` file is available as a separate trace.

## Development

Run the API and frontend in separate terminals while working on the viewer.

```bash
pixi run dev-api ./trace.json  # API with reload on port 1205
pixi run dev-web               # Vite with HMR, proxying /api
```

```bash
pixi run test        # pytest and vitest
pixi run lint        # ruff, prettier, and eslint
pixi run typecheck   # pyright and TypeScript
pixi run build       # bundled frontend plus sdist and wheel
```

## Releasing

Create and publish a GitHub release with a `vX.Y.Z` tag. The package version is derived from that
tag, so no source file needs a version bump. Publishing the release triggers GitHub Actions to run
the full check suite, build the frontend into the wheel and source distribution, publish both to
PyPI using trusted publishing, and attach them to the GitHub release. Configure a `pypi`
environment in GitHub and add this repository as a trusted publisher for the `pydantic-ai-trace`
project on PyPI before the first release.
