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
strorintand 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.