Skip to main content

vsl-langchain

A LangChain adapter for vsl-core: implements vsl_core.conformance.protocol.VSLAdapter and gates tool calls inside a create_agent() agent via AgentMiddleware.wrap_tool_call.

Is:

  • A VSLAdapter implementation (LangChainAdapter) that passes vsl_core.conformance.suite.run_conformance_suite with an empty result.
  • VSLToolMiddleware: a real langchain.agents.middleware.types.AgentMiddleware subclass that gates named tools, keyed by tool name, inside create_agent's middleware stack.

Is not:

  • A replacement for vsl-core itself — the PreNode/Invariant/Fallback/TerminalState constructs, the ledger, and the governance vocabulary all live in vsl-core. This package only compiles and wires those constructs into LangChain.
  • Compatible with the deprecated AgentExecutor/initialize_agent/create_react_agent APIs. Those predate the middleware system this adapter depends on — this package targets create_agent (LangChain >= 1.0) only.

Why wrap_tool_call, and why it's a real gate — not an assumption

AgentMiddleware.wrap_tool_call/awrap_tool_call is LangChain's own sanctioned interception point for tool execution. This was verified directly against the installed package's own docstring (langchain==1.3.17, not just documentation prose), which states outright:

"Middleware can call the handler multiple times for retry logic, skip calling it to short-circuit, or modify the request/response."

That is a genuine F1 pre-commitment guarantee: the middleware runs strictly before the tool executes, and structurally controls whether the real call (handler) ever happens at all. If a gate denies, handler is never called — the tool genuinely never runs, proven directly in this repo's own tests (test_integration.py asserts the handler's call log stays empty on denial, not just that a particular return value came back).

This supersedes an earlier, weaker finding (see project memory) that LangChain's callback system (on_tool_start, etc.) had unconfirmed blocking behavior — wrap_tool_call is a different, confirmed mechanism, not the same uncertain one.

Install

pip install vsl-langchain

This installs vsl-core (super-semantics-vsl, imported as vsl_core) and LangChain with it.

Quick taste

from langchain.agents import create_agent
from vsl_core.constructs import PreNode
from vsl_core.metrics import AssuranceBasis, F2Modification, GammaEstimate
from vsl_langchain import LangChainAdapter, VSLToolMiddleware

adapter = LangChainAdapter()

async def monitor(candidate_input):
    amount = candidate_input["args"].get("amount", 0.0)
    return GammaEstimate(gamma_hat=2.0 if amount <= 1000.0 else 0.0)

pre_node = PreNode(
    name="refund-cap",
    description="Requires refund amount under the hard cap.",
    monitor=monitor,
    assurance_basis=AssuranceBasis(f1_pre_commitment=True, f2_modification=F2Modification.NONE),
)
gate = adapter.compile_pre_node(pre_node)

middleware = VSLToolMiddleware(gates_by_tool_name={"send_refund": gate})

agent = create_agent(
    model="anthropic:claude-sonnet-5",
    tools=[send_refund, lookup_order],  # lookup_order stays ungated -- no entry in gates_by_tool_name
    middleware=[middleware],
)

VSLToolMiddleware doesn't consume Fallback

A PreNode's Fallback (on_failure, delta_factor, max_retries, on_max_retries) is policy data only here — LangChainAdapter.compile_pre_node/compile_invariant never read pre_node.fallback. On denial, VSLToolMiddleware.awrap_tool_call returns an error ToolMessage once, immediately; there is no retry loop. This is the same inertness vsl-langgraph's LangGraphAdapter has — vsl-core's own PlainPythonReferenceAdapter doesn't consume Fallback either, so no adapter currently executes these fields as behavior.

VSLToolMiddleware doesn't write to the ledger either

Nothing in awrap_tool_call calls VerbaLedger.write* — a gate denial becomes an error ToolMessage, and that's it. If you want an audit trail of gate decisions, your own code (e.g. wrapping VSLToolMiddleware construction, or a separate middleware) has to call ledger.write_monitor/ledger.write(LedgerEntryType.PRE_NODE, ...)/write_verification explicitly, causally linked via caused_by — the same three entry types vsl-core's own building guide says to write around every gated call. Skip PRE_NODE and VerbaLedger.audit()'s drift_flagged_monitor_has_pre_node check fails on any denial — not a bug in audit(), just an incomplete write. An agent with no ledger calls anywhere produces real, working gating and zero audit trail — this package won't warn you, because from its point of view every gate did exactly what it was compiled to do.

Where those writes are kept is up to you: VerbaLedger accepts any LedgerStore, and vsl-core includes InMemoryLedgerStore, JsonlLedgerStore (a local append-only file) and an optional immudb store.

The F1/F2 assurance distinction — same caveat as vsl-core and vsl-langgraph

Every PreNode/Invariant here still requires an AssuranceBasis, and it's still self-declared, not independently verified — nothing in this package checks that a stated F2Modification.FULL actually matches what a monitor/rule does. See vsl-core's README ("The F1/F2 assurance distinction") for the full explanation. vsl-langchain does not yet carry the hosted-API-detection heuristic vsl-langgraph's LangGraphAdapter has — that's a known gap, not implemented in this initial version.

Status

Alpha. Conformance-suite green. Integration-tested against the real ToolCallRequest/ToolMessage types from the actually-installed langchain/langgraph packages (not mocks) — covering: PreNode allow/deny, Invariant allow/deny, and an ungated tool passing straight through. Not yet tested against a full live create_agent() loop with a real or fake chat model — only the middleware's awrap_tool_call hook in isolation.

Layout

src/vsl_langchain/
└── adapter.py   LangChainAdapter (VSLAdapter conformance contract), VSLToolMiddleware (create_agent wiring)
tests/
├── test_conformance.py   run_conformance_suite(LangChainAdapter()) == []
└── test_integration.py   real ToolCallRequest/ToolMessage, PreNode + Invariant, allow/deny/ungated paths

Metadata

Release files for vsl-langchain 0.1.2

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

Source distribution (sdist)

Source distribution for vsl-langchain 0.1.2
File Size Uploaded Provenance Actions
vsl_langchain-0.1.2.tar.gz 8.7 kB With provenance Details for vsl_langchain-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vsl-langchain 0.1.2
File Interpreter ABI Platform Actions
vsl_langchain-0.1.2-py3-none-any.whl Python 3 none any Details for vsl_langchain-0.1.2-py3-none-any.whl

Total release size: 16.5 kB

Release files / vsl_langchain-0.1.2.tar.gz

Download URL vsl_langchain-0.1.2.tar.gz
Size 8.7 kB
Tags Source
SHA-256 checksum
How to use checksums
371f8441235b66e22056d28ddd3e6b0ae6a0ca96f7654d03d3b3ca09e387aab1
BLAKE2b-256 checksum
How to use checksums
1591976ac8fb8e036480a69a2227b3ce59ab00eda3158fa86c1f8be2a7a2993f
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 13, 2026.

Transparency log

Release files / vsl_langchain-0.1.2-py3-none-any.whl

Download URL vsl_langchain-0.1.2-py3-none-any.whl
Size 7.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
65496481d8a0222e6cea08ff1369d35e0369eefeab12294b47d9fc367489627b
BLAKE2b-256 checksum
How to use checksums
c998c06d933970874b2072936e78eb1a6c5e41be71b4cc562fab40259a1a703d
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 13, 2026.

Transparency log

Security for vsl-langchain 0.1.2

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 vsl_langchain-0.1.2.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 13, 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.2 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