Metadata-Version: 2.5
Name: pydantic-ai-viz
Version: 0.1.0
Summary: See what your Pydantic AI agents are and what they do: blueprints, live runs and shareable replays. Unofficial, not affiliated with Pydantic.
Project-URL: Homepage, https://github.com/LowWeiLin/pydantic-ai-viz
Project-URL: Documentation, https://lowweilin.github.io/pydantic-ai-viz/
Project-URL: Repository, https://github.com/LowWeiLin/pydantic-ai-viz
Project-URL: Issues, https://github.com/LowWeiLin/pydantic-ai-viz/issues
Project-URL: Changelog, https://github.com/LowWeiLin/pydantic-ai-viz/blob/main/CHANGELOG.md
Author: pydantic-ai-viz contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agents,devtools,llm,opentelemetry,pydantic-ai,pydantic-graph,tracing,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: opentelemetry-sdk>=1.30
Requires-Dist: pydantic-ai-slim<3,>=2.60
Description-Content-Type: text/markdown

# pydantic-ai-viz

See what your [Pydantic AI](https://ai.pydantic.dev/) agents are (the blueprint) and what they do (the run) on one canvas, live or replayed. Draw any project's agents straight from its source code, without running a line of it. No API key, no account, nothing leaves your machine.

[![CI](https://github.com/LowWeiLin/pydantic-ai-viz/actions/workflows/ci.yml/badge.svg)](https://github.com/LowWeiLin/pydantic-ai-viz/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/pydantic-ai-viz.svg)](https://pypi.org/project/pydantic-ai-viz/)
[![Python versions](https://img.shields.io/pypi/pyversions/pydantic-ai-viz.svg)](https://pypi.org/project/pydantic-ai-viz/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/LowWeiLin/pydantic-ai-viz/blob/main/LICENSE)

> **Unofficial.** pydantic-ai-viz is a community project. It is not affiliated with or endorsed by Pydantic.

## Try it in 10 seconds

**See a demo.**

```bash
uvx pydantic-ai-viz demo
```

This opens a browser tab and plays a scripted support-triage agent: streamed tokens, three parallel tool calls, a retry, a delegation to a second agent and a structured result. The demo model is scripted, so it needs no API key and makes no network calls. `pydantic-ai-viz demo --list` shows the other demos.

[![An agent run in pydantic-ai-viz: blueprint canvas, span timeline and inspector](https://raw.githubusercontent.com/LowWeiLin/pydantic-ai-viz/main/docs/assets/screenshots/hero-dark.png)](https://lowweilin.github.io/pydantic-ai-viz/demo/)

The screenshot links to the [hosted demo](https://lowweilin.github.io/pydantic-ai-viz/demo/), which replays real recordings in your browser.

**See your own agents, with nothing executed.**

```bash
cd path/to/your/project
uvx pydantic-ai-viz view .
```

This reads every `.py` file below the current directory and draws each agent and graph in it: model, instructions, tools with their parameter schemas, output type, and which agent hands work to which, each with the file and line it is defined at. The code is parsed, never imported or run, so its dependencies do not have to be installed and it is safe on code you have not reviewed. A file, a module name or a GitHub repository works too: `uvx pydantic-ai-viz view gh:pydantic/pydantic-ai@v2.70.0/examples`.

[![pydantic-ai-viz view on the demos' own source: files in the sidebar, an agent with its tools and delegate, and a tool's schema and source location in the inspector](https://raw.githubusercontent.com/LowWeiLin/pydantic-ai-viz/main/docs/assets/screenshots/view-dark.png)](https://lowweilin.github.io/pydantic-ai-viz/concepts/how-view-works/)

What can and cannot be read from source is in [How view works](https://lowweilin.github.io/pydantic-ai-viz/concepts/how-view-works/), and [Real-world examples](https://lowweilin.github.io/pydantic-ai-viz/real-world/) shows it on twelve public projects.

## Watch your agent run

```bash
pip install pydantic-ai-viz    # or: uv add --dev pydantic-ai-viz
```

```python
import pydantic_ai_viz as pviz
from my_app import agent

with pviz.serve(agent, open_browser=True) as session:
    agent.run_sync("Where is my order?")
    session.wait()  # keep the viewer up until Ctrl+C
```

`serve` captures every agent run in the process from then on. You do not change how you call the agent.

Or leave your code alone and run a script under the viewer:

```bash
pydantic-ai-viz run my_script.py
```

## What you get

- **Blueprint from source.** The agent as a diagram: model, instructions, toolsets, tools with their JSON schemas, output type and delegation to other agents, across all the files of a project. `view` reads it from your source code, which is never executed; what only running the code could tell, such as a model read from an environment variable, is shown as the code that computes it. From Python, a blueprint can also be read from the agent object.
- **Live runs.** Model requests, tool calls, retries and sub-agent runs light up on the blueprint and stack up in a span timeline as they happen.
- **Inspector.** Click any span to read the conversation, tool arguments and results, token usage and the raw span attributes.
- **Graphs.** `pydantic-graph` graphs get the same treatment: nodes, decisions and edges, with the active node highlighted during a run.
- **Recordings and exports.** Scrub back through any run. Save it as a `.pviz.jsonl` recording, or export one self-contained HTML file that opens offline.

<table>
  <tr>
    <td><img alt="Agent blueprint" src="https://raw.githubusercontent.com/LowWeiLin/pydantic-ai-viz/main/docs/assets/screenshots/blueprint.png" width="400"></td>
    <td><img alt="Run timeline" src="https://raw.githubusercontent.com/LowWeiLin/pydantic-ai-viz/main/docs/assets/screenshots/run-timeline.png" width="400"></td>
  </tr>
  <tr>
    <td><img alt="Inspector" src="https://raw.githubusercontent.com/LowWeiLin/pydantic-ai-viz/main/docs/assets/screenshots/inspector.png" width="400"></td>
    <td><img alt="Graph run" src="https://raw.githubusercontent.com/LowWeiLin/pydantic-ai-viz/main/docs/assets/screenshots/graph.png" width="400"></td>
  </tr>
</table>

## How it works

`view` parses your files with Python's own `ast` module and follows names, imports and your own functions to the values they stand for; it never imports or executes the code. Values that only running the code could produce stay as source text. See [How view works](https://lowweilin.github.io/pydantic-ai-viz/concepts/how-view-works/).

`serve` turns on Pydantic AI's own OpenTelemetry instrumentation and points it at a private tracer provider, so nothing is sent anywhere and no global OpenTelemetry state is set. A span processor in your process turns each span into an event in an append-only log. A small local server (standard library only, bound to `127.0.0.1`) streams that log to a one-file viewer, and the same log is what a recording or an export contains.

Read more in the [documentation](https://lowweilin.github.io/pydantic-ai-viz/):
[quickstart](https://lowweilin.github.io/pydantic-ai-viz/quickstart/) ·
[guides](https://lowweilin.github.io/pydantic-ai-viz/guides/visualize-an-agent/) ·
[Python API](https://lowweilin.github.io/pydantic-ai-viz/reference/python-api/) ·
[CLI](https://lowweilin.github.io/pydantic-ai-viz/reference/cli/)

## Limits and non-goals

- **`view` shows only what the source spells out.** A model or prompt that is computed when the code runs is shown as the expression that computes it, and an agent built by a library function is not found. `view --import` reads the live objects instead, which runs the code; use it only on code you trust.
- **Local development only.** It captures runs in the process that calls `serve` or `record`, and keeps them in memory. For production tracing, use [Pydantic Logfire](https://pydantic.dev/logfire). The two work together; see the [Logfire guide](https://lowweilin.github.io/pydantic-ai-viz/guides/logfire/).
- **Not a chat playground.** Pydantic AI already has `agent.to_web()` for that.
- **Recordings and exports contain your prompts, tool arguments and tool results.** Read [Privacy](https://lowweilin.github.io/pydantic-ai-viz/guides/privacy/) before you share one.
- **Token streaming is opt-in** (`stream=True`). It switches model requests to streaming, which fails on a model that cannot stream.
- **MCP toolsets are shown as one opaque node.** Their tools appear once a run has used them.
- **No cost estimates, run diffing or search** in this version.

## Compatibility

| | Supported |
|---|---|
| Python | 3.11, 3.12, 3.13, 3.14 |
| Pydantic AI | `pydantic-ai-slim>=2.60,<3` |
| OpenTelemetry SDK | `opentelemetry-sdk>=1.30` |
| OS | Linux, macOS and Windows (all tested in CI) |

A few blueprint fields are read from private Pydantic AI attributes. If a Pydantic AI release changes them, those fields degrade to a warning in the viewer and the rest keeps working. The [compatibility page](https://lowweilin.github.io/pydantic-ai-viz/reference/compatibility/) lists them and says exactly which versions were tested.

## Contributing

Bug reports and pull requests are welcome. [CONTRIBUTING.md](https://github.com/LowWeiLin/pydantic-ai-viz/blob/main/CONTRIBUTING.md) covers the development setup and the checks to run. Report security issues privately as described in [SECURITY.md](https://github.com/LowWeiLin/pydantic-ai-viz/blob/main/SECURITY.md).

## Acknowledgements

The canvas is drawn with [React Flow](https://reactflow.dev) and laid out with [dagre](https://github.com/dagrejs/dagre). The viewer is also built on [React](https://react.dev), [Radix UI](https://www.radix-ui.com), [Zustand](https://github.com/pmndrs/zustand) and [Tailwind CSS](https://tailwindcss.com). The licence of every library bundled into the viewer is at the top of the viewer's HTML file, and of every export made from it.

## License

[MIT](https://github.com/LowWeiLin/pydantic-ai-viz/blob/main/LICENSE).

pydantic-ai-viz is an unofficial community project. It is not affiliated with, sponsored by or endorsed by Pydantic. "Pydantic", "Pydantic AI" and "Logfire" are names of their respective owners.
