vsl-maf 0.2.2__tar.gz

vsl_maf-0.2.2/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,215 @@
+# 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/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vsl-maf"
+version = "0.2.2"
+description = "Microsoft Agent Framework (agent-framework) 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).
+    # vsl_maf also checks the installed version on import (needs >= 0.2.0).
+    "super-semantics-vsl>=0.3,<0.4",
+    # Core only: the adapter needs FunctionMiddleware and MiddlewareFailure, not
+    # every model connector. Tested against 1.25.0.
+    "agent-framework-core>=1.25.0",
+]
+keywords = ["governance", "ai-safety", "guardrails", "agent-framework", "vsl", "verba", "microsoft-agent-framework"]
+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-Microsoft-agent-framework"
+Repository = "https://github.com/supersemantics/VSL-Microsoft-agent-framework"
+Changelog = "https://github.com/supersemantics/VSL-Microsoft-agent-framework/blob/HEAD/CHANGELOG.md"
+Issues = "https://github.com/supersemantics/VSL-Microsoft-agent-framework/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.23"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

vsl_maf-0.2.2/setup.cfg

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

vsl_maf-0.2.2/src/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",
+]