safentic 1.0.4__py3-none-any.whl → 1.0.5__py3-none-any.whl

safentic/__init__.py

@@ -1,8 +1,8 @@
-from .layer import SafetyLayer, SafenticError
-
-__all__ = [
-    "SafetyLayer",
-    "SafenticError",
-]
-
-__version__ = "1.0.4"
+from .layer import SafetyLayer, SafenticError
+
+__all__ = [
+    "SafetyLayer",
+    "SafenticError",
+]
+
+__version__ = "1.0.5"

safentic/engine.py

@@ -1,12 +1,16 @@
+import time
 from .policy import PolicyEngine
 from .logger.audit import AuditLogger
 
-class PolicyEnforcer():
+
+class PolicyEnforcer:
     """
     Runtime wrapper to evaluate and enforce tool usage policies.
-    Tracks agent-specific violations and supports audit logging.
+    Tracks agent-specific violations, supports audit logging, and handles TTL-based tool blocks.
     """
 
+    TOOL_BLOCK_TTL = 60  # seconds - how long a tool remains blocked after violation
+
     def __init__(self, policy_engine: PolicyEngine = None):
         self.policy_engine = policy_engine or PolicyEngine()
         self.agent_states = {}
@@ -18,44 +22,43 @@ class PolicyEnforcer():
         Returns a dict with 'allowed', 'reason', and agent state metadata.
         """
         state = self.agent_states.setdefault(agent_id, {
-            "blocked_tools": set(),
+            "blocked_tools": {},  # tool_name -> timestamp of block
             "violation_count": 0,
             "last_violation": None
         })
 
-        # Block repeat attempts to use already-denied tool
-        if tool_name in state["blocked_tools"]:
-            reason = "Tool previously blocked for this agent."
-            self.audit_logger.log(
-                agent_id=agent_id,
-                tool=tool_name,
-                allowed=False,
-                reason=reason
-            )
+        # Check if tool is still blocked
+        if self._is_tool_blocked(tool_name, state):
+            reason = "Tool is temporarily blocked due to a prior violation."
+            self.audit_logger.log(agent_id=agent_id, tool=tool_name, allowed=False, reason=reason)
             return self._deny(tool_name, state, reason)
 
-        # Run policy evaluation
+        # Evaluate policy
         violation = self.policy_engine.evaluate_policy(tool_name, tool_args)
 
         if violation:
-            state["blocked_tools"].add(tool_name)
+            # Example violation object: {"reason": "...", "level": "block"}
+            level = violation.get("level", "block")
+            reason = violation.get("reason", "Policy violation")
+
+            if level == "warn":
+                # Log a warning but allow the call
+                self.audit_logger.log(agent_id=agent_id, tool=tool_name, allowed=True, reason=f"Warning: {reason}")
+                return {
+                    "allowed": True,
+                    "reason": f"Warning: {reason}",
+                    "agent_state": state
+                }
+
+            # Otherwise: enforce block
+            state["blocked_tools"][tool_name] = time.time()
             state["violation_count"] += 1
             state["last_violation"] = violation
-            self.audit_logger.log(
-                agent_id=agent_id,
-                tool=tool_name,
-                allowed=False,
-                reason=violation
-            )
-            return self._deny(tool_name, state, violation)
-
-        # Log allowed action
-        self.audit_logger.log(
-            agent_id=agent_id,
-            tool=tool_name,
-            allowed=True
-        )
+            self.audit_logger.log(agent_id=agent_id, tool=tool_name, allowed=False, reason=reason)
+            return self._deny(tool_name, state, reason)
 
+        # Allow
+        self.audit_logger.log(agent_id=agent_id, tool=tool_name, allowed=True)
         return {
             "allowed": True,
             "reason": "Action permitted",
@@ -63,9 +66,7 @@ class PolicyEnforcer():
         }
 
     def reset(self, agent_id: str = None):
-        """
-        Clears violation state for one agent or all agents.
-        """
+        """Clears violation state for one or all agents."""
         if agent_id:
             self.agent_states.pop(agent_id, None)
         else:
@@ -78,3 +79,14 @@ class PolicyEnforcer():
             "tool": tool_name,
             "agent_state": state
         }
+
+    def _is_tool_blocked(self, tool_name: str, state: dict) -> bool:
+        """Checks if a tool is still blocked based on TTL."""
+        blocked_at = state["blocked_tools"].get(tool_name)
+        if not blocked_at:
+            return False
+        if time.time() - blocked_at > self.TOOL_BLOCK_TTL:
+            # Tool block expired
+            del state["blocked_tools"][tool_name]
+            return False
+        return True

safentic/layer.py

@@ -2,21 +2,33 @@ from .engine import PolicyEnforcer
 from .logger.audit import AuditLogger
 from .helper.auth import validate_api_key
 
+
 class SafenticError(Exception):
     """Raised when Safentic blocks an action."""
     pass
 
+
 class InvalidAPIKeyError(Exception):
     """Raised when an invalid API key is used."""
     pass
 
+
+class InvalidAgentInterfaceError(Exception):
+    """Raised when the wrapped agent does not implement the required method."""
+    pass
+
+
 class SafetyLayer:
     """
-    Safentic runtime enforcement wrapper for agent actions.
-    Requires a valid API key to function.
+    Wraps an agent with real-time enforcement of Safentic policies.
+    All tool calls must go through `call_tool()`.
+
+    Example:
+        agent = SafetyLayer(MyAgent(), api_key="...", agent_id="agent-001")
+        agent.call_tool("send_email", {"to": "alice@example.com"})
     """
 
-    def __init__(self, api_key: str = "", agent_id: str = "", enforcer: PolicyEnforcer = None, raise_on_block: bool = True):
+    def __init__(self, agent, api_key: str, agent_id: str = "", enforcer: PolicyEnforcer = None, raise_on_block: bool = True):
         if not api_key:
             raise InvalidAPIKeyError("Missing API key")
 
@@ -24,23 +36,24 @@ class SafetyLayer:
         if not validation_response or validation_response.get("status") != "valid":
             raise InvalidAPIKeyError("Invalid or unauthorized API key")
 
+        if not hasattr(agent, "call_tool") or not callable(getattr(agent, "call_tool")):
+            raise InvalidAgentInterfaceError("Wrapped agent must implement `call_tool(tool_name: str, **kwargs)`")
+
+        self.agent = agent
         self.api_key = api_key
         self.agent_id = agent_id
         self.raise_on_block = raise_on_block
         self.logger = AuditLogger()
-
         self.enforcer = enforcer or PolicyEnforcer()
         self.enforcer.reset(agent_id)
 
-    def protect(self, tool_name: str, tool_args: dict) -> dict:
+    def call_tool(self, tool_name: str, tool_args: dict) -> dict:
         """
-        Checks whether a tool action is allowed.
-        Raises SafenticError if blocked (default), or returns result if raise_on_block=False.
+        Intercepts a tool call and enforces policies before execution.
+        If blocked, raises `SafenticError` or returns an error response (configurable).
         """
-
         result = self.enforcer.enforce(self.agent_id, tool_name, tool_args)
 
-        # Log structured event
         self.logger.log(
             agent_id=self.agent_id,
             tool=tool_name,
@@ -51,6 +64,6 @@ class SafetyLayer:
         if not result["allowed"]:
             if self.raise_on_block:
                 raise SafenticError(result["reason"])
-            return result
+            return {"error": result["reason"]}
 
-        return result
+        return self.agent.call_tool(tool_name, **tool_args)

safentic/policy.py

@@ -1,14 +1,15 @@
 import os
 import yaml
-from typing import Optional
+from typing import Optional, Dict, Any, Union
 from .verifiers.sentence_verifier import SentenceTransformerVerifier
 from .logger.audit import AuditLogger
 
 
 class PolicyEngine:
     """
-    Evaluates whether a given tool action complies with safety policies.
-    Uses rule types such as deny_phrase and semantic checks.
+    Evaluates whether a tool action complies with safety policies.
+    Supports multiple rule types: deny_phrase, semantic.
+    Returns structured violations for downstream enforcement.
     """
 
     VALID_RULE_TYPES = {"deny_phrase", "semantic"}
@@ -37,10 +38,16 @@ class PolicyEngine:
         with open(path, encoding="utf-8") as f:
             return f.read().strip().lower()
 
-    def evaluate_policy(self, tool_name: str, args: dict, agent_id: str = "unknown") -> Optional[str]:
+    def evaluate_policy(
+        self,
+        tool_name: str,
+        args: Dict[str, Any],
+        agent_id: str = "unknown"
+    ) -> Optional[Dict[str, Union[str, Any]]]:
         """
-        Returns None if allowed, or a string reason if blocked.
-        Supports modular rule types per tool.
+        Returns:
+            None if allowed,
+            dict with 'reason' and 'level' if blocked or warned
         """
         tool_rules = self.policy_cfg.get("tools", {}).get(tool_name)
         if not tool_rules:
@@ -52,50 +59,39 @@ class PolicyEngine:
 
         for check in tool_rules.get("checks", []):
             rule_type = check.get("type")
+            level = check.get("level", "block")  # Default to block
 
             if rule_type not in self.VALID_RULE_TYPES:
-                warning = f"Unknown rule type in policy: '{rule_type}' for tool: '{tool_name}'"
-                self.audit_logger.log(
-                    agent_id=agent_id,
-                    tool=tool_name,
-                    allowed=True,
-                    reason=warning
-                )
+                warning = f"Unknown rule type: '{rule_type}' for tool: '{tool_name}'"
+                self.audit_logger.log(agent_id=agent_id, tool=tool_name, allowed=True, reason=warning)
                 continue
 
+            # ---- Phrase Matching ----
             if rule_type == "deny_phrase":
                 for phrase in check.get("phrases", []):
                     if phrase.lower() in text:
-                        reason = f"Blocked: matched deny phrase “{phrase}”"
-                        self.audit_logger.log(
-                            agent_id=agent_id,
-                            tool=tool_name,
-                            allowed=False,
-                            reason=reason
-                        )
-                        return reason
+                        reason = f"Matched deny phrase: “{phrase}”"
+                        self.audit_logger.log(agent_id=agent_id, tool=tool_name, allowed=(level == "warn"), reason=reason)
+                        return {"reason": reason, "level": level}
 
+            # ---- Semantic Check ----
             elif rule_type == "semantic":
                 trigger_phrases = [p.lower() for p in check.get("trigger_phrases", [])]
                 if any(p in text for p in trigger_phrases):
                     reference_file = check.get("reference_file")
                     if not reference_file:
-                        continue
+                        continue  # Skip if not configured
 
                     reference_text = self._load_reference_text(reference_file)
                     decision = self.verifier.decision(candidate=text, official=reference_text)
 
                     if decision == "block":
                         explanation = self.verifier.explain(candidate=text, official=reference_text)
-                        reason = f"Blocked by semantic check: {explanation}"
-                        self.audit_logger.log(
-                            agent_id=agent_id,
-                            tool=tool_name,
-                            allowed=False,
-                            reason=reason
-                        )
-                        return reason
+                        reason = f"Semantic block: {explanation}"
+                        self.audit_logger.log(agent_id=agent_id, tool=tool_name, allowed=(level == "warn"), reason=reason)
+                        return {"reason": reason, "level": level}
 
+                    # Log semantic pass
                     self.audit_logger.log(
                         agent_id=agent_id,
                         tool=tool_name,

{safentic-1.0.4.dist-info → safentic-1.0.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: safentic
-Version: 1.0.4
+Version: 1.0.5
 Summary: Safentic SDK for behavior analysis
 Home-page: https://safentic.com
 Author: Safentic

{safentic-1.0.4.dist-info → safentic-1.0.5.dist-info}/RECORD

@@ -1,9 +1,9 @@
 safentic/LICENSE.txt,sha256=xl3AZ2rkiOG5qE01SPRBgoW5Ib5YKZQeszh6OlvKePk,2330
-safentic/__init__.py,sha256=ZCchAM13KAYuwaA570PTLCuwP4956ov_oZVTOxKy99E,132
+safentic/__init__.py,sha256=RFKBKMmJGUZy436bF_wI0AAgiyWYJqeF3MIlhUi7_VU,124
 safentic/config.py,sha256=V6c8Fz0t-Ja278kjCrQMlGPBQ4Hj830t3q7U7oM4Q4k,90
-safentic/engine.py,sha256=-a90x70SY15WkOIkgxoPVLs_9xGsf4Krj-CmpoMs6tE,2597
-safentic/layer.py,sha256=hU6BTjvIbCSPLQrCnfEs2KKCR3JeOzIdWxCIlffk-5c,1876
-safentic/policy.py,sha256=ApAAAxiWb_M5TUTtYKk10BVWEy4xViSbM8ikocIqWoI,4111
+safentic/engine.py,sha256=Ho9-sHXnJuRUh0fsONLip8Dsf927EJK_8RwXDk4Mk-Q,3564
+safentic/layer.py,sha256=3sGVn7gGWoiStEKO3jTV4_2QxKUWEH1BiThR421GISo,2481
+safentic/policy.py,sha256=VKIxLfcJtwA3U7DVwefLWprKQCFbfya-RJZvU1n4sEc,4138
 safentic/helper/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 safentic/helper/auth.py,sha256=evhikKRTtGXYp0YKkdntBM4bUjdUTtvJ2nA5YLt2IIA,391
 safentic/logger/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -15,8 +15,8 @@ safentic/policies/policy.yaml,sha256=EoDjvloG56WGNjqNV18xytcCr2v4I0KG6uSx6_yTVAg
 safentic/verifiers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 safentic/verifiers/sentence_verifier.py,sha256=jgObZ1t4UCYHYIfNayI0n69hVBWOHc9GAhpJsDbiD2c,2376
 tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tests/test_all.py,sha256=oKq-vbo_THyoupx1r7aoNqIAb72rH2t9uyUJtpbDOyQ,5642
-safentic-1.0.4.dist-info/METADATA,sha256=rYcmXmYpFcFakpSGI9QSQkxhDvk2GH8vxkoCgKto590,1477
-safentic-1.0.4.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
-safentic-1.0.4.dist-info/top_level.txt,sha256=8bLyq7i9we7XEcbDYLHTUfR3IIpICeMfG8NWAHCLU5s,15
-safentic-1.0.4.dist-info/RECORD,,
+tests/test_all.py,sha256=makysLQtgKAFOfIutnvmBQcMLkMY3inkT6ig5h_I2e4,5878
+safentic-1.0.5.dist-info/METADATA,sha256=5S7U-KmaCPDVPcv_HsR7K6Px0inqySRxRr_fbqdxJv4,1477
+safentic-1.0.5.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+safentic-1.0.5.dist-info/top_level.txt,sha256=8bLyq7i9we7XEcbDYLHTUfR3IIpICeMfG8NWAHCLU5s,15
+safentic-1.0.5.dist-info/RECORD,,

tests/test_all.py

@@ -18,6 +18,10 @@ TESTS = {
     "generic_refund": "I’m sorry for the trouble—please let us know more about your refund issue.",
 }
 
+class MockAgent:
+    def call_tool(self, tool_name, **kwargs):
+        return {"status": "mock-success"}
+
 @pytest.fixture
 def policy_engine():
     return PolicyEngine()
@@ -33,8 +37,8 @@ def enforcer():
     ("made_up_timeframe", "24 hours"),
 ])
 def test_policy_engine_evaluate(policy_engine, case, expected_contains):
-    reason = policy_engine.evaluate_policy("send_email", {"body": TESTS[case]})
-    assert expected_contains in reason.lower()
+    violation = policy_engine.evaluate_policy("send_email", {"body": TESTS[case]})
+    assert violation and expected_contains in violation["reason"].lower()
 
 def test_policy_engine_skips_empty(policy_engine):
     assert policy_engine.evaluate_policy("send_email", {"body": ""}) is None
@@ -47,7 +51,7 @@ def test_policy_engine_unknown_rule_type(policy_engine):
 
 def test_policy_engine_malformed_semantic(policy_engine):
     policy_engine.policy_cfg = {
-        "tools": {"send_email": {"checks": [{"type": "semantic", "trigger_phrases": ["refund"]}]}}
+        "tools": {"send_email": {"checks": [{"type": "semantic", "trigger_phrases": ["refund"]}]}},
     }
     assert policy_engine.evaluate_policy("send_email", {"body": "refund policy applies"}) is None
 
@@ -56,25 +60,26 @@ def test_enforcer_blocks_expected_cases(enforcer):
     for case in ["valid_excerpt", "generic_refund"]:
         result = enforcer.enforce(agent_id, "send_email", {"body": TESTS[case]})
         assert not result["allowed"]
+        assert "reason" in result
 
 def test_enforcer_blocks_and_resets(enforcer):
     agent_id = "agent-reset"
     res = enforcer.enforce(agent_id, "send_email", {"body": TESTS["hallucination_one_device"]})
     assert not res["allowed"]
     repeat = enforcer.enforce(agent_id, "send_email", {"body": TESTS["hallucination_one_device"]})
-    assert "previously blocked" in repeat["reason"].lower()
+    assert "temporarily blocked" in repeat["reason"].lower()
     enforcer.reset(agent_id)
     assert agent_id not in enforcer.agent_states
 
 def test_safety_layer_blocks_and_raises():
-    layer = SafetyLayer(api_key="demo-1234", agent_id="safety-1", raise_on_block=True)
+    layer = SafetyLayer(agent=MockAgent(), api_key="demo-1234", agent_id="safety-1", raise_on_block=True)
     with pytest.raises(SafenticError):
-        layer.protect("send_email", {"body": TESTS["made_up_timeframe"]})
+        layer.call_tool("send_email", {"body": TESTS["made_up_timeframe"]})
 
 def test_safety_layer_returns_result():
     safe_input = {"body": "This is a neutral and policy-safe email message."}
-    layer = SafetyLayer(api_key="demo-1234", agent_id="safety-2", raise_on_block=False)
-    assert layer.protect("send_email", safe_input)["allowed"]
+    layer = SafetyLayer(agent=MockAgent(), api_key="demo-1234", agent_id="safety-2", raise_on_block=False)
+    assert layer.call_tool("send_email", safe_input)["status"] == "mock-success"
 
 @mock.patch("safentic.verifiers.sentence_verifier.SentenceTransformer")
 def test_similarity_score_consistency(mock_model_class):