Skip to main content

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_call hook 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)

Source distribution for recusal-langgraph 0.1.1
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)

Table of built distributions (wheels) for recusal-langgraph 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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