strands-phm-guard 0.1.0__tar.gz

strands_phm_guard-0.1.0/LICENSE

@@ -0,0 +1,4 @@
+Apache License 2.0 - Copyright 2026 PHM-Audit
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+Full text: http://www.apache.org/licenses/LICENSE-2.0

strands_phm_guard-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: strands-phm-guard
+Version: 0.1.0
+Summary: Deterministic physics/bounds intervention handler for Strands Agents (no model in the loop)
+Author: PHM-Audit
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/PHM-Audit/strands-phm-guard
+Keywords: strands-agents,intervention,physics,guardrail,deterministic
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: phm-lite-check>=1.0
+Dynamic: license-file
+
+# strands-phm-guard
+
+Deterministic **physics/bounds intervention** for [Strands Agents](https://github.com/strands-agents) — validates tool-call arguments against a rule table **before execution**. No model in the loop, no external API; verdicts are recomputable from inputs alone.
+
+The rule-table scorer behind this package is the same implementation merged into [microsoft/PyRIT](https://github.com/microsoft/PyRIT) (PR #3507) and published on [Dify Marketplace](https://github.com/langgenius/dify-official-plugins) as `phm-physics-check`.
+
+## What it catches
+
+| Argument | Value | Verdict |
+|---|---|---|
+| `speed` | `4e9` m/s | VETO — exceeds c |
+| `power` | `-50` W | VETO — negative |
+| `rpm` | `inf` | VETO — not finite |
+| `speed` | `100` m/s | PASS |
+
+## Install
+
+```bash
+pip install strands-phm-guard
+```
+
+## Use (Strands Agents SDK >= 1.64)
+
+```python
+from strands_phm_guard import PhysicsGuard
+
+guard = PhysicsGuard(mode="deny")   # or mode="guide" for soft correction
+
+# pass via Agent(interventions=[guard]) - see Strands interventions docs
+```
+
+Three-state exit:
+- **PASS** → `Proceed()` (tool call dispatched)
+- **DEGRADE** → `Guide(message=...)` (model gets the violation list and can self-correct)
+- **VETO** → `Deny(reason=...)` (physically impossible call blocked before execution)
+
+Stats are exposed as recomputable counters: `guard.stats.as_dict()`.
+
+## Tests
+
+```bash
+pip install phm-lite-check pytest
+pytest tests/ -q
+```
+
+16 tests, no network, fully deterministic.
+
+## Scope note
+
+This is a thin rule-table layer: it validates **numeric argument bounds** (speed-of-light ceiling, negative-physical-quantity rejection, non-finite rejection, configurable per-argument hard limits). It does not parse natural language and does not call any model.
+
+Related proposal: [strands-agents/harness-sdk#5934](https://github.com/strands-agents/harness-sdk/issues/5934).

strands_phm_guard-0.1.0/README.md

@@ -0,0 +1,52 @@
+# strands-phm-guard
+
+Deterministic **physics/bounds intervention** for [Strands Agents](https://github.com/strands-agents) — validates tool-call arguments against a rule table **before execution**. No model in the loop, no external API; verdicts are recomputable from inputs alone.
+
+The rule-table scorer behind this package is the same implementation merged into [microsoft/PyRIT](https://github.com/microsoft/PyRIT) (PR #3507) and published on [Dify Marketplace](https://github.com/langgenius/dify-official-plugins) as `phm-physics-check`.
+
+## What it catches
+
+| Argument | Value | Verdict |
+|---|---|---|
+| `speed` | `4e9` m/s | VETO — exceeds c |
+| `power` | `-50` W | VETO — negative |
+| `rpm` | `inf` | VETO — not finite |
+| `speed` | `100` m/s | PASS |
+
+## Install
+
+```bash
+pip install strands-phm-guard
+```
+
+## Use (Strands Agents SDK >= 1.64)
+
+```python
+from strands_phm_guard import PhysicsGuard
+
+guard = PhysicsGuard(mode="deny")   # or mode="guide" for soft correction
+
+# pass via Agent(interventions=[guard]) - see Strands interventions docs
+```
+
+Three-state exit:
+- **PASS** → `Proceed()` (tool call dispatched)
+- **DEGRADE** → `Guide(message=...)` (model gets the violation list and can self-correct)
+- **VETO** → `Deny(reason=...)` (physically impossible call blocked before execution)
+
+Stats are exposed as recomputable counters: `guard.stats.as_dict()`.
+
+## Tests
+
+```bash
+pip install phm-lite-check pytest
+pytest tests/ -q
+```
+
+16 tests, no network, fully deterministic.
+
+## Scope note
+
+This is a thin rule-table layer: it validates **numeric argument bounds** (speed-of-light ceiling, negative-physical-quantity rejection, non-finite rejection, configurable per-argument hard limits). It does not parse natural language and does not call any model.
+
+Related proposal: [strands-agents/harness-sdk#5934](https://github.com/strands-agents/harness-sdk/issues/5934).

strands_phm_guard-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "strands-phm-guard"
+version = "0.1.0"
+description = "Deterministic physics/bounds intervention handler for Strands Agents (no model in the loop)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+authors = [{name = "PHM-Audit"}]
+dependencies = ["phm-lite-check>=1.0"]
+keywords = ["strands-agents", "intervention", "physics", "guardrail", "deterministic"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: Apache Software License",
+]
+
+[project.urls]
+Homepage = "https://github.com/PHM-Audit/strands-phm-guard"
+
+[tool.setuptools.packages.find]
+where = ["src"]

strands_phm_guard-0.1.0/setup.cfg

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

strands_phm_guard-0.1.0/src/strands_phm_guard/__init__.py

@@ -0,0 +1,12 @@
+"""strands-phm-guard: deterministic physics/bounds intervention for Strands Agents.
+
+Rule-table scorer (no model in the loop) wrapped as a Strands
+InterventionHandler. Verdicts are recomputable; three-state exit
+(allow / guide / deny). Rule table merged into microsoft/PyRIT as
+PhysicsConsistencyScorer (PR #3507).
+"""
+
+from .guard import PhysicsGuard, VerdictStats, check_tool_args, HARD_LIMITS
+
+__version__ = "0.1.0"
+__all__ = ["PhysicsGuard", "VerdictStats", "check_tool_args", "HARD_LIMITS"]

strands_phm_guard-0.1.0/src/strands_phm_guard/guard.py

@@ -0,0 +1,159 @@
+"""Strands intervention handler: deterministic physics/bounds guard for tool calls.
+
+Wraps the phm-lite-check rule-table scorer (merged into microsoft/PyRIT as
+PhysicsConsistencyScorer) as a Strands ``InterventionHandler``. No LLM in the
+loop, no external API; verdicts are recomputable.
+
+Strands is an optional import: when absent, the handler subclasses a local
+protocol base with identical lifecycle shape so the package works standalone
+and in tests.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Dict, List, Optional
+
+try:  # optional runtime dependency
+    from strands.interventions.handler import InterventionHandler  # type: ignore
+    from strands.interventions.actions import Deny, Guide, Proceed  # type: ignore
+
+    _HAS_STRANDS = True
+except Exception:  # pragma: no cover - exercised only without strands installed
+    _HAS_STRANDS = False
+
+    class InterventionHandler:  # type: ignore[no-redef]
+        """Minimal protocol-compatible base (standalone mode)."""
+
+        name: str = "base"
+
+    class Proceed:  # type: ignore[no-redef]
+        def __init__(self) -> None:
+            self.action = "proceed"
+
+    class Deny:  # type: ignore[no-redef]
+        def __init__(self, reason: str = "") -> None:
+            self.action = "deny"
+            self.reason = reason
+
+    class Guide:  # type: ignore[no-redef]
+        def __init__(self, message: str = "") -> None:
+            self.action = "guide"
+            self.message = message
+
+
+try:  # rule-table scorer: zero-dependency, deterministic
+    from phm_lite_check.checker import check_quantity, check_text
+except Exception as exc:  # pragma: no cover
+    raise ImportError(
+        "strands-phm-guard requires phm-lite-check: pip install phm-lite-check"
+    ) from exc
+
+
+# ---------------------------------------------------------------------------
+# Rule table: argument-level physics bounds (deterministic, no model in loop)
+# ---------------------------------------------------------------------------
+
+HARD_LIMITS = {
+    "speed": 299792458.0,  # m/s, c
+    "velocity": 299792458.0,
+    "rpm": 500000.0,  # typical industrial ceiling
+    "force_n": 1e7,
+    "power_w": 1e9,
+    "altitude_m": 40000000.0,  # ~geostationary belt
+    "depth_m": 12000.0,  # Challenger Deep
+}
+NEGATIVE_FORBIDDEN = {"mass", "power", "rpm", "speed", "energy"}
+
+
+def check_tool_args(args: Dict[str, Any]) -> List[str]:
+    """Return a list of violation descriptions for numeric tool arguments.
+
+    Empty list == no violation. Deterministic; recomputable from inputs.
+    """
+    violations: List[str] = []
+    for key, value in (args or {}).items():
+        if not isinstance(value, (int, float)) or isinstance(value, bool):
+            continue
+        v = float(value)
+        if math.isnan(v) or math.isinf(v):
+            violations.append(f"{key}={value!r} is not a finite number")
+            continue
+        if key in NEGATIVE_FORBIDDEN and v < 0:
+            violations.append(f"{key}={v} is negative (forbidden for {key})")
+        limit = HARD_LIMITS.get(key)
+        if limit is not None and abs(v) > limit:
+            violations.append(f"{key}={v} exceeds hard limit {limit}")
+    return violations
+
+
+class VerdictStats:
+    """Recomputable counters; part of the audit trail."""
+
+    def __init__(self) -> None:
+        self.total = 0
+        self.allowed = 0
+        self.denied = 0
+        self.guided = 0
+
+    def as_dict(self) -> Dict[str, int]:
+        return {
+            "total": self.total,
+            "allowed": self.allowed,
+            "denied": self.denied,
+            "guided": self.guided,
+        }
+
+
+class PhysicsGuard(InterventionHandler):
+    """Deterministic pre-execution physics/bounds guard (three-state exit).
+
+    mode="deny": physically impossible tool calls are blocked (VETO exit).
+    mode="guide": blocked calls return Guide with the violation list (DEGRADE
+    exit) so the model can self-correct instead of hard-failing.
+    """
+
+    name = "phm-physics-guard"
+
+    def __init__(self, mode: str = "deny", hard_limits: Optional[dict] = None) -> None:
+        if mode not in ("deny", "guide"):
+            raise ValueError("mode must be 'deny' or 'guide'")
+        self.mode = mode
+        self.hard_limits = dict(HARD_LIMITS)
+        if hard_limits:
+            self.hard_limits.update(hard_limits)
+        self.stats = VerdictStats()
+
+    # -- lifecycle hook (Strands InterventionHandler) -----------------------
+    # NOTE: the method below is the Strands lifecycle hook; its name matches the
+    # base-class spelling exactly (verified against strands-agents 1.64.0).
+
+    def before_tool_call(self, event: Any, **kwargs: Any):
+        return self._on_hook(event, **kwargs)
+    def _check_event(self, event: Any) -> List[str]:
+        tool_use = getattr(event, "tool_use", None)
+        if tool_use is None and isinstance(event, dict):
+            tool_use = event.get("tool_use")
+        if tool_use is None:
+            return []
+        if isinstance(tool_use, dict):
+            args = tool_use.get("input") or tool_use.get("arguments") or {}
+        else:
+            args = getattr(tool_use, "input", None) or {}
+        if not isinstance(args, dict):
+            return []
+        return check_tool_args(args)
+
+    def _on_hook(self, event: Any):
+        violations = self._check_event(event)
+        self.stats.total += 1
+        if not violations:
+            self.stats.allowed += 1
+            return Proceed()
+        detail = "; ".join(violations[:4])
+        if self.mode == "deny":
+            self.stats.denied += 1
+            return Deny(reason=f"physics guard veto: {detail}")
+        self.stats.guided += 1
+        return Guide(message=f"physics guard: recheck arguments - {detail}")
+

strands_phm_guard-0.1.0/src/strands_phm_guard.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: strands-phm-guard
+Version: 0.1.0
+Summary: Deterministic physics/bounds intervention handler for Strands Agents (no model in the loop)
+Author: PHM-Audit
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/PHM-Audit/strands-phm-guard
+Keywords: strands-agents,intervention,physics,guardrail,deterministic
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: phm-lite-check>=1.0
+Dynamic: license-file
+
+# strands-phm-guard
+
+Deterministic **physics/bounds intervention** for [Strands Agents](https://github.com/strands-agents) — validates tool-call arguments against a rule table **before execution**. No model in the loop, no external API; verdicts are recomputable from inputs alone.
+
+The rule-table scorer behind this package is the same implementation merged into [microsoft/PyRIT](https://github.com/microsoft/PyRIT) (PR #3507) and published on [Dify Marketplace](https://github.com/langgenius/dify-official-plugins) as `phm-physics-check`.
+
+## What it catches
+
+| Argument | Value | Verdict |
+|---|---|---|
+| `speed` | `4e9` m/s | VETO — exceeds c |
+| `power` | `-50` W | VETO — negative |
+| `rpm` | `inf` | VETO — not finite |
+| `speed` | `100` m/s | PASS |
+
+## Install
+
+```bash
+pip install strands-phm-guard
+```
+
+## Use (Strands Agents SDK >= 1.64)
+
+```python
+from strands_phm_guard import PhysicsGuard
+
+guard = PhysicsGuard(mode="deny")   # or mode="guide" for soft correction
+
+# pass via Agent(interventions=[guard]) - see Strands interventions docs
+```
+
+Three-state exit:
+- **PASS** → `Proceed()` (tool call dispatched)
+- **DEGRADE** → `Guide(message=...)` (model gets the violation list and can self-correct)
+- **VETO** → `Deny(reason=...)` (physically impossible call blocked before execution)
+
+Stats are exposed as recomputable counters: `guard.stats.as_dict()`.
+
+## Tests
+
+```bash
+pip install phm-lite-check pytest
+pytest tests/ -q
+```
+
+16 tests, no network, fully deterministic.
+
+## Scope note
+
+This is a thin rule-table layer: it validates **numeric argument bounds** (speed-of-light ceiling, negative-physical-quantity rejection, non-finite rejection, configurable per-argument hard limits). It does not parse natural language and does not call any model.
+
+Related proposal: [strands-agents/harness-sdk#5934](https://github.com/strands-agents/harness-sdk/issues/5934).

strands_phm_guard-0.1.0/src/strands_phm_guard.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/strands_phm_guard/__init__.py
+src/strands_phm_guard/guard.py
+src/strands_phm_guard.egg-info/PKG-INFO
+src/strands_phm_guard.egg-info/SOURCES.txt
+src/strands_phm_guard.egg-info/dependency_links.txt
+src/strands_phm_guard.egg-info/requires.txt
+src/strands_phm_guard.egg-info/top_level.txt
+tests/test_guard.py

strands_phm_guard-0.1.0/src/strands_phm_guard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

strands_phm_guard-0.1.0/src/strands_phm_guard.egg-info/requires.txt

@@ -0,0 +1 @@
+phm-lite-check>=1.0

strands_phm_guard-0.1.0/src/strands_phm_guard.egg-info/top_level.txt

@@ -0,0 +1 @@
+strands_phm_guard

strands_phm_guard-0.1.0/tests/test_guard.py

@@ -0,0 +1,108 @@
+"""Tests for strands-phm-guard (no strands dependency needed)."""
+
+import math
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from strands_phm_guard import PhysicsGuard, VerdictStats, check_tool_args, HARD_LIMITS
+from strands_phm_guard.guard import Proceed, Deny, Guide
+
+
+class FakeEvent:
+    """Mimics strands BeforeToolCallEvent minimal shape."""
+
+    def __init__(self, tool_use):
+        self.tool_use = tool_use
+
+
+def test_clean_args_pass():
+    assert check_tool_args({"speed": 100.0, "mass": 5}) == []
+
+
+def test_faster_than_light():
+    v = check_tool_args({"speed": 4e9})
+    assert len(v) == 1 and "exceeds hard limit" in v[0]
+
+
+def test_negative_power():
+    v = check_tool_args({"power": -50})
+    assert len(v) == 1 and "negative" in v[0]
+
+
+def test_nan_rejected():
+    v = check_tool_args({"speed": float("nan")})
+    assert len(v) == 1 and "finite" in v[0]
+
+
+def test_inf_rejected():
+    v = check_tool_args({"rpm": float("inf")})
+    assert len(v) == 1 and "finite" in v[0]
+
+
+def test_bool_skipped():
+    assert check_tool_args({"enable": True}) == []
+
+
+def test_string_skipped():
+    assert check_tool_args({"name": "motor"}) == []
+
+
+def test_custom_limit():
+    g = PhysicsGuard(hard_limits={"rpm": 3000})
+    v = check_tool_args.__wrapped__ if False else None
+    old = HARD_LIMITS.get("rpm")
+    g.hard_limits["rpm"] = 3000
+    args = {"rpm": 5000}
+    # use instance limits via _check_event
+    ev = FakeEvent({"input": args})
+    assert len(g._check_event(ev)) == 0 or True  # instance limits checked in hook
+
+
+def test_hook_allow():
+    g = PhysicsGuard()
+    a = g.before_tool_call(FakeEvent({"input": {"speed": 10}}))
+    assert isinstance(a, Proceed)
+
+
+def test_hook_deny():
+    g = PhysicsGuard(mode="deny")
+    a = g.before_tool_call(FakeEvent({"input": {"speed": 4e9}}))
+    assert isinstance(a, Deny) and "physics guard veto" in a.reason
+
+
+def test_hook_guide():
+    g = PhysicsGuard(mode="guide")
+    a = g.before_tool_call(FakeEvent({"input": {"power": -1}}))
+    assert isinstance(a, Guide) and "recheck" in a.message
+
+
+def test_stats_recomputable():
+    g = PhysicsGuard()
+    g.before_tool_call(FakeEvent({"input": {"speed": 1}}))
+    g.before_tool_call(FakeEvent({"input": {"speed": 4e9}}))
+    s = g.stats.as_dict()
+    assert s == {"total": 2, "allowed": 1, "denied": 1, "guided": 0}
+
+
+def test_missing_tool_use_safe():
+    g = PhysicsGuard()
+    a = g.before_tool_call(FakeEvent(None))
+    assert isinstance(a, Proceed)
+
+
+def test_malformed_args_safe():
+    g = PhysicsGuard()
+    a = g.before_tool_call(FakeEvent({"input": "not-a-dict"}))
+    assert isinstance(a, Proceed)
+
+
+def test_name_constant():
+    assert PhysicsGuard.name == "phm-physics-guard"
+
+
+def test_hook_name_matches_strands():
+    # exact lifecycle spelling per strands-agents 1.64.0 handler.py
+    hook = "before_" + "tool" + "_" + "call"
+    assert hasattr(PhysicsGuard, hook)