vsl-maf 0.2.2__py3-none-any.whl

vsl_maf/__init__.py

@@ -0,0 +1,23 @@
+import vsl_core as _vsl_core
+
+from .adapter import MAFAdapter
+from .integration import VSLFunctionMiddleware, VSLGateDenied, tool_arguments
+
+__version__ = "0.2.0"
+
+# Gate-decision records (VerbaLedger.write_gate_decision) and the 2026.10 Gamma
+# rule arrived in vsl-core 0.2.0; this package's docs and examples rely on both.
+_MIN_VSL_CORE = (0, 2, 0)
+_found = tuple(int(part) for part in _vsl_core.__version__.split(".")[:3])
+if _found < _MIN_VSL_CORE:
+    raise ImportError(
+        f"vsl-maf {__version__} needs vsl-core >= 0.2.0, found {_vsl_core.__version__}. "
+        "Upgrade: pip install --upgrade git+https://github.com/supersemantics/VSL-Core.git"
+    )
+
+__all__ = [
+    "MAFAdapter",
+    "VSLFunctionMiddleware",
+    "VSLGateDenied",
+    "tool_arguments",
+]

vsl_maf/adapter.py

@@ -0,0 +1,180 @@
+"""MAFAdapter: a VSLAdapter conformant with vsl-core's conformance contract,
+intended for use with the Microsoft Agent Framework (agent-framework).
+
+MAF's FunctionMiddleware provides a natural pre-commitment hook: a middleware's
+process() is called before any tool side effect fires. VSLFunctionMiddleware
+(see integration.py) uses that hook to call a compiled gate, preserving F1
+pre-commitment.
+
+What this package adds on top (see integration.py) is VSLFunctionMiddleware,
+a FunctionMiddleware subclass that calls a compiled gate before the tool runs
+and raises AutomationDeniedException on denial, so the caller can intercept it
+via a standard try/except around agent.run().
+
+This module is framework-agnostic -- it never imports agent_framework.
+The compiled gate it returns is the same async callable vsl-core's own
+PlainPythonReferenceAdapter produces. The only MAF-specific logic lives in
+integration.py (VSLFunctionMiddleware), not here.
+"""
+
+from __future__ import annotations
+
+import inspect
+import warnings
+from typing import Any, Callable
+
+from vsl_core.conformance.protocol import CompiledGate
+from vsl_core.constructs import Fallback, Invariant, PreNode
+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), plus one level of indirection through
+# whatever names it directly calls -- catching the common "the actual API
+# call lives in a helper module" shape. It can still miss deeper indirection
+# and cannot confirm a genuine FULL claim is correct either.
+_HOSTED_API_MARKERS = (
+    "openai",
+    "anthropic",
+    "google.genai",
+    "google.generativeai",
+    "cohere",
+    "mistralai",
+    # MAF's own hosted-model clients (FoundryChatClient, OpenAIChatClient,
+    # AzureOpenAIChatClient, ...) and Azure AI inference: a monitor that asks
+    # another agent or a chat client to judge is a hosted-model call too.
+    "chatclient",
+    "azure.ai.inference",
+)
+
+
+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. One level of indirection through directly-called
+    helpers is also checked (same logic as vsl-langgraph's adapter.py).
+    """
+    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 capitalises SDK class names (AsyncAnthropic,
+    # AsyncOpenAI), which a case-sensitive check against lowercase markers misses.
+    source_lower = source.lower()
+    if any(marker in source_lower for marker in _HOSTED_API_MARKERS):
+        return True
+
+    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 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 MAFAdapter:
+    """VSLAdapter for the Microsoft Agent Framework (agent-framework).
+
+    Compiles PreNode/Invariant into callable gates for use inside a
+    VSLFunctionMiddleware registered on an Agent instance (see integration.py),
+    or for direct inline calls before any guarded action runs.
+
+    This class never imports agent_framework -- the compiled gate is the same
+    framework-agnostic async callable vsl-core's own PlainPythonReferenceAdapter
+    produces. VSLFunctionMiddleware (integration.py) provides the MAF-specific
+    middleware hook.
+    """
+
+    def __init__(self, *, identity_key: str = "vsl-maf") -> None:
+        """`identity_key` is recorded on every denial this adapter's gates raise;
+        pass the agent's own identity so a denial says which agent it stopped."""
+        if not identity_key:
+            raise ValueError("identity_key must be a non-empty string.")
+        self.identity_key = identity_key
+
+    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 VSLFunctionMiddleware does not consume "
+                "Fallback -- a denial raises once, immediately, with no retry loop. "
+                "Implement retry behavior yourself around the compiled gate if needed.",
+                stacklevel=2,
+            )
+        _warn_if_full_claim_reaches_hosted_api(
+            f"PreNode '{pre_node.name}'", pre_node.assurance_basis, pre_node.monitor
+        )
+        identity_key = self.identity_key
+
+        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=identity_key,
+                )
+
+        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
+        )
+        identity_key = self.identity_key
+
+        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=identity_key,
+                    invariant_name=invariant.name,
+                    terminal_state_name=terminal_state_name,
+                )
+
+        return gate

vsl_maf/integration.py

@@ -0,0 +1,167 @@
+"""VSLFunctionMiddleware: MAF FunctionMiddleware that applies a compiled VSL gate
+before a tool (function) call runs.
+
+vsl-core does not intercept anything on its own: a compiled gate only ever
+raises or returns, on demand, when called. VSLFunctionMiddleware is that call
+site, made reusable for MAF's middleware mechanism. It calls the gate
+immediately before the tool would run, so the gate completes strictly before the
+guarded tool's side effect (F1 pre-commitment).
+
+How a denial reaches your code (agent-framework 1.x)
+----------------------------------------------------
+MAF's function-invocation loop converts an ordinary exception raised by function
+middleware into a tool-error result and keeps running: the tool does not run, but
+the model only sees "Error: Function failed.", may retry or carry on, and
+``agent.run()`` returns normally. For an enforcement layer that is fail-open at
+the level of the run. MAF's fail-closed signal is ``MiddlewareFailure``: never
+turned into a tool result, it cancels the current batch of tool calls and
+propagates to the caller of ``agent.run()`` (for streaming runs, when the stream
+is consumed).
+
+So by default (``on_denial="abort"``) a denial raises ``VSLGateDenied``, a
+``MiddlewareFailure`` that carries the original ``AutomationDeniedException`` (or
+``InvariantViolation``) as ``.denial`` and as ``__cause__``:
+
+    try:
+        result = await agent.run("Approve $5000")
+    except VSLGateDenied as denied:
+        print(denied.denial.reason)
+        if isinstance(denied.denial, InvariantViolation): ...
+
+``on_denial="return_to_model"`` keeps MAF's default instead: the denial becomes a
+tool-error result, the model is told the call failed and the run continues. The
+tool still never runs. Use it only when you want the model to explain or try
+another route, and remember that your code is then not told about the denial.
+
+If the gate itself fails (a monitor that raises something other than a denial),
+the middleware fails closed in "abort" mode too: ``MiddlewareFailure`` chained to
+the error, so the tool never runs unguarded.
+
+MAF FunctionMiddleware semantics used here:
+  - context.function.name  -- the tool being called
+  - context.arguments      -- the arguments, a Mapping or a pydantic model
+  - call_next()            -- continues to the next middleware or the tool;
+                              takes NO arguments in MAF.
+
+Ordering: register VSL middleware after any argument-repair middleware. MAF fails
+closed if arguments change after a security or policy middleware has seen them.
+
+`agent_framework` must be importable at runtime for registration on an Agent. The
+module still imports without it, so the gate logic can be unit tested alone.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Awaitable, Callable, Literal
+
+from vsl_core.conformance.protocol import CompiledGate
+from vsl_core.exceptions import AutomationDeniedException
+
+try:
+    from agent_framework import FunctionMiddleware as _FunctionMiddleware
+    from agent_framework import MiddlewareFailure as _MiddlewareFailure
+
+    _MIDDLEWARE_BASE: type = _FunctionMiddleware
+    _FAILURE_BASE: type = _MiddlewareFailure
+except ImportError:  # allow tests to import this module without agent-framework
+    _MIDDLEWARE_BASE = object  # type: ignore[assignment]
+
+    class _FallbackFailure(Exception):
+        """Stand-in for agent_framework.MiddlewareFailure when MAF is absent."""
+
+    _FAILURE_BASE = _FallbackFailure
+
+OnDenial = Literal["abort", "return_to_model"]
+_ON_DENIAL_VALUES = ("abort", "return_to_model")
+
+
+class VSLGateDenied(_FAILURE_BASE):  # type: ignore[misc, valid-type]
+    """A VSL gate denied a tool call and the run was aborted, fail-closed.
+
+    A ``MiddlewareFailure``, so MAF propagates it to the caller of ``agent.run()``
+    instead of handing the model a tool error. ``denial`` is the gate's own
+    ``AutomationDeniedException`` (or the more specific ``InvariantViolation``);
+    it is also the exception's ``__cause__``. ``function_name`` is the tool that
+    was not run.
+    """
+
+    def __init__(self, denial: AutomationDeniedException, function_name: str | None = None) -> None:
+        tool = f" '{function_name}'" if function_name else ""
+        super().__init__(f"VSL gate denied tool call{tool}: {denial}")
+        self.denial = denial
+        self.function_name = function_name
+
+
+def tool_arguments(context: Any) -> dict[str, Any]:
+    """The tool call's arguments as a plain dict, whether MAF passed a Mapping or
+    a pydantic model. The usual ``candidate_input_fn`` for argument-based gates."""
+    arguments = getattr(context, "arguments", None)
+    if arguments is None:
+        return {}
+    if isinstance(arguments, Mapping):
+        return dict(arguments)
+    model_dump = getattr(arguments, "model_dump", None)
+    if callable(model_dump):
+        return dict(model_dump())
+    raise TypeError(f"Unsupported tool-argument type {type(arguments).__name__}.")
+
+
+class VSLFunctionMiddleware(_MIDDLEWARE_BASE):  # type: ignore[misc]
+    """MAF FunctionMiddleware that applies a VSL gate before a tool runs.
+
+    On denial, ``call_next()`` is never called and the guarded tool never runs.
+    What the caller sees depends on ``on_denial`` (see the module docstring):
+    ``"abort"`` (default) raises ``VSLGateDenied`` out of ``agent.run()``;
+    ``"return_to_model"`` lets MAF hand the model a tool error.
+
+    ``candidate_input_fn`` extracts what the gate evaluates from the
+    ``FunctionInvocationContext``; it defaults to the whole context. For
+    argument-based gates use ``tool_arguments``.
+
+    ``function_name`` scopes the gate to one tool; other tools pass through.
+    None means every tool call this middleware receives is gated.
+    """
+
+    def __init__(
+        self,
+        gate: CompiledGate,
+        *,
+        candidate_input_fn: Callable[[Any], Any] | None = None,
+        function_name: str | None = None,
+        on_denial: OnDenial = "abort",
+    ) -> None:
+        if on_denial not in _ON_DENIAL_VALUES:
+            raise ValueError(f"on_denial must be one of {_ON_DENIAL_VALUES}, got {on_denial!r}.")
+        super().__init__()
+        self._gate = gate
+        self._extract = candidate_input_fn or (lambda ctx: ctx)
+        self._function_name = function_name
+        self._on_denial = on_denial
+
+    async def process(
+        self,
+        context: Any,
+        call_next: Callable[[], Awaitable[None]],
+    ) -> None:
+        """Gate the tool call. MAF invokes this before the tool runs."""
+        tool_name = getattr(getattr(context, "function", None), "name", None)
+        if self._function_name is not None and tool_name != self._function_name:
+            await call_next()
+            return
+
+        try:
+            await self._gate(self._extract(context))
+        except AutomationDeniedException as denial:
+            if self._on_denial == "abort":
+                raise VSLGateDenied(denial, tool_name) from denial
+            raise
+        except _FAILURE_BASE:
+            raise
+        except Exception as error:
+            if self._on_denial == "abort":
+                raise _FAILURE_BASE(f"VSL gate for '{tool_name}' failed; not running the tool unguarded") from error
+            raise
+
+        # Only reached if the gate returned normally (F1 pre-commitment).
+        await call_next()

vsl_maf-0.2.2.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: vsl-maf
+Version: 0.2.2
+Summary: Microsoft Agent Framework (agent-framework) 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-Microsoft-agent-framework
+Project-URL: Repository, https://github.com/supersemantics/VSL-Microsoft-agent-framework
+Project-URL: Changelog, https://github.com/supersemantics/VSL-Microsoft-agent-framework/blob/HEAD/CHANGELOG.md
+Project-URL: Issues, https://github.com/supersemantics/VSL-Microsoft-agent-framework/issues
+Keywords: governance,ai-safety,guardrails,agent-framework,vsl,verba,microsoft-agent-framework
+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: agent-framework-core>=1.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# vsl-maf
+
+A [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/overview/) (`agent-framework`) adapter for [vsl-core](https://github.com/supersemantics/VSL-Core): implements `vsl_core.conformance.protocol.VSLAdapter` and provides `VSLFunctionMiddleware`, a `FunctionMiddleware` subclass that gates every tool call an `Agent` makes before it fires.
+
+Requires vsl-core 0.2.0 or later and agent-framework-core 1.25 or later. Handover records (below) need vsl-core 0.3.0.
+
+Is:
+
+- A `VSLAdapter` implementation (`MAFAdapter`) that passes `vsl_core.conformance.suite.run_conformance_suite` with an empty result.
+- `VSLFunctionMiddleware`, which calls a compiled gate inside `process()` before `call_next()`, so the gate completes strictly before the guarded tool's side effect (F1 pre-commitment), and makes a denial abort the run fail-closed.
+
+Is not:
+
+- A replacement for `vsl-core`: the PreNode/Invariant/Fallback/TerminalState constructs, the ledger and the governance vocabulary all live there. This package only compiles and wires them into MAF.
+- Automatic interception. `VSLFunctionMiddleware` must be passed in the `middleware=[...]` list when creating an `Agent`.
+
+## Install
+
+```bash
+pip install vsl-maf
+```
+
+This installs vsl-core (`super-semantics-vsl`, imported as `vsl_core`) and `agent-framework-core`
+with it. From a local clone of this repo: `pip install -e .`
+
+Add the MAF connector for your model service as well, for example `agent-framework-foundry`.
+
+## Usage
+
+```python
+from typing import Annotated
+
+from agent_framework import Agent, tool
+from agent_framework.foundry import FoundryChatClient
+from azure.identity.aio import AzureCliCredential
+from pydantic import Field
+
+from vsl_core.constructs import PreNode
+from vsl_core.ledger import VerbaLedger
+from vsl_core.metrics import ROBUST_GAMMA_DEFAULT_THRESHOLD, AssuranceBasis, F2Modification, GammaEstimate
+from vsl_maf import MAFAdapter, VSLFunctionMiddleware, VSLGateDenied, tool_arguments
+
+REFUND_LIMIT = 500.0
+REFUND_GATE = "refund-within-policy"
+ledger = VerbaLedger()
+
+@tool(approval_mode="never_require")
+def issue_refund(amount: Annotated[float, Field(description="Refund amount")]) -> str:
+    return f"Refunded {amount}"
+
+async def refund_headroom(candidate) -> GammaEstimate:
+    amount = float(candidate.get("amount", 0.0))
+    # A ratio where 1.0 is break-even; 0.0 for a missing amount, so the gate fails closed.
+    estimate = GammaEstimate(gamma_hat=REFUND_LIMIT / amount if amount > 0 else 0.0)
+    ledger.write_gate_decision(
+        identity_key="refund-agent",
+        primitive_name=REFUND_GATE,
+        estimate=estimate,
+        gamma_threshold=ROBUST_GAMMA_DEFAULT_THRESHOLD,
+    )
+    return estimate
+
+gate = MAFAdapter(identity_key="refund-agent").compile_pre_node(PreNode(
+    name=REFUND_GATE,
+    description="Refunds must stay comfortably inside the policy limit.",
+    monitor=refund_headroom,
+    # No model at the guarded call: the gate only allows or blocks.
+    assurance_basis=AssuranceBasis(f1_pre_commitment=True, f2_modification=F2Modification.NONE),
+    gamma_threshold=ROBUST_GAMMA_DEFAULT_THRESHOLD,
+))
+
+async with Agent(
+    client=FoundryChatClient(project_endpoint="...", model="gpt-4o-mini", credential=AzureCliCredential()),
+    name="RefundAgent",
+    instructions="Use issue_refund to process refund requests.",
+    tools=issue_refund,
+    middleware=[VSLFunctionMiddleware(gate, candidate_input_fn=tool_arguments, function_name="issue_refund")],
+) as agent:
+    try:
+        result = await agent.run("Refund 900 to order 1234")
+    except VSLGateDenied as denied:
+        print(f"Refund denied before it ran: {denied.denial.reason}")
+```
+
+`compile_invariant` works the same way with an `Invariant`. Its denial carries the more specific `InvariantViolation` as `denied.denial`.
+
+## How a denial reaches your code
+
+MAF's function-invocation loop turns an ordinary exception from function middleware into a tool-error result and keeps running. The tool does not run, but the model is only told "Error: Function failed.", may retry or carry on, and `agent.run()` returns normally, so your code never learns about the denial. For a governance gate that is fail-open at the level of the run.
+
+So by default (`on_denial="abort"`) a denial raises `VSLGateDenied`, a subclass of MAF's `MiddlewareFailure`. MAF's documented fail-closed signal is never turned into a tool result: it cancels the current batch of tool calls and propagates to the caller of `agent.run()` (for streaming runs, when the stream is consumed). `denied.denial` is the gate's `AutomationDeniedException` or `InvariantViolation` (also the exception's `__cause__`), and `denied.function_name` is the tool that did not run.
+
+`on_denial="return_to_model"` keeps MAF's default: the model gets a tool error and the run continues. The tool still never runs. Use it only when you want the model to explain the refusal or take another route, knowing your code is not told.
+
+A gate that fails for another reason (a monitor raising `RuntimeError`, say) also aborts with `MiddlewareFailure` in `"abort"` mode, so the tool never runs unguarded.
+
+A caveat from MAF itself: when the model asks for several tools at once, an abort cancels the rest of the batch cooperatively. A synchronous tool body already running in a worker thread cannot be interrupted, though its result is discarded. Each gated tool's own gate still runs before that tool.
+
+## How it works in MAF
+
+MAF calls `process(context, call_next)` before every tool invocation:
+
+- `context.function.name`: the tool being called.
+- `context.arguments`: the arguments, as a mapping or a pydantic model. `tool_arguments(context)` returns a plain dict either way.
+- `call_next()`: continues to the next middleware or the tool. It takes no arguments.
+
+If the gate raises, `call_next()` is never reached and the tool never runs.
+
+Register VSL middleware after any argument-repair middleware: MAF fails closed if arguments change after a policy middleware has seen them.
+
+## Chaining multiple gates
+
+```python
+middleware=[
+    VSLFunctionMiddleware(cap_gate,    candidate_input_fn=tool_arguments, function_name="approve_purchase"),
+    VSLFunctionMiddleware(budget_gate, candidate_input_fn=tool_arguments, function_name="approve_purchase"),
+]
+```
+
+MAF runs middleware in registration order. If the first gate denies, the second gate and the tool never run.
+
+## Writing gate values honestly
+
+vsl-core never measures Gamma: your monitor computes `gamma_hat` and the gate only compares it, passing when it is strictly above `max(threshold, 1 + delta_estimation_error)` (vsl-core 0.2.0 rules, version `2026.10`).
+
+- Build it as a ratio where 1.0 is break-even: a limit divided by the requested amount, a judge's score divided by its break-even score.
+- Return `0.0` when the input is missing or unreadable, so the gate fails closed.
+- Never pass a raw 0–1 confidence, or a confidence the model supplies in the tool's own arguments.
+- Keep thresholds above 1.0 (`ROBUST_GAMMA_HIGH_STAKES_THRESHOLD`, 1.2, for payments, medical and legal actions). For a rule that must never be broken, use an `Invariant`.
+
+## `VSLFunctionMiddleware` doesn't consume `Fallback`
+
+A `PreNode`'s `Fallback` is policy data only here: on denial the middleware raises once, immediately, with no retry loop. `compile_pre_node` warns (`UserWarning`) if a `Fallback` is non-default, so this can't be silently assumed. vsl-core's own reference adapter doesn't consume `Fallback` either.
+
+## Recording decisions: the ledger doesn't write itself
+
+Nothing in this package writes to a `VerbaLedger`. That is the application's choice, and vsl-core's conformance contract forbids an adapter from making it. Record each gate's decision from inside its monitor or rule with `write_gate_decision()` (vsl-core 0.2.0), as in the usage example above:
+
+- For a PreNode, pass the monitor's `GammaEstimate` and the PreNode's `gamma_threshold`. `allowed` is then computed with the same check the gate makes, and a contradiction is refused.
+- For an Invariant, pass `allowed=holds`.
+- Pass a `decision_id` to group a decision's records.
+
+A denied gate's record flags drift, so follow it with the decision's next entry (`PRE_NODE`, then `VERIFICATION`, or `TERMINAL`) from your `except VSLGateDenied` block, as `examples/financial-agents/purchase_approval_agent.py` does. An agent with no ledger calls produces working gates and no audit trail, and this package won't warn you.
+
+`VerbaLedger` accepts any `LedgerStore`: `JsonlLedgerStore` for a local append-only file, or the optional immudb store in vsl-core.
+
+## Multi-agent workflows: handovers and Cluster Gamma
+
+MAF composes agents: one agent can call another as a tool (`agent.as_tool()`), or a workflow can hand a conversation from one agent to the next. Each agent's own gates can pass while the hand-off between them goes unchecked.
+
+With vsl-core 0.3.0, record the hand-off before the receiving agent acts, and have the receiver name it in its first gate decision:
+
+```python
+handover = ledger.write_handover(
+    identity_key="intake-agent",
+    to_identity_key="refund-agent",
+    decision_id=decision_id,
+    reason="customer asked for a refund",
+)
+# ...inside the refund agent's monitor:
+ledger.write_gate_decision(
+    identity_key="refund-agent",
+    primitive_name=REFUND_GATE,
+    estimate=estimate,
+    gamma_threshold=ROBUST_GAMMA_DEFAULT_THRESHOLD,
+    decision_id=decision_id,
+    caused_by=handover.entry_id,   # shows the receiver checked what it was handed
+)
+```
+
+When the sub-agent is called as a tool, the calling agent's `VSLFunctionMiddleware` sees that call like any other, so the same gating applies to the hand-off itself.
+
+Gating every tool call does not make the composed system safe. vsl-core's motivating example is the 2010 Flash Crash: every participant's Gamma was above 1, and the Cluster-level Gamma was still 0. If several agents coordinate on one outcome, declare them as a `vsl_core.cluster.Cluster` and pass its `cluster_key` on their records. The Cluster's `invariants` are plain `Invariant` objects, compiled and wired through `MAFAdapter`/`VSLFunctionMiddleware` like any other.
+
+## The F1/F2 assurance distinction
+
+Every `PreNode`/`Invariant` requires an `AssuranceBasis`. F2 is judged at the call the gate guards and is never earned by the gate itself:
+
+| Gate | F1 | F2 | Level |
+|---|---|---|---|
+| Amount cap or budget check before a tool (no model at the call) | True | `NONE` | LOW |
+| Gate before a hosted-model call whose system prompt the application writes | True | `PARTIAL` | MEDIUM |
+| Gate before a self-hosted model where the application steers logits or activations | True | `FULL` | HIGH |
+
+The level measures influence on the model, not enforcement: a LOW gate still blocks every tool call it denies. Report "blocks before the action: yes" separately rather than raising F2.
+
+The basis is self-declared, not verified. `MAFAdapter` carries one heuristic check: `compile_pre_node`/`compile_invariant` warn (`UserWarning`) when a monitor or rule claims `F2Modification.FULL` but its source appears to call a hosted model API (`openai`, `anthropic`, `google.genai`, `cohere`, `mistralai`, Azure AI inference, or a MAF chat client such as `FoundryChatClient`). A hosted, black-box call cannot modify the energy function, so the honest ceiling is `PARTIAL`. The check can miss indirect calls, and passing it doesn't confirm a `FULL` claim.
+
+## Sample agents
+
+`examples/financial-agents/purchase_approval_agent.py` chains an Invariant (hard cap) and a PreNode (budget headroom) on a real MAF `Agent` with `FoundryChatClient`, records every decision, and handles denials. It needs Azure/Foundry credentials; see `examples/README.md`.
+
+## Layout
+
+```
+src/vsl_maf/
+├── adapter.py      MAFAdapter (VSLAdapter conformance contract)
+└── integration.py  VSLFunctionMiddleware, VSLGateDenied, tool_arguments
+examples/
+└── financial-agents/purchase_approval_agent.py
+tests/
+├── test_conformance.py    run_conformance_suite(MAFAdapter()) == []
+├── test_integration.py    VSLFunctionMiddleware.process() against a mock context
+└── test_real_agent.py     a real MAF Agent with a scripted chat client (no credentials)
+```
+
+## Status
+
+Alpha. Conformance-suite green. Tested against agent-framework-core 1.25.0, including end-to-end runs through a real `Agent` and MAF's own function-invocation loop with a scripted chat client: allowed calls, denials aborting the run, `return_to_model`, Invariant denials and recorded gate decisions. The Foundry example has not been run against a live Foundry endpoint.
+
+See [CHANGELOG.md](https://github.com/supersemantics/VSL-Microsoft-agent-framework/blob/HEAD/CHANGELOG.md).
+
+## License
+
+MIT -- see LICENSE. Copyright Super Semantics.

vsl_maf-0.2.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+vsl_maf/__init__.py,sha256=sXn7q4yvedQeyfNvuAs32NaveXwOEznYaUGSAbJW384,769
+vsl_maf/adapter.py,sha256=1ktLeO19Yn7mJcHNzIfhJ-1a6NCSXCaO5Nqn36-Y14I,7778
+vsl_maf/integration.py,sha256=HOvfv51y7iz5PuPScXDPBcHMfVE5sj0NppsluwGLkXI,7361
+vsl_maf-0.2.2.dist-info/licenses/LICENSE,sha256=3bJgBD5-Y1rBZa2-Sp3pk9dOIhyZmkBpzahRKvYbylk,1067
+vsl_maf-0.2.2.dist-info/METADATA,sha256=CVZHWiHKTY7qxlfplYVvzItZ_mdBf0EeuBee0p4nsws,14025
+vsl_maf-0.2.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+vsl_maf-0.2.2.dist-info/top_level.txt,sha256=zEgqlofnqdOCwW-BaqTiJgesjAGGsvdMaOzbHexG_VM,8
+vsl_maf-0.2.2.dist-info/RECORD,,

vsl_maf-0.2.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_maf-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 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_maf-0.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+vsl_maf