agentprdiff 0.1.0__tar.gz

agentprdiff-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# agentguard runtime
+# Users SHOULD commit .agentguard/baselines; they should NOT commit run artifacts.
+.agentguard/runs/
+.agentguard/cache/

agentprdiff-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to `agentprdiff` are documented in this file. Originally
+prototyped under the name `tracediff`; renamed before first public release.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-04-22
+
+Initial public release.
+
+### Added
+
+- Core `Suite` / `Case` / `Trace` model for defining agent regression tests.
+- Deterministic graders: `contains`, `contains_any`, `regex_match`, `tool_called`,
+  `tool_sequence`, `output_length_lt`, `latency_lt_ms`, `cost_lt_usd`,
+  `no_tool_called`.
+- Semantic grader (`semantic`) with a pluggable `judge` callable and built-in
+  fake judge for CI environments without API keys.
+- Baseline store (JSON files under `.agentprdiff/baselines/`) designed to be
+  committed to version control.
+- Trace diff engine producing a structured `TraceDelta` (assertion pass/fail
+  changes, cost delta, latency delta, tool-call sequence changes, output
+  change).
+- CLI: `agentprdiff init`, `agentprdiff record`, `agentprdiff check`, `agentprdiff diff`.
+- Rich-formatted terminal reporter and machine-readable JSON reporter for CI.
+- Quickstart example with a mock agent that runs without any API keys.
+- Pytest test suite covering graders, runner, differ, store, and CLI smoke.
+- GitHub Actions CI workflow.
+
+### Known limitations
+
+- Only a manual instrumentation API for provider SDKs is shipped in 0.1.0.
+  Drop-in wrappers for OpenAI / Anthropic / Vercel AI SDK are planned for 0.2.
+- The semantic grader's built-in judge supports OpenAI and Anthropic via user-
+  supplied API keys; hosted judge endpoints are not yet offered.

agentprdiff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinoth Nageshwaran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentprdiff-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: agentprdiff
+Version: 0.1.0
+Summary: Guard your LLM agents in CI. Snapshot tests that catch behavioral regressions when models, prompts, or vendors change.
+Project-URL: Homepage, https://github.com/vnageshwaran-de/agentprdiff
+Project-URL: Documentation, https://github.com/vnageshwaran-de/agentprdiff#readme
+Project-URL: Issues, https://github.com/vnageshwaran-de/agentprdiff/issues
+Project-URL: Repository, https://github.com/vnageshwaran-de/agentprdiff
+Author-email: Vinoth Nageshwaran <vnageshwaran@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,ci,evaluation,llm,observability,regression-testing,snapshot-testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# agentprdiff
+
+**Guard your LLM agents in CI.** Snapshot tests that catch behavioral regressions when models, prompts, or vendors change.
+
+> You upgraded Claude. You tweaked a system prompt. You swapped `gpt-4o` for `gpt-4o-mini` in the cheap path. Which of your agent's behaviors just changed? `agentprdiff` tells you — before the PR merges.
+
+```bash
+pip install agentprdiff
+```
+
+[![CI](https://github.com/vnageshwaran-de/agentprdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/vnageshwaran-de/agentprdiff/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agentprdiff.svg)](https://pypi.org/project/agentprdiff/)
+[![Python](https://img.shields.io/pypi/pyversions/agentprdiff.svg)](https://pypi.org/project/agentprdiff/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+## Why
+
+Unit tests assume determinism. Agents aren't deterministic, but they do have *behaviors you rely on* — a specific tool gets called, a refund amount is quoted, a latency budget is respected, a safety guardrail fires. When a model or prompt changes, those behaviors drift. Today most teams find out in production.
+
+`agentprdiff` turns those behaviors into versioned, diffable baselines you check into git, and a CI command that fails the build when they regress.
+
+It is **not** a framework. Your agent stays exactly the way it is. `agentprdiff` records what it did, lets you assert what should be true about what it did, and compares runs across time.
+
+## 10-line hello world
+
+```python
+# suite.py
+from agentprdiff import case, suite
+from agentprdiff.graders import contains, tool_called, latency_lt_ms, semantic
+from my_agent import run  # your agent — unchanged
+
+support = suite(
+    name="customer_support",
+    agent=run,
+    cases=[
+        case(
+            name="refund_happy_path",
+            input="I want a refund for order #1234",
+            expect=[
+                contains("refund"),
+                tool_called("lookup_order"),
+                semantic("agent acknowledges the refund and explains the timeline"),
+                latency_lt_ms(10_000),
+            ],
+        ),
+    ],
+)
+```
+
+```bash
+agentprdiff init
+agentprdiff record suite.py     # save this run as the baseline
+agentprdiff check  suite.py     # in CI: diff vs baseline, exit 1 on regression
+```
+
+That's the whole product. Four CLI commands. One Python file. Zero framework lock-in.
+
+## What's in the box
+
+- **Case + Suite model** — tiny, opinionated, no magic.
+- **10 batteries-included graders** — `contains`, `contains_any`, `regex_match`, `tool_called`, `tool_sequence`, `no_tool_called`, `output_length_lt`, `latency_lt_ms`, `cost_lt_usd`, `semantic` (LLM-as-judge with pluggable backend).
+- **Baseline store** — JSON files under `.agentprdiff/baselines/`, meant to be **committed**. Reviewers see trace changes in pull requests.
+- **Diff engine** — per-case `TraceDelta` with assertion pass/fail changes, cost delta, latency delta, tool-sequence changes, and a unified output diff.
+- **CI-ready CLI** — exit 1 on regression, `--json-out` for artifact archiving, Rich-formatted terminal output.
+- **Zero SDK lock-in** — works with OpenAI, Anthropic, Gemini, Bedrock, LangChain, LangGraph, LlamaIndex, Vercel AI SDK, custom wrappers — if you can wrap your agent in a function, `agentprdiff` can test it.
+
+## How it compares
+
+| | Unit tests | LLM-as-judge eval | `agentprdiff` |
+|---|---|---|---|
+| Deterministic pass/fail | yes | no | **yes** (when assertions are deterministic) |
+| Catches behavioral drift | no | yes | **yes** |
+| Runs in CI on every PR | yes | too expensive | **yes** |
+| Human-readable diff of what changed | n/a | rare | **yes** |
+| Works without API keys | yes | no | **yes** (deterministic graders + fake judge) |
+
+The value is in the combination: deterministic assertions for the 80% of behaviors you can encode as rules ("this tool was called", "this word appeared", "cost stayed under $0.02"), plus a semantic grader for the 20% that need a judge — with a fake-judge fallback so your CI stays green and free when API keys aren't available.
+
+## The workflow
+
+1. Write a `Suite` alongside your agent code.
+2. Run `agentprdiff record` once on a known-good version. Commit the resulting `.agentprdiff/baselines/` directory.
+3. In CI, on every PR, run `agentprdiff check`. If any assertion regresses, or cost/latency budgets are breached, the job fails.
+4. When behavior intentionally changes, the PR author re-runs `agentprdiff record`, commits the new baseline, and explains the change in the PR description. Reviewers see the before/after in the diff.
+
+This is the same loop as Jest snapshot tests or VCR cassettes — applied to LLM agents.
+
+## Instrumenting your agent
+
+`agentprdiff` doesn't monkey-patch anything. Your agent returns `(output, Trace)`:
+
+```python
+from agentprdiff import Trace, LLMCall, ToolCall
+
+def my_agent(query: str) -> tuple[str, Trace]:
+    trace = Trace(suite_name="", case_name="", input=query)
+
+    # ... call your model, record what happened ...
+    trace.record_llm_call(LLMCall(
+        provider="anthropic",
+        model="claude-sonnet-4-6",
+        prompt_tokens=120, completion_tokens=80,
+        cost_usd=0.0012, latency_ms=340,
+    ))
+
+    # ... call a tool, record what happened ...
+    trace.record_tool_call(ToolCall(name="lookup_order", arguments={"id": "1234"}))
+
+    return final_output, trace
+```
+
+Agents that return just an output still work — `agentprdiff` wraps them and captures wall-clock latency. You can backfill richer instrumentation incrementally, assertion by assertion.
+
+## CI integration
+
+```yaml
+# .github/workflows/agents.yml
+name: agent-regression
+on: [pull_request]
+jobs:
+  agentprdiff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - run: pip install -e ".[dev]"
+      - run: agentprdiff check suites/*.py --json-out artifacts/agentprdiff.json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with: { name: agentprdiff, path: artifacts/ }
+```
+
+See [`docs/ci-integration.md`](./docs/ci-integration.md) for GitLab, CircleCI, and Buildkite.
+
+## Quickstart
+
+A runnable end-to-end demo, no API keys needed:
+
+```bash
+git clone https://github.com/vnageshwaran-de/agentprdiff
+cd agentprdiff
+pip install -e ".[dev]"
+
+cd examples/quickstart
+agentprdiff init
+agentprdiff record suite.py
+agentprdiff check  suite.py   # exit 0
+
+# now break the agent and watch agentprdiff catch it
+sed -i "s/refund/noundr/g" agent.py
+agentprdiff check suite.py    # exit 1; see the diff
+```
+
+## Status
+
+`agentprdiff` is **alpha** (0.1.0). The core model and CLI are stable; provider-specific SDK wrappers and a LangChain/LangGraph integration are on the 0.2 roadmap. See [`CHANGELOG.md`](./CHANGELOG.md).
+
+Feedback, bug reports, and PRs extremely welcome. Open an issue or @ me.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

agentprdiff-0.1.0/README.md

@@ -0,0 +1,163 @@
+# agentprdiff
+
+**Guard your LLM agents in CI.** Snapshot tests that catch behavioral regressions when models, prompts, or vendors change.
+
+> You upgraded Claude. You tweaked a system prompt. You swapped `gpt-4o` for `gpt-4o-mini` in the cheap path. Which of your agent's behaviors just changed? `agentprdiff` tells you — before the PR merges.
+
+```bash
+pip install agentprdiff
+```
+
+[![CI](https://github.com/vnageshwaran-de/agentprdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/vnageshwaran-de/agentprdiff/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agentprdiff.svg)](https://pypi.org/project/agentprdiff/)
+[![Python](https://img.shields.io/pypi/pyversions/agentprdiff.svg)](https://pypi.org/project/agentprdiff/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+## Why
+
+Unit tests assume determinism. Agents aren't deterministic, but they do have *behaviors you rely on* — a specific tool gets called, a refund amount is quoted, a latency budget is respected, a safety guardrail fires. When a model or prompt changes, those behaviors drift. Today most teams find out in production.
+
+`agentprdiff` turns those behaviors into versioned, diffable baselines you check into git, and a CI command that fails the build when they regress.
+
+It is **not** a framework. Your agent stays exactly the way it is. `agentprdiff` records what it did, lets you assert what should be true about what it did, and compares runs across time.
+
+## 10-line hello world
+
+```python
+# suite.py
+from agentprdiff import case, suite
+from agentprdiff.graders import contains, tool_called, latency_lt_ms, semantic
+from my_agent import run  # your agent — unchanged
+
+support = suite(
+    name="customer_support",
+    agent=run,
+    cases=[
+        case(
+            name="refund_happy_path",
+            input="I want a refund for order #1234",
+            expect=[
+                contains("refund"),
+                tool_called("lookup_order"),
+                semantic("agent acknowledges the refund and explains the timeline"),
+                latency_lt_ms(10_000),
+            ],
+        ),
+    ],
+)
+```
+
+```bash
+agentprdiff init
+agentprdiff record suite.py     # save this run as the baseline
+agentprdiff check  suite.py     # in CI: diff vs baseline, exit 1 on regression
+```
+
+That's the whole product. Four CLI commands. One Python file. Zero framework lock-in.
+
+## What's in the box
+
+- **Case + Suite model** — tiny, opinionated, no magic.
+- **10 batteries-included graders** — `contains`, `contains_any`, `regex_match`, `tool_called`, `tool_sequence`, `no_tool_called`, `output_length_lt`, `latency_lt_ms`, `cost_lt_usd`, `semantic` (LLM-as-judge with pluggable backend).
+- **Baseline store** — JSON files under `.agentprdiff/baselines/`, meant to be **committed**. Reviewers see trace changes in pull requests.
+- **Diff engine** — per-case `TraceDelta` with assertion pass/fail changes, cost delta, latency delta, tool-sequence changes, and a unified output diff.
+- **CI-ready CLI** — exit 1 on regression, `--json-out` for artifact archiving, Rich-formatted terminal output.
+- **Zero SDK lock-in** — works with OpenAI, Anthropic, Gemini, Bedrock, LangChain, LangGraph, LlamaIndex, Vercel AI SDK, custom wrappers — if you can wrap your agent in a function, `agentprdiff` can test it.
+
+## How it compares
+
+| | Unit tests | LLM-as-judge eval | `agentprdiff` |
+|---|---|---|---|
+| Deterministic pass/fail | yes | no | **yes** (when assertions are deterministic) |
+| Catches behavioral drift | no | yes | **yes** |
+| Runs in CI on every PR | yes | too expensive | **yes** |
+| Human-readable diff of what changed | n/a | rare | **yes** |
+| Works without API keys | yes | no | **yes** (deterministic graders + fake judge) |
+
+The value is in the combination: deterministic assertions for the 80% of behaviors you can encode as rules ("this tool was called", "this word appeared", "cost stayed under $0.02"), plus a semantic grader for the 20% that need a judge — with a fake-judge fallback so your CI stays green and free when API keys aren't available.
+
+## The workflow
+
+1. Write a `Suite` alongside your agent code.
+2. Run `agentprdiff record` once on a known-good version. Commit the resulting `.agentprdiff/baselines/` directory.
+3. In CI, on every PR, run `agentprdiff check`. If any assertion regresses, or cost/latency budgets are breached, the job fails.
+4. When behavior intentionally changes, the PR author re-runs `agentprdiff record`, commits the new baseline, and explains the change in the PR description. Reviewers see the before/after in the diff.
+
+This is the same loop as Jest snapshot tests or VCR cassettes — applied to LLM agents.
+
+## Instrumenting your agent
+
+`agentprdiff` doesn't monkey-patch anything. Your agent returns `(output, Trace)`:
+
+```python
+from agentprdiff import Trace, LLMCall, ToolCall
+
+def my_agent(query: str) -> tuple[str, Trace]:
+    trace = Trace(suite_name="", case_name="", input=query)
+
+    # ... call your model, record what happened ...
+    trace.record_llm_call(LLMCall(
+        provider="anthropic",
+        model="claude-sonnet-4-6",
+        prompt_tokens=120, completion_tokens=80,
+        cost_usd=0.0012, latency_ms=340,
+    ))
+
+    # ... call a tool, record what happened ...
+    trace.record_tool_call(ToolCall(name="lookup_order", arguments={"id": "1234"}))
+
+    return final_output, trace
+```
+
+Agents that return just an output still work — `agentprdiff` wraps them and captures wall-clock latency. You can backfill richer instrumentation incrementally, assertion by assertion.
+
+## CI integration
+
+```yaml
+# .github/workflows/agents.yml
+name: agent-regression
+on: [pull_request]
+jobs:
+  agentprdiff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - run: pip install -e ".[dev]"
+      - run: agentprdiff check suites/*.py --json-out artifacts/agentprdiff.json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with: { name: agentprdiff, path: artifacts/ }
+```
+
+See [`docs/ci-integration.md`](./docs/ci-integration.md) for GitLab, CircleCI, and Buildkite.
+
+## Quickstart
+
+A runnable end-to-end demo, no API keys needed:
+
+```bash
+git clone https://github.com/vnageshwaran-de/agentprdiff
+cd agentprdiff
+pip install -e ".[dev]"
+
+cd examples/quickstart
+agentprdiff init
+agentprdiff record suite.py
+agentprdiff check  suite.py   # exit 0
+
+# now break the agent and watch agentprdiff catch it
+sed -i "s/refund/noundr/g" agent.py
+agentprdiff check suite.py    # exit 1; see the diff
+```
+
+## Status
+
+`agentprdiff` is **alpha** (0.1.0). The core model and CLI are stable; provider-specific SDK wrappers and a LangChain/LangGraph integration are on the 0.2 roadmap. See [`CHANGELOG.md`](./CHANGELOG.md).
+
+Feedback, bug reports, and PRs extremely welcome. Open an issue or @ me.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

agentprdiff-0.1.0/examples/quickstart/README.md

@@ -0,0 +1,22 @@
+# agentprdiff quickstart
+
+A minimal, runnable example. No API keys required.
+
+```bash
+# from the repo root:
+pip install -e .
+cd examples/quickstart
+
+agentprdiff init
+agentprdiff record suite.py   # records baselines for every case
+agentprdiff check  suite.py   # re-runs every case, diffs against the baseline
+```
+
+The first `check` after `record` should exit 0 with all cases passing. Now
+edit `agent.py` — change the refund wording or remove the `lookup_order`
+tool call for a particular input — and re-run `agentprdiff check`. You'll see
+the specific grader that now fails, a cost and latency delta, and a unified
+diff of the output.
+
+That's the whole loop. Swap `support_agent` for whatever production agent
+you want to guard.

agentprdiff-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentprdiff"
+version = "0.1.0"
+description = "Guard your LLM agents in CI. Snapshot tests that catch behavioral regressions when models, prompts, or vendors change."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Vinoth Nageshwaran", email = "vnageshwaran@gmail.com" }]
+keywords = [
+    "llm",
+    "agent",
+    "evaluation",
+    "regression-testing",
+    "snapshot-testing",
+    "ci",
+    "observability",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "click>=8.1",
+    "rich>=13.0",
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.30"]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "ruff>=0.5",
+    "mypy>=1.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/vnageshwaran-de/agentprdiff"
+Documentation = "https://github.com/vnageshwaran-de/agentprdiff#readme"
+Issues = "https://github.com/vnageshwaran-de/agentprdiff/issues"
+Repository = "https://github.com/vnageshwaran-de/agentprdiff"
+
+[project.scripts]
+agentprdiff = "agentprdiff.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentprdiff"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/agentprdiff", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = false
+ignore_missing_imports = true

agentprdiff-0.1.0/src/agentprdiff/__init__.py

@@ -0,0 +1,81 @@
+"""agentprdiff — snapshot testing for LLM agents.
+
+The one-happy-path public API:
+
+    from agentprdiff import suite, case
+    from agentprdiff.graders import contains, tool_called, latency_lt_ms, semantic
+
+    def my_agent(query: str) -> str:
+        ...
+
+    billing_suite = suite(
+        name="billing",
+        agent=my_agent,
+        cases=[
+            case(
+                name="refund_happy_path",
+                input="I want a refund for order #1234",
+                expect=[
+                    contains("refund"),
+                    tool_called("lookup_order"),
+                    semantic("agent acknowledges the refund and provides next steps"),
+                    latency_lt_ms(10_000),
+                ],
+            ),
+        ],
+    )
+
+Run from the shell::
+
+    agentprdiff init
+    agentprdiff record path/to/my_suite.py     # save baselines
+    agentprdiff check  path/to/my_suite.py     # diff against baselines; exit 1 on regression
+"""
+
+from __future__ import annotations
+
+from .core import (
+    AgentFn,
+    Case,
+    Grader,
+    GradeResult,
+    LLMCall,
+    Suite,
+    ToolCall,
+    Trace,
+    case,
+    run_agent,
+    suite,
+)
+from .differ import AssertionChange, TraceDelta, diff_traces
+from .runner import CaseReport, Runner, RunReport
+from .store import BaselineStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # core
+    "Suite",
+    "Case",
+    "Trace",
+    "LLMCall",
+    "ToolCall",
+    "Grader",
+    "GradeResult",
+    "AgentFn",
+    "suite",
+    "case",
+    "run_agent",
+    # diffing
+    "TraceDelta",
+    "AssertionChange",
+    "diff_traces",
+    # runner
+    "Runner",
+    "RunReport",
+    "CaseReport",
+    # storage
+    "BaselineStore",
+    # version
+    "__version__",
+]