vsl-langgraph 0.1.2__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+vsl_langgraph/__init__.py,sha256=yZ_PZxJSysMUqYbpZLC8cfaHdSYeDDVn9szl_WZMhSg,217
+vsl_langgraph/adapter.py,sha256=gDA7-0-K8-SEd1YobXp9i5vWk5BGl40exgW7nd3aPzA,7693
+vsl_langgraph/integration.py,sha256=WV4q7K_S-drQIUBj0ENRLzZ7aU65eLT1MsqkjxuXc9w,3039
+vsl_langgraph-0.1.2.dist-info/licenses/LICENSE,sha256=k_93isT77tF7gkFv2yNPM8ESgDazhABxVak4K5tmjs8,1072
+vsl_langgraph-0.1.2.dist-info/METADATA,sha256=S26ZECgStbGxsm0hxVGdKfmeQPVGfrCzsaG222e8Nog,9908
+vsl_langgraph-0.1.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+vsl_langgraph-0.1.2.dist-info/top_level.txt,sha256=GV5y6GC7WXksM-U9ra8Uxh3DNakGy_O_HFXnGmhlQhs,14
+vsl_langgraph-0.1.2.dist-info/RECORD,,

vsl_langgraph-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vsl_langgraph-0.1.2.dist-info/licenses/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.dist-info/top_level.txt

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