vsl-langgraph 0.1.2__tar.gz

vsl_langgraph-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_langgraph-0.1.2/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: vsl-langgraph
+Version: 0.1.2
+Summary: LangGraph adapter for VSL (VERBA Specification Language) governance primitives -- implements vsl-core's VSLAdapter conformance contract.
+License: MIT
+Project-URL: Homepage, https://github.com/supersemantics/VSL-Langgraph
+Project-URL: Repository, https://github.com/supersemantics/VSL-Langgraph
+Project-URL: Changelog, https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/CHANGELOG.md
+Project-URL: Issues, https://github.com/supersemantics/VSL-Langgraph/issues
+Keywords: governance,ai-safety,guardrails,langgraph,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: langgraph>=0.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: openai>=1.0; extra == "examples"
+Requires-Dist: anthropic>=0.40; extra == "examples"
+Requires-Dist: google-genai>=0.5; extra == "examples"
+Dynamic: license-file
+
+# vsl-langgraph
+
+A [LangGraph](https://github.com/langchain-ai/langgraph) adapter for
+[`vsl-core`](https://github.com/supersemantics/VSL-Core): implements `vsl_core.conformance.protocol.VSLAdapter`
+and provides the LangGraph-specific wiring to call a compiled gate from a
+`StateGraph` node and route around a denial.
+
+**Is:**
+- A `VSLAdapter` implementation (`LangGraphAdapter`) that passes `vsl_core.conformance.suite.run_conformance_suite` with an empty result.
+- A small set of wiring helpers (`gated_node`, `route_on_denial`) for calling a compiled gate immediately before a node's side effect and routing to a blocked/terminal node via `add_conditional_edges` on denial.
+
+**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 LangGraph.
+- Automatic interception. LangGraph has no dedicated guardrail/hook type -- a node is a plain callable, so the gate is called explicitly inside `gated_node`, the same way `vsl-core`'s own docs describe calling a gate in plain Python.
+
+## Documentation
+
+- [docs/concepts.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/concepts.md) -- the vocabulary (`PreNode`, `Invariant`, `GammaEstimate`, `AssuranceBasis`/F1-F2, `CompiledGate`), a diagram of the gate lifecycle, which gate shape fits which kind of LangGraph node, and a complete scope table for every `vsl-core` construct -- not just the two this adapter compiles.
+- [docs/quickstart.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/quickstart.md) -- install through a working chained-gate graph, building up from one gate to real LLM-backed gates, with real diagrams generated from the actual compiled graphs.
+- [docs/api-reference.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/api-reference.md) -- `LangGraphAdapter` / `gated_node` / `route_on_denial`, every parameter, scannable.
+- [docs/beyond-the-gate.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/beyond-the-gate.md) -- everything `vsl-core` defines that this adapter doesn't compile (`TerminalState`, `VerbaLedger`, re-enablement, `Cluster`, `Specification`/`Proofing`/`Binding`) but that still applies inside a LangGraph app, each with real, run worked examples.
+- [docs/dos-and-donts.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/dos-and-donts.md) -- a scannable checklist for writing or reviewing `vsl-langgraph` code, each rule traced back to a real reason.
+- [docs/testing-your-gates.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/testing-your-gates.md) -- how to prove your own `PreNode`/`Invariant` wiring is correct, generalized from this repo's own test suite.
+- [docs/troubleshooting.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/troubleshooting.md) -- real, reproduced failure modes (not guessed) with exact error text and fixes.
+
+## Install
+
+```
+pip install vsl-langgraph
+```
+
+This installs vsl-core (`super-semantics-vsl`, imported as `vsl_core`) and LangGraph with it. From a
+local clone of this repo: `pip install -e .`
+
+## Quick taste
+
+```python
+gate = LangGraphAdapter().compile_pre_node(pre_node)  # or .compile_invariant(invariant)
+
+graph.add_node("do_the_thing", gated_node(gate, do_the_thing))
+graph.add_conditional_edges("do_the_thing", route_on_denial("blocked", "allowed"))
+```
+
+`gated_node` calls `gate` immediately before `do_the_thing` runs; on denial, `do_the_thing` never runs and `route_on_denial` sends the graph to `"blocked"` instead. Full walkthrough with real output: [docs/quickstart.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/quickstart.md).
+
+## Sample agents
+
+`examples/` is organized by domain -- see [examples/README.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/examples/README.md) for the full list and the roadmap for domains not built yet. Four so far:
+
+- **`examples/financial-agents/purchase_approval_agent.py`** -- both governance primitives chained in one graph, synthetic and LLM-free. The fastest read of the gate-wiring pattern.
+- **`examples/marketing/research_publish_agent.py`** -- the same pattern behind five real LLM calls across three providers (Gemini, OpenAI, three Claude models), with an automatic offline fallback when no API keys are set.
+- **`examples/customer-support/refund_support_agent.py`** -- the one with a *dynamic* graph topology: an LLM picks which tool to call (`lookup_order` / `issue_refund` / `send_email`) and a plain LangGraph router sends the run to whichever node it chose, before any vsl-core gate is even reached. `issue_refund` is gated by an `Invariant`, `send_email` by a `PreNode`, `lookup_order` is ungated -- straight from `vsl-core`'s own canonical worked example.
+- **`examples/chat-conversation/chat_reply_agent.py`** -- governance on what the agent is about to *say*, not a backend action: an `Invariant` blocking an unverified guarantee, a `PreNode` handing off to a human on low confidence.
+
+```
+python examples/financial-agents/purchase_approval_agent.py
+python examples/marketing/research_publish_agent.py
+python examples/customer-support/refund_support_agent.py
+python examples/chat-conversation/chat_reply_agent.py
+```
+
+All four run with zero setup (deterministic offline fallbacks) or live against real providers with the right API keys set. Diagrammed and walked through step by step in [docs/quickstart.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/quickstart.md).
+
+## Layout
+
+```
+src/vsl_langgraph/
+├── adapter.py       LangGraphAdapter (VSLAdapter conformance contract)
+└── integration.py   gated_node, route_on_denial (StateGraph wiring)
+docs/
+├── concepts.md            vocabulary, gate-lifecycle diagram, full construct scope table
+├── quickstart.md          install -> working graph, with real diagrams
+├── api-reference.md       every export, scannable
+├── beyond-the-gate.md     TerminalState/ledger/escalation, Cluster, Specification -- real worked examples
+├── dos-and-donts.md       scannable checklist for writing/reviewing this code
+├── testing-your-gates.md  how to prove your own gate wiring is correct
+└── troubleshooting.md     real, reproduced failure modes
+examples/
+├── README.md                 domain taxonomy and roadmap
+├── financial-agents/
+│   └── purchase_approval_agent.py   PreNode + Invariant, no LLM calls
+├── marketing/
+│   ├── research_publish_agent.py    same pattern, 5 real LLM calls / 3 providers
+│   └── marketing_providers.py, marketing_fake_providers.py, marketing_model_ids.py
+├── customer-support/
+│   ├── refund_support_agent.py      LLM picks the tool; dynamic routing, not fixed topology
+│   └── support_providers.py, support_fake_providers.py
+└── chat-conversation/
+    ├── chat_reply_agent.py          governs the agent's own reply, not a backend action
+    └── chat_providers.py, chat_fake_providers.py
+tests/
+├── test_conformance.py               run_conformance_suite(LangGraphAdapter()) == []
+├── test_integration.py               exercises a real compiled StateGraph
+├── test_purchase_approval_agent.py   exercises the financial-agents sample's three scenarios
+├── test_customer_support_agent.py    exercises dynamic routing + both gate types
+└── test_chat_reply_agent.py          exercises the chat sample's three scenarios
+```
+
+Every example domain's provider modules are named with a domain prefix (`marketing_*`, `support_*`, `chat_*`) rather than a generic `providers.py` -- several examples import a same-named module in the same test run, and Python's module cache is process-global, so generic names collide across examples.
+
+## Status
+
+Alpha. Conformance-suite green; integration tested against a real
+`StateGraph` for both the `PreNode` and `Invariant` paths (pass-through and
+denial routing), including chained multi-gate graphs, real LLM-backed
+gates across three providers, and -- as of `customer-support/refund_support_agent.py`
+-- a graph where an LLM's own output decides which node runs next, not
+just a fixed topology with LLM-backed gates. `gated_node` doesn't implement
+`Fallback`'s retry/intervention fields (`delta_factor`, `max_retries`,
+`intervention`) -- those aren't consumed by `vsl-core`'s own
+`PlainPythonReferenceAdapter` either, so this mirrors the reference
+adapter's actual behavior rather than leaving out something `vsl-core`
+itself defines a contract for.

vsl_langgraph-0.1.2/README.md

@@ -0,0 +1,113 @@
+# vsl-langgraph
+
+A [LangGraph](https://github.com/langchain-ai/langgraph) adapter for
+[`vsl-core`](https://github.com/supersemantics/VSL-Core): implements `vsl_core.conformance.protocol.VSLAdapter`
+and provides the LangGraph-specific wiring to call a compiled gate from a
+`StateGraph` node and route around a denial.
+
+**Is:**
+- A `VSLAdapter` implementation (`LangGraphAdapter`) that passes `vsl_core.conformance.suite.run_conformance_suite` with an empty result.
+- A small set of wiring helpers (`gated_node`, `route_on_denial`) for calling a compiled gate immediately before a node's side effect and routing to a blocked/terminal node via `add_conditional_edges` on denial.
+
+**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 LangGraph.
+- Automatic interception. LangGraph has no dedicated guardrail/hook type -- a node is a plain callable, so the gate is called explicitly inside `gated_node`, the same way `vsl-core`'s own docs describe calling a gate in plain Python.
+
+## Documentation
+
+- [docs/concepts.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/concepts.md) -- the vocabulary (`PreNode`, `Invariant`, `GammaEstimate`, `AssuranceBasis`/F1-F2, `CompiledGate`), a diagram of the gate lifecycle, which gate shape fits which kind of LangGraph node, and a complete scope table for every `vsl-core` construct -- not just the two this adapter compiles.
+- [docs/quickstart.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/quickstart.md) -- install through a working chained-gate graph, building up from one gate to real LLM-backed gates, with real diagrams generated from the actual compiled graphs.
+- [docs/api-reference.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/api-reference.md) -- `LangGraphAdapter` / `gated_node` / `route_on_denial`, every parameter, scannable.
+- [docs/beyond-the-gate.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/beyond-the-gate.md) -- everything `vsl-core` defines that this adapter doesn't compile (`TerminalState`, `VerbaLedger`, re-enablement, `Cluster`, `Specification`/`Proofing`/`Binding`) but that still applies inside a LangGraph app, each with real, run worked examples.
+- [docs/dos-and-donts.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/dos-and-donts.md) -- a scannable checklist for writing or reviewing `vsl-langgraph` code, each rule traced back to a real reason.
+- [docs/testing-your-gates.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/testing-your-gates.md) -- how to prove your own `PreNode`/`Invariant` wiring is correct, generalized from this repo's own test suite.
+- [docs/troubleshooting.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/troubleshooting.md) -- real, reproduced failure modes (not guessed) with exact error text and fixes.
+
+## Install
+
+```
+pip install vsl-langgraph
+```
+
+This installs vsl-core (`super-semantics-vsl`, imported as `vsl_core`) and LangGraph with it. From a
+local clone of this repo: `pip install -e .`
+
+## Quick taste
+
+```python
+gate = LangGraphAdapter().compile_pre_node(pre_node)  # or .compile_invariant(invariant)
+
+graph.add_node("do_the_thing", gated_node(gate, do_the_thing))
+graph.add_conditional_edges("do_the_thing", route_on_denial("blocked", "allowed"))
+```
+
+`gated_node` calls `gate` immediately before `do_the_thing` runs; on denial, `do_the_thing` never runs and `route_on_denial` sends the graph to `"blocked"` instead. Full walkthrough with real output: [docs/quickstart.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/quickstart.md).
+
+## Sample agents
+
+`examples/` is organized by domain -- see [examples/README.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/examples/README.md) for the full list and the roadmap for domains not built yet. Four so far:
+
+- **`examples/financial-agents/purchase_approval_agent.py`** -- both governance primitives chained in one graph, synthetic and LLM-free. The fastest read of the gate-wiring pattern.
+- **`examples/marketing/research_publish_agent.py`** -- the same pattern behind five real LLM calls across three providers (Gemini, OpenAI, three Claude models), with an automatic offline fallback when no API keys are set.
+- **`examples/customer-support/refund_support_agent.py`** -- the one with a *dynamic* graph topology: an LLM picks which tool to call (`lookup_order` / `issue_refund` / `send_email`) and a plain LangGraph router sends the run to whichever node it chose, before any vsl-core gate is even reached. `issue_refund` is gated by an `Invariant`, `send_email` by a `PreNode`, `lookup_order` is ungated -- straight from `vsl-core`'s own canonical worked example.
+- **`examples/chat-conversation/chat_reply_agent.py`** -- governance on what the agent is about to *say*, not a backend action: an `Invariant` blocking an unverified guarantee, a `PreNode` handing off to a human on low confidence.
+
+```
+python examples/financial-agents/purchase_approval_agent.py
+python examples/marketing/research_publish_agent.py
+python examples/customer-support/refund_support_agent.py
+python examples/chat-conversation/chat_reply_agent.py
+```
+
+All four run with zero setup (deterministic offline fallbacks) or live against real providers with the right API keys set. Diagrammed and walked through step by step in [docs/quickstart.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/quickstart.md).
+
+## Layout
+
+```
+src/vsl_langgraph/
+├── adapter.py       LangGraphAdapter (VSLAdapter conformance contract)
+└── integration.py   gated_node, route_on_denial (StateGraph wiring)
+docs/
+├── concepts.md            vocabulary, gate-lifecycle diagram, full construct scope table
+├── quickstart.md          install -> working graph, with real diagrams
+├── api-reference.md       every export, scannable
+├── beyond-the-gate.md     TerminalState/ledger/escalation, Cluster, Specification -- real worked examples
+├── dos-and-donts.md       scannable checklist for writing/reviewing this code
+├── testing-your-gates.md  how to prove your own gate wiring is correct
+└── troubleshooting.md     real, reproduced failure modes
+examples/
+├── README.md                 domain taxonomy and roadmap
+├── financial-agents/
+│   └── purchase_approval_agent.py   PreNode + Invariant, no LLM calls
+├── marketing/
+│   ├── research_publish_agent.py    same pattern, 5 real LLM calls / 3 providers
+│   └── marketing_providers.py, marketing_fake_providers.py, marketing_model_ids.py
+├── customer-support/
+│   ├── refund_support_agent.py      LLM picks the tool; dynamic routing, not fixed topology
+│   └── support_providers.py, support_fake_providers.py
+└── chat-conversation/
+    ├── chat_reply_agent.py          governs the agent's own reply, not a backend action
+    └── chat_providers.py, chat_fake_providers.py
+tests/
+├── test_conformance.py               run_conformance_suite(LangGraphAdapter()) == []
+├── test_integration.py               exercises a real compiled StateGraph
+├── test_purchase_approval_agent.py   exercises the financial-agents sample's three scenarios
+├── test_customer_support_agent.py    exercises dynamic routing + both gate types
+└── test_chat_reply_agent.py          exercises the chat sample's three scenarios
+```
+
+Every example domain's provider modules are named with a domain prefix (`marketing_*`, `support_*`, `chat_*`) rather than a generic `providers.py` -- several examples import a same-named module in the same test run, and Python's module cache is process-global, so generic names collide across examples.
+
+## Status
+
+Alpha. Conformance-suite green; integration tested against a real
+`StateGraph` for both the `PreNode` and `Invariant` paths (pass-through and
+denial routing), including chained multi-gate graphs, real LLM-backed
+gates across three providers, and -- as of `customer-support/refund_support_agent.py`
+-- a graph where an LLM's own output decides which node runs next, not
+just a fixed topology with LLM-backed gates. `gated_node` doesn't implement
+`Fallback`'s retry/intervention fields (`delta_factor`, `max_retries`,
+`intervention`) -- those aren't consumed by `vsl-core`'s own
+`PlainPythonReferenceAdapter` either, so this mirrors the reference
+adapter's actual behavior rather than leaving out something `vsl-core`
+itself defines a contract for.

vsl_langgraph-0.1.2/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vsl-langgraph"
+version = "0.1.2"
+description = "LangGraph adapter for VSL (VERBA Specification Language) governance primitives -- implements vsl-core's VSLAdapter conformance contract."
+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",
+    "langgraph>=0.2",
+]
+keywords = ["governance", "ai-safety", "guardrails", "langgraph", "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-Langgraph"
+Repository = "https://github.com/supersemantics/VSL-Langgraph"
+Changelog = "https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/CHANGELOG.md"
+Issues = "https://github.com/supersemantics/VSL-Langgraph/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.23"]
+# Only examples/research_publish_agent.py needs these -- src/vsl_langgraph
+# itself never imports a provider SDK, staying model-agnostic same as vsl-core.
+examples = ["openai>=1.0", "anthropic>=0.40", "google-genai>=0.5"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

vsl_langgraph-0.1.2/setup.cfg

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

vsl_langgraph-0.1.2/src/vsl_langgraph/__init__.py

@@ -0,0 +1,9 @@
+from .adapter import LangGraphAdapter
+from .integration import DEFAULT_DENIAL_KEY, gated_node, route_on_denial
+
+__all__ = [
+    "LangGraphAdapter",
+    "gated_node",
+    "route_on_denial",
+    "DEFAULT_DENIAL_KEY",
+]

vsl_langgraph-0.1.2/src/vsl_langgraph/adapter.py

@@ -0,0 +1,163 @@
+"""LangGraphAdapter: a VSLAdapter conformant with vsl-core's conformance
+contract, intended for use inside LangGraph nodes.
+
+LangGraph has no dedicated guardrail/interception type -- a StateGraph node
+is just a plain sync/async callable, and conditional edges are plain router
+functions evaluated after a node returns. There is therefore nothing
+LangGraph-specific to compile a PreNode/Invariant *into*: the compiled gate
+is the same framework-agnostic async callable vsl-core's own
+PlainPythonReferenceAdapter produces, called directly inside a node body
+before the side effect it guards. What this package adds on top (see
+`integration.py`) is the wiring convention for calling that gate from a
+node and routing around a denial with `add_conditional_edges`, not a
+different gate-compilation strategy.
+"""
+
+from __future__ import annotations
+
+import inspect
+import warnings
+from typing import Any, Callable
+
+from vsl_core.constructs import Fallback, Invariant, PreNode
+from vsl_core.conformance.protocol import CompiledGate
+from vsl_core.exceptions import AutomationDeniedException, InvariantViolation
+from vsl_core.metrics import F2Modification
+
+_DEFAULT_FALLBACK = Fallback()
+
+# Source-text markers for hosted, black-box model APIs. A gate whose
+# monitor/rule reaches one of these cannot honestly claim F2Modification.FULL
+# -- FULL requires direct access to the energy function itself (logits,
+# weights, activations), which a hosted API call structurally cannot expose.
+# The honest ceiling for a hosted-API-backed check is PARTIAL (MEDIUM), per
+# vsl-core's own README example. This is a heuristic, not a proof: it scans
+# source text -- the monitor/rule's OWN body (inspect.getsource(fn), not its
+# containing module's entire source; see _reaches_hosted_api's docstring for
+# why that distinction matters), plus one level of indirection through
+# whatever names it directly calls -- catching the common "the actual API
+# call lives in a helper module" shape, e.g. a monitor in agent.py calling
+# judge_confidence() from a separate providers.py that imports anthropic --
+# for these markers. It can still miss deeper indirection (two or more
+# call-frames away, a callable reached only via a dict/attribute lookup,
+# dynamic imports) and cannot confirm a genuine FULL claim is correct either
+# -- it only catches the one concrete, previously-observed failure mode of
+# claiming FULL while calling a hosted API.
+_HOSTED_API_MARKERS = (
+    "openai",
+    "anthropic",
+    "google.genai",
+    "google.generativeai",
+    "cohere",
+    "mistralai",
+)
+
+
+def _reaches_hosted_api(fn: Callable[..., Any], _seen: set | None = None) -> bool:
+    """Scoped to fn's OWN source (inspect.getsource(fn)), not its containing
+    module's entire source. Scanning the whole module was a real false-
+    positive bug found while building a companion prototype: an unrelated
+    function's comment or docstring elsewhere in the same file could
+    trigger a match that had nothing to do with fn itself. Function-level
+    scoping fixes that without requiring every monitor/rule to live in its
+    own file -- real hosted-API calls are actual code inside the relevant
+    function (or a helper it calls, covered by the indirection walk below),
+    not incidental mentions elsewhere in the file.
+    """
+    if _seen is None:
+        _seen = set()
+    if fn in _seen:
+        return False
+    _seen.add(fn)
+
+    if inspect.getmodule(fn) is None:
+        return False
+    try:
+        source = inspect.getsource(fn)
+    except (OSError, TypeError):
+        return False
+    # Case-insensitive: real code capitalizes SDK class names (AsyncAnthropic,
+    # AsyncOpenAI), which a case-sensitive check against lowercase "anthropic"/
+    # "openai" markers would miss -- found and fixed after function-scoping
+    # (above) removed an accidental crutch: the old whole-module scan happened
+    # to also catch the lowercase `from anthropic import ...` line elsewhere
+    # in the file, masking this case bug until scoping narrowed to fn itself.
+    source_lower = source.lower()
+    if any(marker in source_lower for marker in _HOSTED_API_MARKERS):
+        return True
+
+    # One level of indirection: follow names this function's body directly
+    # references, in case the real hosted-API call lives in a helper it
+    # calls rather than in its own module.
+    code = getattr(fn, "__code__", None)
+    globalns = getattr(fn, "__globals__", None)
+    if code is None or globalns is None:
+        return False
+    for referenced_name in code.co_names:
+        candidate = globalns.get(referenced_name)
+        if callable(candidate) and candidate is not fn:
+            if _reaches_hosted_api(candidate, _seen):
+                return True
+    return False
+
+
+def _warn_if_full_claim_reaches_hosted_api(name: str, assurance_basis: Any, fn: Callable[..., Any]) -> None:
+    if assurance_basis.f2_modification != F2Modification.FULL:
+        return
+    if not _reaches_hosted_api(fn):
+        return
+    warnings.warn(
+        f"'{name}' claims F2Modification.FULL, but its monitor/rule appears to "
+        "call a hosted model API (openai/anthropic/google.genai/cohere/mistralai "
+        "detected in its module's source). A hosted, black-box API call cannot "
+        "directly modify the energy function -- FULL is not achievable this way. "
+        "The honest ceiling is F2Modification.PARTIAL (MEDIUM assurance), per "
+        "vsl-core's own README F1/F2 example. This is a heuristic check, not "
+        "proof -- it can miss indirect calls, and passing it does not confirm "
+        "FULL is correct either.",
+        stacklevel=3,
+    )
+
+
+class LangGraphAdapter:
+    def compile_pre_node(self, pre_node: PreNode) -> CompiledGate:
+        if pre_node.fallback != _DEFAULT_FALLBACK:
+            warnings.warn(
+                f"PreNode '{pre_node.name}' sets a non-default Fallback "
+                f"({pre_node.fallback!r}), but gated_node does not consume "
+                "Fallback -- a denial raises once, immediately, with no "
+                "retry loop. See docs/dos-and-donts.md if you need retry "
+                "behavior; you must implement it yourself around the "
+                "compiled gate.",
+                stacklevel=2,
+            )
+        _warn_if_full_claim_reaches_hosted_api(f"PreNode '{pre_node.name}'", pre_node.assurance_basis, pre_node.monitor)
+
+        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-langgraph",
+                )
+
+        return gate
+
+    def compile_invariant(self, invariant: Invariant) -> CompiledGate:
+        _warn_if_full_claim_reaches_hosted_api(f"Invariant '{invariant.name}'", invariant.assurance_basis, invariant.rule)
+
+        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-langgraph",
+                    invariant_name=invariant.name,
+                    terminal_state_name=terminal_state_name,
+                )
+
+        return gate

vsl_langgraph-0.1.2/src/vsl_langgraph/integration.py

@@ -0,0 +1,81 @@
+"""Wiring helpers for calling a compiled VSL gate from inside a LangGraph
+node and routing around a denial with `add_conditional_edges`.
+
+vsl-core does not intercept anything on its own (see
+vsl-core/docs/building-with-vsl-core.md, "know what's automatic and what
+you write yourself"): a compiled gate only ever raises or returns, on
+demand, when called. `gated_node` is that call site, made reusable for a
+LangGraph StateGraph -- it calls the gate immediately before the wrapped
+node would run (preserving F1 pre-commitment: the gate completes strictly
+before the guarded node's side effect), and on denial returns a state
+update instead of letting the exception propagate, so a conditional edge
+can route to a blocked/terminal node in the normal LangGraph way rather
+than crashing the graph run.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Awaitable, Callable, Mapping
+
+from vsl_core.conformance.protocol import CompiledGate
+from vsl_core.exceptions import AutomationDeniedException
+
+StateNode = Callable[[Mapping[str, Any]], Any]
+
+DEFAULT_DENIAL_KEY = "vsl_denial"
+
+
+def gated_node(
+    gate: CompiledGate,
+    node: StateNode,
+    *,
+    candidate_input_fn: Callable[[Mapping[str, Any]], Any] | None = None,
+    denial_key: str = DEFAULT_DENIAL_KEY,
+) -> Callable[[Mapping[str, Any]], Awaitable[dict[str, Any]]]:
+    """Wrap `node` so `gate` is checked immediately before it runs.
+
+    `candidate_input_fn` extracts whatever the gate should evaluate from
+    graph state; defaults to passing the whole state through unchanged.
+
+    On denial, `node` is never called and the returned state update sets
+    `denial_key` to the caught exception -- pair with `route_on_denial`
+    (or your own router reading `denial_key`) in `add_conditional_edges` to
+    send the run to a blocked/terminal node.
+
+    Does not consume `PreNode.fallback` -- a denial raises once,
+    immediately, with no retry loop, regardless of `fallback.max_retries`.
+    `LangGraphAdapter.compile_pre_node` warns if a non-default `Fallback`
+    is set. See docs/dos-and-donts.md.
+    """
+    extract = candidate_input_fn or (lambda state: state)
+
+    async def wrapped(state: Mapping[str, Any]) -> dict[str, Any]:
+        try:
+            await gate(extract(state))
+        except AutomationDeniedException as exc:
+            return {denial_key: exc}
+
+        result = node(state)
+        if inspect.isawaitable(result):
+            result = await result
+        return dict(result) if result else {}
+
+    return wrapped
+
+
+def route_on_denial(
+    blocked_node: str,
+    allowed_node: str,
+    *,
+    denial_key: str = DEFAULT_DENIAL_KEY,
+) -> Callable[[Mapping[str, Any]], str]:
+    """Build a router for `add_conditional_edges` matching `gated_node`'s
+    convention: routes to `blocked_node` if `denial_key` is set in state
+    (truthy), otherwise to `allowed_node`.
+    """
+
+    def router(state: Mapping[str, Any]) -> str:
+        return blocked_node if state.get(denial_key) is not None else allowed_node
+
+    return router

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

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: vsl-langgraph
+Version: 0.1.2
+Summary: LangGraph adapter for VSL (VERBA Specification Language) governance primitives -- implements vsl-core's VSLAdapter conformance contract.
+License: MIT
+Project-URL: Homepage, https://github.com/supersemantics/VSL-Langgraph
+Project-URL: Repository, https://github.com/supersemantics/VSL-Langgraph
+Project-URL: Changelog, https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/CHANGELOG.md
+Project-URL: Issues, https://github.com/supersemantics/VSL-Langgraph/issues
+Keywords: governance,ai-safety,guardrails,langgraph,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: langgraph>=0.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: openai>=1.0; extra == "examples"
+Requires-Dist: anthropic>=0.40; extra == "examples"
+Requires-Dist: google-genai>=0.5; extra == "examples"
+Dynamic: license-file
+
+# vsl-langgraph
+
+A [LangGraph](https://github.com/langchain-ai/langgraph) adapter for
+[`vsl-core`](https://github.com/supersemantics/VSL-Core): implements `vsl_core.conformance.protocol.VSLAdapter`
+and provides the LangGraph-specific wiring to call a compiled gate from a
+`StateGraph` node and route around a denial.
+
+**Is:**
+- A `VSLAdapter` implementation (`LangGraphAdapter`) that passes `vsl_core.conformance.suite.run_conformance_suite` with an empty result.
+- A small set of wiring helpers (`gated_node`, `route_on_denial`) for calling a compiled gate immediately before a node's side effect and routing to a blocked/terminal node via `add_conditional_edges` on denial.
+
+**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 LangGraph.
+- Automatic interception. LangGraph has no dedicated guardrail/hook type -- a node is a plain callable, so the gate is called explicitly inside `gated_node`, the same way `vsl-core`'s own docs describe calling a gate in plain Python.
+
+## Documentation
+
+- [docs/concepts.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/concepts.md) -- the vocabulary (`PreNode`, `Invariant`, `GammaEstimate`, `AssuranceBasis`/F1-F2, `CompiledGate`), a diagram of the gate lifecycle, which gate shape fits which kind of LangGraph node, and a complete scope table for every `vsl-core` construct -- not just the two this adapter compiles.
+- [docs/quickstart.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/quickstart.md) -- install through a working chained-gate graph, building up from one gate to real LLM-backed gates, with real diagrams generated from the actual compiled graphs.
+- [docs/api-reference.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/api-reference.md) -- `LangGraphAdapter` / `gated_node` / `route_on_denial`, every parameter, scannable.
+- [docs/beyond-the-gate.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/beyond-the-gate.md) -- everything `vsl-core` defines that this adapter doesn't compile (`TerminalState`, `VerbaLedger`, re-enablement, `Cluster`, `Specification`/`Proofing`/`Binding`) but that still applies inside a LangGraph app, each with real, run worked examples.
+- [docs/dos-and-donts.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/dos-and-donts.md) -- a scannable checklist for writing or reviewing `vsl-langgraph` code, each rule traced back to a real reason.
+- [docs/testing-your-gates.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/testing-your-gates.md) -- how to prove your own `PreNode`/`Invariant` wiring is correct, generalized from this repo's own test suite.
+- [docs/troubleshooting.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/troubleshooting.md) -- real, reproduced failure modes (not guessed) with exact error text and fixes.
+
+## Install
+
+```
+pip install vsl-langgraph
+```
+
+This installs vsl-core (`super-semantics-vsl`, imported as `vsl_core`) and LangGraph with it. From a
+local clone of this repo: `pip install -e .`
+
+## Quick taste
+
+```python
+gate = LangGraphAdapter().compile_pre_node(pre_node)  # or .compile_invariant(invariant)
+
+graph.add_node("do_the_thing", gated_node(gate, do_the_thing))
+graph.add_conditional_edges("do_the_thing", route_on_denial("blocked", "allowed"))
+```
+
+`gated_node` calls `gate` immediately before `do_the_thing` runs; on denial, `do_the_thing` never runs and `route_on_denial` sends the graph to `"blocked"` instead. Full walkthrough with real output: [docs/quickstart.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/quickstart.md).
+
+## Sample agents
+
+`examples/` is organized by domain -- see [examples/README.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/examples/README.md) for the full list and the roadmap for domains not built yet. Four so far:
+
+- **`examples/financial-agents/purchase_approval_agent.py`** -- both governance primitives chained in one graph, synthetic and LLM-free. The fastest read of the gate-wiring pattern.
+- **`examples/marketing/research_publish_agent.py`** -- the same pattern behind five real LLM calls across three providers (Gemini, OpenAI, three Claude models), with an automatic offline fallback when no API keys are set.
+- **`examples/customer-support/refund_support_agent.py`** -- the one with a *dynamic* graph topology: an LLM picks which tool to call (`lookup_order` / `issue_refund` / `send_email`) and a plain LangGraph router sends the run to whichever node it chose, before any vsl-core gate is even reached. `issue_refund` is gated by an `Invariant`, `send_email` by a `PreNode`, `lookup_order` is ungated -- straight from `vsl-core`'s own canonical worked example.
+- **`examples/chat-conversation/chat_reply_agent.py`** -- governance on what the agent is about to *say*, not a backend action: an `Invariant` blocking an unverified guarantee, a `PreNode` handing off to a human on low confidence.
+
+```
+python examples/financial-agents/purchase_approval_agent.py
+python examples/marketing/research_publish_agent.py
+python examples/customer-support/refund_support_agent.py
+python examples/chat-conversation/chat_reply_agent.py
+```
+
+All four run with zero setup (deterministic offline fallbacks) or live against real providers with the right API keys set. Diagrammed and walked through step by step in [docs/quickstart.md](https://github.com/supersemantics/VSL-Langgraph/blob/HEAD/docs/quickstart.md).
+
+## Layout
+
+```
+src/vsl_langgraph/
+├── adapter.py       LangGraphAdapter (VSLAdapter conformance contract)
+└── integration.py   gated_node, route_on_denial (StateGraph wiring)
+docs/
+├── concepts.md            vocabulary, gate-lifecycle diagram, full construct scope table
+├── quickstart.md          install -> working graph, with real diagrams
+├── api-reference.md       every export, scannable
+├── beyond-the-gate.md     TerminalState/ledger/escalation, Cluster, Specification -- real worked examples
+├── dos-and-donts.md       scannable checklist for writing/reviewing this code
+├── testing-your-gates.md  how to prove your own gate wiring is correct
+└── troubleshooting.md     real, reproduced failure modes
+examples/
+├── README.md                 domain taxonomy and roadmap
+├── financial-agents/
+│   └── purchase_approval_agent.py   PreNode + Invariant, no LLM calls
+├── marketing/
+│   ├── research_publish_agent.py    same pattern, 5 real LLM calls / 3 providers
+│   └── marketing_providers.py, marketing_fake_providers.py, marketing_model_ids.py
+├── customer-support/
+│   ├── refund_support_agent.py      LLM picks the tool; dynamic routing, not fixed topology
+│   └── support_providers.py, support_fake_providers.py
+└── chat-conversation/
+    ├── chat_reply_agent.py          governs the agent's own reply, not a backend action
+    └── chat_providers.py, chat_fake_providers.py
+tests/
+├── test_conformance.py               run_conformance_suite(LangGraphAdapter()) == []
+├── test_integration.py               exercises a real compiled StateGraph
+├── test_purchase_approval_agent.py   exercises the financial-agents sample's three scenarios
+├── test_customer_support_agent.py    exercises dynamic routing + both gate types
+└── test_chat_reply_agent.py          exercises the chat sample's three scenarios
+```
+
+Every example domain's provider modules are named with a domain prefix (`marketing_*`, `support_*`, `chat_*`) rather than a generic `providers.py` -- several examples import a same-named module in the same test run, and Python's module cache is process-global, so generic names collide across examples.
+
+## Status
+
+Alpha. Conformance-suite green; integration tested against a real
+`StateGraph` for both the `PreNode` and `Invariant` paths (pass-through and
+denial routing), including chained multi-gate graphs, real LLM-backed
+gates across three providers, and -- as of `customer-support/refund_support_agent.py`
+-- a graph where an LLM's own output decides which node runs next, not
+just a fixed topology with LLM-backed gates. `gated_node` doesn't implement
+`Fallback`'s retry/intervention fields (`delta_factor`, `max_retries`,
+`intervention`) -- those aren't consumed by `vsl-core`'s own
+`PlainPythonReferenceAdapter` either, so this mirrors the reference
+adapter's actual behavior rather than leaving out something `vsl-core`
+itself defines a contract for.

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

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/vsl_langgraph/__init__.py
+src/vsl_langgraph/adapter.py
+src/vsl_langgraph/integration.py
+src/vsl_langgraph.egg-info/PKG-INFO
+src/vsl_langgraph.egg-info/SOURCES.txt
+src/vsl_langgraph.egg-info/dependency_links.txt
+src/vsl_langgraph.egg-info/requires.txt
+src/vsl_langgraph.egg-info/top_level.txt
+tests/test_chat_reply_agent.py
+tests/test_conformance.py
+tests/test_customer_support_agent.py
+tests/test_full_claim_hosted_api_warning.py
+tests/test_integration.py
+tests/test_purchase_approval_agent.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,11 @@
+super-semantics-vsl<0.4,>=0.3
+langgraph>=0.2
+
+[dev]
+pytest>=7
+pytest-asyncio>=0.23
+
+[examples]
+openai>=1.0
+anthropic>=0.40
+google-genai>=0.5

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

@@ -0,0 +1 @@
+vsl_langgraph

vsl_langgraph-0.1.2/tests/test_chat_reply_agent.py

@@ -0,0 +1,34 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "examples" / "chat-conversation"))
+
+import chat_fake_providers as fake_providers  # noqa: E402
+from chat_reply_agent import build_agent  # noqa: E402
+
+_MESSAGE = "My order hasn't arrived and it's been two weeks, what happens now?"
+
+
+async def test_resolved_reply_is_sent():
+    fake_providers.set_scenario("resolved")
+    result = await build_agent().ainvoke({"customer_message": _MESSAGE})
+    assert result.get("sent_reply") is not None
+    assert result.get("guarantee_denial") is None
+    assert result.get("confidence_denial") is None
+    assert result.get("handed_off") is None
+
+
+async def test_unverified_guarantee_is_handed_off_not_sent():
+    fake_providers.set_scenario("unverified_guarantee")
+    result = await build_agent().ainvoke({"customer_message": _MESSAGE})
+    assert result.get("sent_reply") is None
+    assert result.get("guarantee_denial") is not None
+    assert result.get("handed_off") is True
+
+
+async def test_low_confidence_is_handed_off_not_sent():
+    fake_providers.set_scenario("low_confidence")
+    result = await build_agent().ainvoke({"customer_message": _MESSAGE})
+    assert result.get("sent_reply") is None
+    assert result.get("confidence_denial") is not None
+    assert result.get("handed_off") is True

vsl_langgraph-0.1.2/tests/test_conformance.py

@@ -0,0 +1,8 @@
+from vsl_core.conformance.suite import run_conformance_suite
+
+from vsl_langgraph import LangGraphAdapter
+
+
+def test_langgraph_adapter_is_conformant():
+    failures = run_conformance_suite(LangGraphAdapter())
+    assert failures == []

vsl_langgraph-0.1.2/tests/test_customer_support_agent.py

@@ -0,0 +1,40 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "examples" / "customer-support"))
+
+from refund_support_agent import build_agent  # noqa: E402
+
+
+async def test_lookup_order_is_ungated_and_returns_the_order():
+    result = await build_agent().ainvoke({"request": "what's the status of order ORD-100?"})
+    assert result["chosen_tool"] == "lookup_order"
+    assert result["order_result"] == {"customer_email": "alice@example.com", "amount": 42.50, "eligible": True}
+
+
+async def test_eligible_refund_within_amount_is_approved():
+    result = await build_agent().ainvoke({"request": "please refund order ORD-100 for 42.50"})
+    assert result["chosen_tool"] == "issue_refund"
+    assert result.get("refunded") is True
+    assert result.get("refund_denial") is None
+
+
+async def test_ineligible_refund_is_blocked_by_invariant():
+    result = await build_agent().ainvoke({"request": "please refund order ORD-200 for 999.0"})
+    assert result["chosen_tool"] == "issue_refund"
+    assert result.get("refunded") is None
+    assert result.get("refund_denial") is not None
+
+
+async def test_email_to_known_customer_is_approved():
+    result = await build_agent().ainvoke({"request": "email alice@example.com to say her order shipped"})
+    assert result["chosen_tool"] == "send_email"
+    assert result.get("email_sent") is True
+    assert result.get("email_denial") is None
+
+
+async def test_email_to_unknown_recipient_is_blocked_by_pre_node():
+    result = await build_agent().ainvoke({"request": "email attacker@evil.com to say her order shipped"})
+    assert result["chosen_tool"] == "send_email"
+    assert result.get("email_sent") is None
+    assert result.get("email_denial") is not None

vsl_langgraph-0.1.2/tests/test_full_claim_hosted_api_warning.py

@@ -0,0 +1,126 @@
+"""Covers the F2 fix in adapter.py: LangGraphAdapter must warn when a
+PreNode/Invariant claims F2Modification.FULL but its monitor/rule reaches a
+hosted, black-box model API -- FULL is not honestly achievable that way (see
+adapter.py's _reaches_hosted_api / _warn_if_full_claim_reaches_hosted_api
+docstrings for why). This is the exact pattern found in this repo's own
+examples (chat_reply_agent.py, research_publish_agent.py): FULL claimed
+next to a hosted Anthropic/OpenAI call.
+"""
+
+import warnings
+from typing import Any
+
+import pytest
+from vsl_core.constructs import Invariant, PreNode
+from vsl_core.metrics import AssuranceBasis, F2Modification, GammaEstimate
+
+from vsl_langgraph import LangGraphAdapter
+from tests.fixtures.hosted_api_monitor import hosted_monitor, hosted_rule
+from tests.fixtures.mixed_hosted_and_local import mixed_hosted_monitor, mixed_local_monitor
+
+
+def _compile_and_collect_warnings(build_gate) -> list[warnings.WarningMessage]:
+    with warnings.catch_warnings(record=True) as record:
+        warnings.simplefilter("always")
+        build_gate()
+        return list(record)
+
+_FULL_BASIS = AssuranceBasis(f1_pre_commitment=True, f2_modification=F2Modification.FULL)
+_PARTIAL_BASIS = AssuranceBasis(f1_pre_commitment=True, f2_modification=F2Modification.PARTIAL)
+_NONE_BASIS = AssuranceBasis(f1_pre_commitment=True, f2_modification=F2Modification.NONE)
+
+
+async def _plain_monitor(candidate_input: Any) -> GammaEstimate:
+    # No hosted-API marker anywhere in this module's source.
+    return GammaEstimate(gamma_hat=2.0)
+
+
+async def _plain_rule(candidate_input: Any) -> bool:
+    return True
+
+
+def test_full_claim_reaching_hosted_api_warns_on_pre_node():
+    pre_node = PreNode(
+        name="hosted-pre-node",
+        description="Claims FULL but its monitor's module mentions a hosted API.",
+        monitor=hosted_monitor,
+        assurance_basis=_FULL_BASIS,
+    )
+    with pytest.warns(UserWarning, match="claims F2Modification.FULL"):
+        LangGraphAdapter().compile_pre_node(pre_node)
+
+
+def test_full_claim_reaching_hosted_api_warns_on_invariant():
+    invariant = Invariant(
+        name="hosted-invariant",
+        description="Claims FULL but its rule's module mentions a hosted API.",
+        rule=hosted_rule,
+        assurance_basis=_FULL_BASIS,
+    )
+    with pytest.warns(UserWarning, match="claims F2Modification.FULL"):
+        LangGraphAdapter().compile_invariant(invariant)
+
+
+def test_full_claim_without_hosted_api_does_not_warn():
+    pre_node = PreNode(
+        name="local-pre-node",
+        description="Claims FULL; nothing hosted-API-shaped in this module.",
+        monitor=_plain_monitor,
+        assurance_basis=_FULL_BASIS,
+    )
+    record = _compile_and_collect_warnings(lambda: LangGraphAdapter().compile_pre_node(pre_node))
+    assert not any("claims F2Modification.FULL" in str(w.message) for w in record)
+
+
+def test_partial_claim_reaching_hosted_api_does_not_trigger_full_warning():
+    # PARTIAL is the honest rating for a hosted-API-backed check -- only a
+    # FULL claim should ever trigger this warning.
+    pre_node = PreNode(
+        name="hosted-pre-node-partial",
+        description="Honestly rated PARTIAL for a hosted-API-backed check.",
+        monitor=hosted_monitor,
+        assurance_basis=_PARTIAL_BASIS,
+    )
+    record = _compile_and_collect_warnings(lambda: LangGraphAdapter().compile_pre_node(pre_node))
+    assert not any("claims F2Modification.FULL" in str(w.message) for w in record)
+
+
+def test_none_claim_reaching_hosted_api_does_not_trigger_full_warning():
+    pre_node = PreNode(
+        name="hosted-pre-node-none",
+        description="NONE claim next to a hosted-API-shaped module.",
+        monitor=hosted_monitor,
+        assurance_basis=_NONE_BASIS,
+    )
+    record = _compile_and_collect_warnings(lambda: LangGraphAdapter().compile_pre_node(pre_node))
+    assert not any("claims F2Modification.FULL" in str(w.message) for w in record)
+
+
+def test_same_file_sibling_function_does_not_cross_contaminate():
+    # Regression test for the false positive found while building a
+    # companion prototype: mixed_local_monitor shares a file with
+    # mixed_hosted_monitor, which genuinely mentions "anthropic". Before
+    # _reaches_hosted_api was scoped to each function's own source (rather
+    # than its whole containing module), this would have wrongly flagged
+    # mixed_local_monitor too, just because of its neighbor.
+    pre_node = PreNode(
+        name="mixed-local-pre-node",
+        description="Claims FULL; genuinely local, but shares a file with a hosted-API monitor.",
+        monitor=mixed_local_monitor,
+        assurance_basis=_FULL_BASIS,
+    )
+    record = _compile_and_collect_warnings(lambda: LangGraphAdapter().compile_pre_node(pre_node))
+    assert not any("claims F2Modification.FULL" in str(w.message) for w in record)
+
+
+def test_same_file_sibling_that_genuinely_reaches_hosted_api_is_still_caught():
+    # The other half of the same regression test: the fix must not become
+    # so narrow it stops detecting real cases sitting in a shared file.
+    pre_node = PreNode(
+        name="mixed-hosted-pre-node",
+        description="Claims FULL; genuinely reaches a hosted API.",
+        monitor=mixed_hosted_monitor,
+        assurance_basis=_FULL_BASIS,
+    )
+    with pytest.warns(UserWarning, match="claims F2Modification.FULL"):
+        LangGraphAdapter().compile_pre_node(pre_node)

vsl_langgraph-0.1.2/tests/test_integration.py

@@ -0,0 +1,102 @@
+from typing import Any, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+from vsl_core.constructs import Invariant, PreNode
+from vsl_core.exceptions import InvariantViolation
+from vsl_core.metrics import AssuranceBasis, F2Modification, GammaEstimate
+
+from vsl_langgraph import LangGraphAdapter, gated_node, route_on_denial
+
+_ASSURANCE_BASIS = AssuranceBasis(f1_pre_commitment=True, f2_modification=F2Modification.FULL)
+
+
+class GraphState(TypedDict, total=False):
+    gamma: float
+    ran_side_effect: bool
+    vsl_denial: Any
+
+
+async def _monitor(candidate_input: GraphState) -> GammaEstimate:
+    return GammaEstimate(gamma_hat=candidate_input["gamma"])
+
+
+def _build_graph():
+    pre_node = PreNode(
+        name="integration-test-pre-node",
+        description="Requires gamma above 1.0 before the guarded node runs.",
+        monitor=_monitor,
+        assurance_basis=_ASSURANCE_BASIS,
+        gamma_threshold=1.0,
+    )
+    gate = LangGraphAdapter().compile_pre_node(pre_node)
+
+    def guarded(state: GraphState) -> dict:
+        return {"ran_side_effect": True}
+
+    graph = StateGraph(GraphState)
+    graph.add_node("guarded", gated_node(gate, guarded))
+    graph.add_node("blocked", lambda state: {})
+    graph.add_node("allowed", lambda state: {})
+    graph.add_edge(START, "guarded")
+    graph.add_conditional_edges("guarded", route_on_denial("blocked", "allowed"))
+    graph.add_edge("blocked", END)
+    graph.add_edge("allowed", END)
+    return graph.compile()
+
+
+async def test_sufficient_gamma_runs_node_and_routes_to_allowed():
+    result = await _build_graph().ainvoke({"gamma": 5.0})
+    assert result.get("ran_side_effect") is True
+    assert result.get("vsl_denial") is None
+
+
+async def test_insufficient_gamma_skips_node_and_routes_to_blocked():
+    result = await _build_graph().ainvoke({"gamma": 0.1})
+    assert result.get("ran_side_effect") is None
+    assert result.get("vsl_denial") is not None
+
+
+class InvariantState(TypedDict, total=False):
+    allowed: bool
+    ran_side_effect: bool
+    vsl_denial: Any
+
+
+async def _rule(candidate_input: InvariantState) -> bool:
+    return candidate_input["allowed"]
+
+
+def _build_invariant_graph():
+    invariant = Invariant(
+        name="integration-test-invariant",
+        description="Requires state['allowed'] to be True before the guarded node runs.",
+        rule=_rule,
+        assurance_basis=_ASSURANCE_BASIS,
+    )
+    gate = LangGraphAdapter().compile_invariant(invariant)
+
+    def guarded(state: InvariantState) -> dict:
+        return {"ran_side_effect": True}
+
+    graph = StateGraph(InvariantState)
+    graph.add_node("guarded", gated_node(gate, guarded))
+    graph.add_node("blocked", lambda state: {})
+    graph.add_node("allowed", lambda state: {})
+    graph.add_edge(START, "guarded")
+    graph.add_conditional_edges("guarded", route_on_denial("blocked", "allowed"))
+    graph.add_edge("blocked", END)
+    graph.add_edge("allowed", END)
+    return graph.compile()
+
+
+async def test_passing_invariant_runs_node_and_routes_to_allowed():
+    result = await _build_invariant_graph().ainvoke({"allowed": True})
+    assert result.get("ran_side_effect") is True
+    assert result.get("vsl_denial") is None
+
+
+async def test_violated_invariant_skips_node_and_routes_to_blocked():
+    result = await _build_invariant_graph().ainvoke({"allowed": False})
+    assert result.get("ran_side_effect") is None
+    denial = result.get("vsl_denial")
+    assert isinstance(denial, InvariantViolation)

vsl_langgraph-0.1.2/tests/test_purchase_approval_agent.py

@@ -0,0 +1,27 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "examples" / "financial-agents"))
+
+from purchase_approval_agent import build_agent  # noqa: E402
+
+
+async def test_high_confidence_under_cap_is_approved():
+    result = await build_agent().ainvoke({"amount": 250.0, "confidence": 5.0})
+    assert result.get("approved") is True
+    assert result.get("confidence_denial") is None
+    assert result.get("cap_denial") is None
+
+
+async def test_low_confidence_is_blocked_before_cap_check_runs():
+    result = await build_agent().ainvoke({"amount": 250.0, "confidence": 0.2})
+    assert result.get("approved") is None
+    assert result.get("confidence_denial") is not None
+    assert result.get("cap_denial") is None
+
+
+async def test_high_confidence_cannot_bypass_hard_cap():
+    result = await build_agent().ainvoke({"amount": 5000.0, "confidence": 5.0})
+    assert result.get("approved") is None
+    assert result.get("confidence_denial") is None
+    assert result.get("cap_denial") is not None