Metadata-Version: 2.4
Name: playagent
Version: 0.1.0
Summary: Agent testing SDK. Instrument, assert, classify.
Author: emartai
License: MIT
Project-URL: Homepage, https://github.com/emartai/playagent
Project-URL: Documentation, https://github.com/emartai/playagent#readme
Project-URL: Repository, https://github.com/emartai/playagent
Project-URL: Issues, https://github.com/emartai/playagent/issues
Keywords: ai,agents,testing,llm,openai,anthropic
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.11
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.15.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25.0; extra == "anthropic"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.25.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg">
    <img alt="PlayAgent" src="assets/logo-dark.svg" width="80">
  </picture>
</p>

<p align="center">Test your AI agents. Catch failures before your users do.</p>

<p align="center">
  <a href="https://github.com/emartai/playagent/actions/workflows/ci.yml"><img alt="Build" src="https://img.shields.io/github/actions/workflow/status/emartai/playagent/ci.yml?style=flat-square&label=build&color=%2334d399"></a>
  <a href="https://pypi.org/project/playagent/"><img alt="PyPI" src="https://img.shields.io/pypi/v/playagent?style=flat-square&color=%2334d399"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-%2334d399?style=flat-square"></a>
</p>

---

**Quick Links:** [Quickstart](#quickstart) · [Assertions](docs/assertions.md) · [Failure Types](docs/failure-types.md) · [Contributing](docs/contributing.md)

---

```bash
pip install playagent[all]
```

```python
from playagent import record
from playagent.adapters.openai import OpenAI

client = OpenAI()

@record
def run_agent(user_input: str):
    return client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": user_input}],
    )
```

```text
  session   sess_a1b2c3d4
  agent     run_agent
  started   2026-04-05 09:14:32
  duration  3.24s
  status    passed

──────────────────────── turn 1 ─────────────────────────
  model     gpt-4o
  latency   812ms

  ▸ user
    What's the weather in Lagos today?

  ▸ assistant
    I'll look that up for you.
    ⬡ tool call  get_weather
      location  "Lagos, NG"
      units     "celsius"
```

| Command | What it does |
|---|---|
| `playagent trace list` | Lists recent trace sessions. |
| `playagent trace view <trace_id>` | Shows turn-by-turn trace details. |
| `playagent report` | Shows aggregate pass/fail and failure breakdowns. |
| `playagent report --format json` | Emits report stats as JSON for CI pipelines. |
| `playagent --version` | Prints installed PlayAgent version. |

## Why PlayAgent

- You stay local-first. PlayAgent writes to SQLite on your machine; nothing is sent to a hosted dashboard by default.
- You can test behavior, not only outputs. Assertions check tool-call order, parameters, and call counts directly.
- If you already use LangSmith, PlayAgent is a smaller option for local SDK-level checks; if you need hosted traces, collaboration, and observability dashboards, LangSmith is the better fit.

## License

MIT
