vsl-langchain 0.1.2__tar.gz

vsl_langchain-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Super Semantics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vsl_langchain-0.1.2/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: vsl-langchain
+Version: 0.1.2
+Summary: LangChain adapter for VSL (VERBA Specification Language) governance primitives -- implements vsl-core's VSLAdapter conformance contract via create_agent's AgentMiddleware.wrap_tool_call hook.
+License: MIT
+Project-URL: Homepage, https://github.com/supersemantics/VSL-LangChain
+Project-URL: Repository, https://github.com/supersemantics/VSL-LangChain
+Project-URL: Changelog, https://github.com/supersemantics/VSL-LangChain/blob/HEAD/CHANGELOG.md
+Project-URL: Issues, https://github.com/supersemantics/VSL-LangChain/issues
+Keywords: governance,ai-safety,guardrails,langchain,vsl,verba
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: super-semantics-vsl<0.4,>=0.3
+Requires-Dist: langchain>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# vsl-langchain
+
+A [LangChain](https://github.com/langchain-ai/langchain) adapter for
+[`vsl-core`](https://github.com/supersemantics/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
+
+```bash
+pip install vsl-langchain
+```
+
+This installs vsl-core (`super-semantics-vsl`, imported as `vsl_core`) and LangChain with it.
+
+## Quick taste
+
+```python
+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](https://github.com/supersemantics/VSL-Core/blob/main/docs/building-with-vsl-core.md#step-3-the-five-things-youll-actually-write) 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
+```

vsl_langchain-0.1.2/README.md

@@ -0,0 +1,91 @@
+# vsl-langchain
+
+A [LangChain](https://github.com/langchain-ai/langchain) adapter for
+[`vsl-core`](https://github.com/supersemantics/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
+
+```bash
+pip install vsl-langchain
+```
+
+This installs vsl-core (`super-semantics-vsl`, imported as `vsl_core`) and LangChain with it.
+
+## Quick taste
+
+```python
+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](https://github.com/supersemantics/VSL-Core/blob/main/docs/building-with-vsl-core.md#step-3-the-five-things-youll-actually-write) 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
+```

vsl_langchain-0.1.2/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vsl-langchain"
+version = "0.1.2"
+description = "LangChain adapter for VSL (VERBA Specification Language) governance primitives -- implements vsl-core's VSLAdapter conformance contract via create_agent's AgentMiddleware.wrap_tool_call hook."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    # vsl-core, published on PyPI as super-semantics-vsl (imported as vsl_core).
+    "super-semantics-vsl>=0.3,<0.4",
+    # AgentMiddleware.wrap_tool_call ("skip calling it to short-circuit")
+    # is the confirmed F1 pre-commitment interception point this adapter
+    # compiles gates onto -- requires the current, non-deprecated
+    # langchain.agents.create_agent API, not the deprecated AgentExecutor.
+    "langchain>=1.0",
+]
+keywords = ["governance", "ai-safety", "guardrails", "langchain", "vsl", "verba"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+]
+
+[project.urls]
+Homepage = "https://github.com/supersemantics/VSL-LangChain"
+Repository = "https://github.com/supersemantics/VSL-LangChain"
+Changelog = "https://github.com/supersemantics/VSL-LangChain/blob/HEAD/CHANGELOG.md"
+Issues = "https://github.com/supersemantics/VSL-LangChain/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.23"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

vsl_langchain-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vsl_langchain-0.1.2/src/vsl_langchain/__init__.py

@@ -0,0 +1,7 @@
+from .adapter import DEFAULT_DENIAL_KEY, LangChainAdapter, VSLToolMiddleware
+
+__all__ = [
+    "LangChainAdapter",
+    "VSLToolMiddleware",
+    "DEFAULT_DENIAL_KEY",
+]

vsl_langchain-0.1.2/src/vsl_langchain/adapter.py

@@ -0,0 +1,132 @@
+"""LangChainAdapter + VSLToolMiddleware: a VSLAdapter conformant with
+vsl-core's conformance contract, plus the LangChain-specific wiring to gate
+tool calls inside a create_agent() agent via AgentMiddleware.wrap_tool_call.
+
+wrap_tool_call is a confirmed F1 pre-commitment interception point --
+verified directly against langchain's actual source
+(langchain/agents/middleware/types.py) and langgraph's ToolCallRequest
+(langgraph/prebuilt/tool_node.py), not assumed from docs prose. The
+middleware receives the ToolCallRequest strictly before the tool executes,
+and structurally controls whether the real call (`handler`) ever runs --
+the framework's own docstring says outright you can "skip calling it to
+short-circuit". This is the same F1 property vsl-langgraph's LangGraphAdapter
+relies on, just reached through create_agent's own sanctioned middleware
+hook instead of a hand-wrapped node function.
+
+The compiled gate itself is the same framework-agnostic async callable
+vsl-core's own PlainPythonReferenceAdapter produces -- LangChainAdapter's
+compile_pre_node/compile_invariant are intentionally near-identical to
+vsl-langgraph's LangGraphAdapter for that reason. What this package adds on
+top is VSLToolMiddleware: the tool-name-keyed wiring for create_agent's
+middleware list, and the ToolMessage-shaped denial response create_agent
+actually expects back from wrap_tool_call.
+
+Requires langchain>=1.0's create_agent API (AgentMiddleware.wrap_tool_call).
+Does not support the deprecated AgentExecutor/create_react_agent path --
+that API predates the middleware system this adapter depends on.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Mapping
+
+from langchain.agents.middleware.types import AgentMiddleware
+from langchain_core.messages import ToolMessage
+from vsl_core.constructs import Invariant, PreNode
+from vsl_core.conformance.protocol import CompiledGate
+from vsl_core.exceptions import AutomationDeniedException, InvariantViolation
+
+DEFAULT_DENIAL_KEY = "vsl_denial"
+
+
+class LangChainAdapter:
+    """VSLAdapter implementation. Gate-compilation logic is intentionally
+    identical in shape to vsl-langgraph's LangGraphAdapter -- the compiled
+    gate is framework-agnostic (vsl_core.conformance.protocol.CompiledGate);
+    only the wiring around it (VSLToolMiddleware, below) is LangChain-specific.
+    """
+
+    def compile_pre_node(self, pre_node: PreNode) -> CompiledGate:
+        async def gate(candidate_input: Any) -> None:
+            estimate = await pre_node.monitor(candidate_input)
+            if not estimate.sufficient(pre_node.gamma_threshold):
+                raise AutomationDeniedException(
+                    reason=f"Pre-node '{pre_node.name}' insufficient Gamma",
+                    identity_key="vsl-langchain",
+                )
+
+        return gate
+
+    def compile_invariant(self, invariant: Invariant) -> CompiledGate:
+        async def gate(candidate_input: Any) -> None:
+            holds = await invariant.rule(candidate_input)
+            if not holds:
+                reason = f"Invariant '{invariant.name}' violated"
+                terminal_state_name = invariant.on_violation.name if invariant.on_violation is not None else None
+                if terminal_state_name is not None:
+                    reason += f" -- entering terminal state '{terminal_state_name}'"
+                raise InvariantViolation(
+                    reason=reason,
+                    identity_key="vsl-langchain",
+                    invariant_name=invariant.name,
+                    terminal_state_name=terminal_state_name,
+                )
+
+        return gate
+
+
+class VSLToolMiddleware(AgentMiddleware):
+    """Gates specific tools inside a create_agent() agent, via
+    AgentMiddleware.awrap_tool_call.
+
+    `gates_by_tool_name` maps a tool's name (matched against
+    request.tool_call["name"]) to a CompiledGate produced by
+    LangChainAdapter.compile_pre_node/compile_invariant. Tools with no
+    entry in this mapping are ungated -- they pass straight to `handler`,
+    matching vsl-core's own "not every action needs a gate" posture (a
+    read-only lookup tool, for example, shouldn't be gated at all).
+
+    `candidate_input_fn` extracts whatever the gate should evaluate from the
+    ToolCallRequest; defaults to passing the request's tool_call dict
+    (name/args/id) through unchanged, matching vsl-langgraph's gated_node
+    default of passing the whole state through.
+
+    On denial, returns a ToolMessage (status="error") carrying the raised
+    exception's reason instead of letting it propagate -- the tool call
+    itself never fires, since `handler` is never called. This mirrors
+    gated_node's convention (denial becomes a state update, not a crash)
+    adapted to what create_agent's tool-call loop actually expects back:
+    a ToolMessage, not a raised exception.
+    """
+
+    def __init__(
+        self,
+        gates_by_tool_name: Mapping[str, CompiledGate],
+        *,
+        candidate_input_fn: Callable[[Any], Any] | None = None,
+        denial_key: str = DEFAULT_DENIAL_KEY,
+    ) -> None:
+        self._gates = dict(gates_by_tool_name)
+        self._extract = candidate_input_fn or (lambda request: request.tool_call)
+        self._denial_key = denial_key
+
+    async def awrap_tool_call(
+        self,
+        request: Any,
+        handler: Callable[[Any], Awaitable[ToolMessage | Any]],
+    ) -> ToolMessage | Any:
+        tool_name = request.tool_call["name"]
+        gate = self._gates.get(tool_name)
+        if gate is None:
+            return await handler(request)
+
+        try:
+            await gate(self._extract(request))
+        except AutomationDeniedException as exc:
+            return ToolMessage(
+                content=f"Denied by VSL governance: {exc}",
+                tool_call_id=request.tool_call["id"],
+                status="error",
+            )
+
+        return await handler(request)

vsl_langchain-0.1.2/src/vsl_langchain.egg-info/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: vsl-langchain
+Version: 0.1.2
+Summary: LangChain adapter for VSL (VERBA Specification Language) governance primitives -- implements vsl-core's VSLAdapter conformance contract via create_agent's AgentMiddleware.wrap_tool_call hook.
+License: MIT
+Project-URL: Homepage, https://github.com/supersemantics/VSL-LangChain
+Project-URL: Repository, https://github.com/supersemantics/VSL-LangChain
+Project-URL: Changelog, https://github.com/supersemantics/VSL-LangChain/blob/HEAD/CHANGELOG.md
+Project-URL: Issues, https://github.com/supersemantics/VSL-LangChain/issues
+Keywords: governance,ai-safety,guardrails,langchain,vsl,verba
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: super-semantics-vsl<0.4,>=0.3
+Requires-Dist: langchain>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# vsl-langchain
+
+A [LangChain](https://github.com/langchain-ai/langchain) adapter for
+[`vsl-core`](https://github.com/supersemantics/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
+
+```bash
+pip install vsl-langchain
+```
+
+This installs vsl-core (`super-semantics-vsl`, imported as `vsl_core`) and LangChain with it.
+
+## Quick taste
+
+```python
+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](https://github.com/supersemantics/VSL-Core/blob/main/docs/building-with-vsl-core.md#step-3-the-five-things-youll-actually-write) 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
+```

vsl_langchain-0.1.2/src/vsl_langchain.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/vsl_langchain/__init__.py
+src/vsl_langchain/adapter.py
+src/vsl_langchain.egg-info/PKG-INFO
+src/vsl_langchain.egg-info/SOURCES.txt
+src/vsl_langchain.egg-info/dependency_links.txt
+src/vsl_langchain.egg-info/requires.txt
+src/vsl_langchain.egg-info/top_level.txt
+tests/test_conformance.py
+tests/test_integration.py

vsl_langchain-0.1.2/src/vsl_langchain.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vsl_langchain-0.1.2/src/vsl_langchain.egg-info/requires.txt

@@ -0,0 +1,6 @@
+super-semantics-vsl<0.4,>=0.3
+langchain>=1.0
+
+[dev]
+pytest>=7
+pytest-asyncio>=0.23

vsl_langchain-0.1.2/src/vsl_langchain.egg-info/top_level.txt

@@ -0,0 +1 @@
+vsl_langchain

vsl_langchain-0.1.2/tests/test_conformance.py

@@ -0,0 +1,8 @@
+from vsl_core.conformance.suite import run_conformance_suite
+
+from vsl_langchain import LangChainAdapter
+
+
+def test_langchain_adapter_is_conformant():
+    failures = run_conformance_suite(LangChainAdapter())
+    assert failures == []

vsl_langchain-0.1.2/tests/test_integration.py

@@ -0,0 +1,119 @@
+"""Exercises VSLToolMiddleware against the real langchain/langgraph types
+(ToolCallRequest, ToolMessage), not mocks -- same discipline as
+vsl-langgraph's test_integration.py.
+"""
+
+from typing import Any
+
+from langgraph.prebuilt.tool_node import ToolCallRequest
+from vsl_core.constructs import Invariant, PreNode
+from vsl_core.exceptions import InvariantViolation
+from vsl_core.metrics import AssuranceBasis, F2Modification, GammaEstimate
+
+from vsl_langchain import LangChainAdapter, VSLToolMiddleware
+
+_ASSURANCE_BASIS = AssuranceBasis(f1_pre_commitment=True, f2_modification=F2Modification.NONE)
+
+_HARD_CAP = 1000.0
+
+
+def _make_request(name: str, args: dict[str, Any], call_id: str = "call_1") -> ToolCallRequest:
+    return ToolCallRequest(
+        tool_call={"name": name, "args": args, "id": call_id, "type": "tool_call"},
+        tool=None,
+        state={},
+        runtime=None,
+    )
+
+
+async def _under_hard_cap(candidate_input: Any) -> GammaEstimate:
+    amount = candidate_input["args"].get("amount", 0.0)
+    return GammaEstimate(gamma_hat=2.0 if amount <= _HARD_CAP else 0.0)
+
+
+async def _refund_amount_ok(candidate_input: Any) -> bool:
+    amount = candidate_input["args"].get("amount", 0.0)
+    return amount <= _HARD_CAP
+
+
+async def _handler_records_call(calls: list[str]):
+    async def handler(request: ToolCallRequest):
+        calls.append(request.tool_call["name"])
+        return f"executed {request.tool_call['name']}"
+
+    return handler
+
+
+def _build_pre_node_middleware() -> VSLToolMiddleware:
+    adapter = LangChainAdapter()
+    pre_node = PreNode(
+        name="refund-amount-pre-node",
+        description="Requires refund amount under the hard cap before send_refund runs.",
+        monitor=_under_hard_cap,
+        assurance_basis=_ASSURANCE_BASIS,
+    )
+    gate = adapter.compile_pre_node(pre_node)
+    return VSLToolMiddleware(gates_by_tool_name={"send_refund": gate})
+
+
+def _build_invariant_middleware() -> VSLToolMiddleware:
+    adapter = LangChainAdapter()
+    invariant = Invariant(
+        name="refund-amount-invariant",
+        description="Refund amount must never exceed the hard cap -- non-bypassable.",
+        rule=_refund_amount_ok,
+        assurance_basis=_ASSURANCE_BASIS,
+    )
+    gate = adapter.compile_invariant(invariant)
+    return VSLToolMiddleware(gates_by_tool_name={"send_refund": gate})
+
+
+async def test_pre_node_allows_call_under_cap_and_handler_actually_runs():
+    calls: list[str] = []
+    middleware = _build_pre_node_middleware()
+    handler = await _handler_records_call(calls)
+
+    request = _make_request("send_refund", {"amount": 250.0})
+    result = await middleware.awrap_tool_call(request, handler)
+
+    assert calls == ["send_refund"]
+    assert result == "executed send_refund"
+
+
+async def test_pre_node_denies_call_over_cap_and_handler_never_runs():
+    calls: list[str] = []
+    middleware = _build_pre_node_middleware()
+    handler = await _handler_records_call(calls)
+
+    request = _make_request("send_refund", {"amount": 5000.0}, call_id="call_2")
+    result = await middleware.awrap_tool_call(request, handler)
+
+    # The real proof of F1 pre-commitment: handler was never called at all.
+    assert calls == []
+    assert result.tool_call_id == "call_2"
+    assert result.status == "error"
+    assert "Denied by VSL governance" in result.content
+
+
+async def test_invariant_denies_call_over_cap_and_handler_never_runs():
+    calls: list[str] = []
+    middleware = _build_invariant_middleware()
+    handler = await _handler_records_call(calls)
+
+    request = _make_request("send_refund", {"amount": 5000.0}, call_id="call_3")
+    result = await middleware.awrap_tool_call(request, handler)
+
+    assert calls == []
+    assert result.status == "error"
+
+
+async def test_ungated_tool_passes_straight_through():
+    calls: list[str] = []
+    middleware = _build_pre_node_middleware()  # only gates "send_refund"
+    handler = await _handler_records_call(calls)
+
+    request = _make_request("lookup_order", {"order_id": "ORD-1"})
+    result = await middleware.awrap_tool_call(request, handler)
+
+    assert calls == ["lookup_order"]
+    assert result == "executed lookup_order"