safentic 1.0.4__tar.gz → 1.0.5__tar.gz

{safentic-1.0.4/safentic.egg-info → safentic-1.0.5}/PKG-INFO

@@ -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 → safentic-1.0.5}/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-1.0.5/safentic/engine.py

@@ -0,0 +1,92 @@
+import time
+from .policy import PolicyEngine
+from .logger.audit import AuditLogger
+
+
+class PolicyEnforcer:
+    """
+    Runtime wrapper to evaluate and enforce tool usage policies.
+    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 = {}
+        self.audit_logger = AuditLogger()
+
+    def enforce(self, agent_id: str, tool_name: str, tool_args: dict) -> dict:
+        """
+        Evaluates a tool action for a given agent.
+        Returns a dict with 'allowed', 'reason', and agent state metadata.
+        """
+        state = self.agent_states.setdefault(agent_id, {
+            "blocked_tools": {},  # tool_name -> timestamp of block
+            "violation_count": 0,
+            "last_violation": None
+        })
+
+        # 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)
+
+        # Evaluate policy
+        violation = self.policy_engine.evaluate_policy(tool_name, tool_args)
+
+        if violation:
+            # 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=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",
+            "agent_state": state
+        }
+
+    def reset(self, agent_id: str = None):
+        """Clears violation state for one or all agents."""
+        if agent_id:
+            self.agent_states.pop(agent_id, None)
+        else:
+            self.agent_states.clear()
+
+    def _deny(self, tool_name: str, state: dict, reason: str) -> dict:
+        return {
+            "allowed": False,
+            "reason": reason,
+            "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-1.0.4 → safentic-1.0.5}/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-1.0.4 → safentic-1.0.5}/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 → safentic-1.0.5/safentic.egg-info}/PKG-INFO

@@ -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 → safentic-1.0.5}/setup.py

@@ -1,27 +1,27 @@
-from setuptools import setup, find_packages
-
-setup(
-    name="safentic",
-    version="1.0.4",
-    packages=find_packages(),
-    install_requires=[
-        "requests",
-        "PyYAML",
-        "sentence-transformers==3.2.1",
-        "sqlalchemy",
-        "python-dotenv"
-        ],
-    include_package_data=True,
-    license="Proprietary :: Safentic Commercial License",  # Custom classifier
-    classifiers=[
-        "Programming Language :: Python :: 3",
-        "License :: Other/Proprietary License",  # Indicates not open source
-        "Operating System :: OS Independent",
-    ],
-    author="Safentic",
-    author_email="contact@safentic.com",
-    description="Safentic SDK for behavior analysis",
-    long_description=open("README.md").read(),
-    long_description_content_type="text/markdown",
-    url="https://safentic.com",
-)
+from setuptools import setup, find_packages
+
+setup(
+    name="safentic",
+    version="1.0.5",
+    packages=find_packages(),
+    install_requires=[
+        "requests",
+        "PyYAML",
+        "sentence-transformers==3.2.1",
+        "sqlalchemy",
+        "python-dotenv"
+        ],
+    include_package_data=True,
+    license="Proprietary :: Safentic Commercial License",  # Custom classifier
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: Other/Proprietary License",  # Indicates not open source
+        "Operating System :: OS Independent",
+    ],
+    author="Safentic",
+    author_email="contact@safentic.com",
+    description="Safentic SDK for behavior analysis",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    url="https://safentic.com",
+)

safentic-1.0.4/safentic/engine.py

@@ -1,80 +0,0 @@
-from .policy import PolicyEngine
-from .logger.audit import AuditLogger
-
-class PolicyEnforcer():
-    """
-    Runtime wrapper to evaluate and enforce tool usage policies.
-    Tracks agent-specific violations and supports audit logging.
-    """
-
-    def __init__(self, policy_engine: PolicyEngine = None):
-        self.policy_engine = policy_engine or PolicyEngine()
-        self.agent_states = {}
-        self.audit_logger = AuditLogger()
-
-    def enforce(self, agent_id: str, tool_name: str, tool_args: dict) -> dict:
-        """
-        Evaluates a tool action for a given agent.
-        Returns a dict with 'allowed', 'reason', and agent state metadata.
-        """
-        state = self.agent_states.setdefault(agent_id, {
-            "blocked_tools": set(),
-            "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
-            )
-            return self._deny(tool_name, state, reason)
-
-        # Run policy evaluation
-        violation = self.policy_engine.evaluate_policy(tool_name, tool_args)
-
-        if violation:
-            state["blocked_tools"].add(tool_name)
-            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
-        )
-
-        return {
-            "allowed": True,
-            "reason": "Action permitted",
-            "agent_state": state
-        }
-
-    def reset(self, agent_id: str = None):
-        """
-        Clears violation state for one agent or all agents.
-        """
-        if agent_id:
-            self.agent_states.pop(agent_id, None)
-        else:
-            self.agent_states.clear()
-
-    def _deny(self, tool_name: str, state: dict, reason: str) -> dict:
-        return {
-            "allowed": False,
-            "reason": reason,
-            "tool": tool_name,
-            "agent_state": state
-        }