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.

Install it from PyPI:

pip install recusal-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.1

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.1
File Size Uploaded Provenance Actions
recusal_pydantic_ai-0.1.1.tar.gz 12.6 kB With provenance Details for recusal_pydantic_ai-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 25.5 kB

Release files / recusal_pydantic_ai-0.1.1.tar.gz

Download URL recusal_pydantic_ai-0.1.1.tar.gz
Size 12.6 kB
Tags Source
SHA-256 checksum
How to use checksums
2fc28ef8fef30c3464151aa973d6fda351ac20e5081f86f2f221e5351ec4181f
BLAKE2b-256 checksum
How to use checksums
393491ecc956bc8da244388fda8bb46173a798b0d63f78a028ab4fa2b7e748b3
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.1-py3-none-any.whl

Download URL recusal_pydantic_ai-0.1.1-py3-none-any.whl
Size 12.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1dd57b2cb9f3a27038a23282e82eac21e4a3d1a2e8def8f57cd796ca3333d971
BLAKE2b-256 checksum
How to use checksums
bf125916f23c2a7fa4edf848bae28afec5c11dafc788ce4a6a15c06d2830e4fe
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.1

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.1.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.1 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