pydantic-ai-trace 0.1.5

Fast local web viewer for pydantic-ai traces (list[ModelMessage] JSON dumps)

pydantic-ai-trace

Use pydantic-ai-trace when you need to inspect an agent run from a JSON dump. Give it a pydantic-ai 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.

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. Build the bundled frontend once, then run paitrace with a trace file or directory.

pixi run build-frontend
pixi run paitrace trace.json

Usage

# 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.

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

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.