Skip to main content

recusal-pydantic-ai

The Recusal gate for Pydantic AI: every tool call an agent proposes is judged by your policy before the tool runs, and a refused call never runs.

This is a separate distribution from recusal. The kernel has zero runtime dependencies and a frozen compatibility perimeter; this package carries the Pydantic AI dependency and its own version, so a Pydantic AI release never forces a release of the kernel.

Status: not yet published to PyPI. Until it is, install it from the repository:

pip install "recusal-pydantic-ai @ git+https://github.com/philpaz/recusal#subdirectory=adapters/pydantic-ai"

Requires Python 3.11+ (Pydantic AI's minimum), recusal>=0.14.0 and pydantic-ai-slim>=2.64.0. It is tested on every pull request against exactly pydantic-ai-slim==2.64.0, and weekly against the newest release.

Use

from pydantic_ai import Agent
from recusal import Finding
from recusal_pydantic_ai import RecusalGate


def policy(tool_name, tool_input):
    sql = tool_input.get("sql", "")
    if tool_name == "run_sql" and sql.lstrip().upper().startswith("DELETE"):
        return [Finding.fail("no_deletes", severity="CRITICAL", message="DELETE is not allowed")]
    return []


agent = Agent(model, tools=[run_sql], capabilities=[RecusalGate(policy)])

A refused call is answered to the model as a failed tool result carrying Recusal's reason. The tool does not run and no retry budget is spent. A policy that raises refuses the call (fail closed).

RecusalGate declares Pydantic AI's innermost position, so it judges the arguments as they reach the tool, after every ordinary capability. The same gate as a plain hook is Hooks(before_tool_execute=recusal_before_tool_execute(policy)); Hooks declares no ordering, so that form must be listed last.

Put every decision on the record

from recusal.audit import AuditLog
from recusal_pydantic_ai import RecusalAuditedGate

log = AuditLog(path="decisions.jsonl")
agent = Agent(model, tools=[run_sql], capabilities=[RecusalAuditedGate(policy, log=log)])

Each call the gate sees, allowed or refused, is one hash-chained entry labeled pydantic_ai.before_tool_execute with Pydantic AI's tool call id and a SHA-256 fingerprint of the arguments (never the arguments). If the log cannot be written the call is refused. Check the log with recusal audit verify decisions.jsonl.

The audited gate calls the plain gate's own refusal function, so there is one decision path.

What the gate does not see

  • A delegated agent. An agent called from inside a tool function runs under its own capabilities. Give every agent its own gate; is_gated(agent) reads only the agent it is given.
  • A call that fails validation. Pydantic AI answers it with a retry prompt before any execute hook runs. The tool does not run either, and the call is not on the audit log.
  • Arguments that are not plain data. JSON scalars, lists and string-keyed dicts are judged. Models, dataclasses, Enum members and other objects are refused before the policy runs. Declare a str or int and resolve application types inside the tool.

Compatibility

This package is outside the kernel's frozen perimeter (STABILITY.md, Integrations). Its public names are the ones in recusal_pydantic_ai.__all__. When a Pydantic AI release changes what the hook is handed, this package gets a release and the kernel does not.

A runnable offline demonstration, with a scripted model and no API key, is examples/pydantic_ai_gate.py and examples/pydantic_ai_audit.py.

Metadata

Release files for recusal-pydantic-ai 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for recusal-pydantic-ai 0.1.0
File Size Uploaded Provenance Actions
recusal_pydantic_ai-0.1.0.tar.gz 12.7 kB With provenance Details for recusal_pydantic_ai-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for recusal-pydantic-ai 0.1.0
File Interpreter ABI Platform Actions
recusal_pydantic_ai-0.1.0-py3-none-any.whl Python 3 none any Details for recusal_pydantic_ai-0.1.0-py3-none-any.whl

Total release size: 25.7 kB

Release files / recusal_pydantic_ai-0.1.0.tar.gz

Download URL recusal_pydantic_ai-0.1.0.tar.gz
Size 12.7 kB
Tags Source
SHA-256 checksum
How to use checksums
c222ee25c5c6051f7a7fde89e10957b42fe43faf969b31a59ae5905185f7c5f8
BLAKE2b-256 checksum
How to use checksums
d00f5127bd307dcfffe8ee2bdea77a4b4cc37fbcac21608c86abd150b59778f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / recusal_pydantic_ai-0.1.0-py3-none-any.whl

Download URL recusal_pydantic_ai-0.1.0-py3-none-any.whl
Size 13.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6508fcc9e488fdb42c08661d01df1fbed98edbb86a8af480bb1e2fb90a6c457a
BLAKE2b-256 checksum
How to use checksums
c0123625aa9677d68e7860d10216b64c60d8f695d0df3ab1c4c5f0f15482a516
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for recusal-pydantic-ai 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for recusal_pydantic_ai-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page