Metadata-Version: 2.5
Name: culprit-ai
Version: 0.1.2
Summary: Finds which prompt commit broke your agent.
Project-URL: Homepage, https://github.com/abi6374/culprit
Project-URL: Documentation, https://abi6374.github.io/culprit/
Project-URL: Repository, https://github.com/abi6374/culprit
Project-URL: Issues, https://github.com/abi6374/culprit/issues
Author: Abinivas
License-Expression: MIT
License-File: LICENSE
Keywords: evals,git,llm,prompts,semantic-diff
Classifier: Development Status :: 3 - Alpha
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: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40
Requires-Dist: openai>=1.50
Requires-Dist: pydantic>=2.8
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatch-vcs>=0.5; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pillow>=11.0; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# culprit

> `git bisect` thinking for prompts: compare what changed in behavior, not only in text.

[![CI](https://github.com/abi6374/culprit/actions/workflows/ci.yml/badge.svg)](https://github.com/abi6374/culprit/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/abi6374/culprit/branch/main/graph/badge.svg)](https://codecov.io/gh/abi6374/culprit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

<!-- Replace this terminal recording with a real culprit diff capture before v0.1.0 release. -->
[![culprit diff terminal demo](docs/assets/demo-placeholder.svg)](docs/semantic-diff.md)

```bash
pip install culprit-ai
```

## Quickstart

```bash
cp examples/quickstart/culprit.yaml .
cp -r examples/quickstart/evals .
export OPENAI_API_KEY="..."
culprit diff HEAD~1 HEAD --eval-set evals/summarizer.yaml
```

## Features

- [Semantic diff](docs/semantic-diff.md): an LLM summary backed by per-case eval evidence.
- [Behavioral bisect](docs/bisect.md): binary-search prompt history to locate the first regression.

  [![culprit bisect terminal demo](docs/assets/bisect-demo.gif)](docs/bisect.md)
- [Git-native architecture](docs/architecture.md): prompt history stays in ordinary Git.
- Provider adapters for OpenAI, Anthropic, and arbitrary OpenAI-compatible endpoints.
- Content-addressed [evaluation cache](docs/architecture.md) to avoid repeat API spend.
- `culprit check` warnings for common secret and PII patterns.
- [Semantic merge](docs/merge.md) remains a documented roadmap phase, not an implemented command.

## Why not just use X?

| Tool | Best fit | How culprit differs |
|---|---|---|
| Promptfoo | Broad prompt/model evaluation and red teaming | culprit centers comparisons on Git revisions and commit history. |
| Confident AI / DeepEval | Evaluation frameworks and hosted workflows | culprit is a local Git wrapper with zero required backend. |
| promptvc | Prompt versioning workflows | culprit leaves version storage entirely to Git and adds eval-backed diffs. |

These tools can complement culprit; the comparison is about workflow focus, not superiority.

## Contributing

Phase 1 improvements are open for contribution. See [CONTRIBUTING.md](CONTRIBUTING.md), including adapter guidance and suggested first issues.

Released under the [MIT License](LICENSE).
