recusal-langgraph
The Recusal gate for
LangGraph: every tool call a ToolNode is
about to execute is judged by your policy first, 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 LangGraph dependency and
its own version, so a LangGraph release never forces a release of the kernel.
Install it from PyPI:
pip install recusal-langgraph
Requires Python 3.10+, recusal>=0.14.0, langgraph>=1.2.12 and langchain-core>=1.6.5.
It is tested on every pull request against exactly langgraph==1.2.12 with
langchain-core==1.6.5, and weekly against the newest releases.
Use
from langchain_core.tools import tool
from langgraph.prebuilt import ToolNode
from recusal import Finding
from recusal_langgraph import recusal_gate
@tool
def run_sql(sql: str) -> str:
"""Run a SQL statement."""
...
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 []
node = ToolNode([run_sql], wrap_tool_call=recusal_gate(policy))
Your @tool list goes into ToolNode unchanged. Every call in a model message crosses
the gate separately, immediately before execution. A refused call is answered with an
error ToolMessage carrying Recusal's reason, and its tool does not run. A policy that
raises refuses the call (fail closed). For an async graph, attach
recusal_agate(policy) with awrap_tool_call and run with ainvoke.
The policy judges the invocation the tool executes, not the dict the model wrote: the input is validated once, defaults the model omitted are completed, and those same objects are passed to the function. Arguments the host injects (state, store, runtime) are left out of judgment, and the model can never supply them.
Put every decision on the record
from recusal.audit import AuditLog
from recusal_langgraph import recusal_audited_gate
log = AuditLog(path="decisions.jsonl")
node = ToolNode([run_sql], wrap_tool_call=recusal_audited_gate(policy, log))
recusal_audited_agate is the async form. Each call the gate sees, allowed or refused,
is one hash-chained entry labeled langgraph.toolnode with LangGraph'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 gates call the plain gate's own judging function, so there is one decision path.
What the gate refuses, and what it does not see
- Refused before the policy runs: a tool whose class or instance overrides the standard execution lifecycle (it could run without reaching the gate), input that does not validate against the tool's schema, and a tool whose callable declares a parameter the schema omits, since that is a value no proposal can carry and the policy would never see.
- Not on the audit log: a call another
wrap_tool_callhook answered without reaching the gate.
This package reads two private LangChain and LangGraph helpers to find the arguments the host injects. That is why its framework requirements have an upper bound, and why the weekly lane against the newest releases exists.
Compatibility
This package is outside the kernel's frozen perimeter (STABILITY.md, Integrations). Its
public names are the ones in recusal_langgraph.__all__. When a LangGraph release
changes what the hook is handed, this package gets a release and the kernel does not.
A runnable offline demonstration, with a scripted graph and no API key, is
examples/langgraph_gate.py
and
examples/langgraph_audit.py.
Metadata
Release files for recusal-langgraph 0.1.1
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_langgraph-0.1.1.tar.gz | 16.8 kB | With provenance | Details for recusal_langgraph-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| recusal_langgraph-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for recusal_langgraph-0.1.1-py3-none-any.whl |
Total release size: 33.2 kB
Release files / recusal_langgraph-0.1.1.tar.gz
| Download URL | recusal_langgraph-0.1.1.tar.gz |
|---|---|
| Size | 16.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8d53b98696750061e749580d7d8766a6a26ac0b036eeda7995775f1336620f90
|
|
BLAKE2b-256 checksum How to use checksums |
85b7ee07989fac120e2d87b30c5875618dd247fd8bc830447023a4d1355a2994
|
| 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_langgraph-0.1.1-py3-none-any.whl
| Download URL | recusal_langgraph-0.1.1-py3-none-any.whl |
|---|---|
| Size | 16.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e140635a9c4f44716c5a153254ac9b2b9c7c0fa5a4fa59a08f5be00e23b76372
|
|
BLAKE2b-256 checksum How to use checksums |
85022c174a094b207addfd90352e5a6b7d54e94e49fa33635f7472cc0bdc8e80
|
| 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-langgraph 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.
Attestation for recusal_langgraph-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 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.