shadow-diff 3.0.5

Behavior contracts for AI agents — tested in your PR, enforced at runtime.

shadow-diff

Catch AI-agent regressions before they hit production.

Shadow is a PR-native diff tool for LLM agents — it records your agent's calls, replays them under a new config, and tells you what changed across nine behavioural dimensions.

Install

The PyPI distribution name is shadow-diff (the bare shadow name on PyPI is an unrelated project). The Python import path is shadow, and the CLI is shadow.

pip install shadow-diff

# With Anthropic support:
pip install 'shadow-diff[anthropic]'

# With OpenAI support:
pip install 'shadow-diff[openai]'

# With both + embeddings:
pip install 'shadow-diff[anthropic,openai,embeddings]'

Requires Python 3.11 or newer.

Quickstart

from shadow.sdk import Session

with Session(output_path="trace.agentlog"):
    # Your existing Anthropic / OpenAI code, unchanged.
    client.messages.create(model="claude-sonnet-4-6", messages=[...])

Shadow automatically patches the Anthropic and OpenAI SDKs to capture every request/response. Secrets are redacted by default.

Then in CI:

shadow replay new-config.yaml --baseline trace.agentlog
shadow diff trace.agentlog candidate.agentlog
shadow bisect old-config.yaml new-config.yaml --traces trace.agentlog

Full docs

The canonical README, examples, the .agentlog spec, and the project roadmap live at https://github.com/manav8498/Shadow.

License

Dual-licensed under MIT OR Apache-2.0. See LICENSE-MIT and LICENSE-APACHE in this distribution, or the project repository.