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

safentic/helper/helper.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from typing import Any, Dict, Iterable, List, Optional, Union
+
+import requests
+from ..config import BASE_API_PATH, API_KEY_ENDPOINT
+
+from .._internal.errors import PolicyValidationError, ReferenceFileError, VerifierError
+
+
+def validate_api_key(key: str) -> Dict[str, Any]:
+    try:
+        response = requests.post(
+            BASE_API_PATH + API_KEY_ENDPOINT, json={"api_key": key}
+        )
+        if response.status_code != 200:
+            return {"valid": False}
+        data = response.json()
+        # Ensure dict shape for mypy; if backend returns non-dict, coerce to wrapped data
+        if not isinstance(data, dict):
+            return {"valid": True, "data": data}
+        # Merge as before
+        out: Dict[str, Any] = {"valid": True}
+        out.update(data)
+        return out
+    except Exception:
+        return {"valid": False}
+
+
+def require(rule: Dict[str, Any], rid: str, key: str) -> None:
+    """Ensure a rule has a required key, else raise PolicyValidationError."""
+    if not rule.get(key):
+        raise PolicyValidationError(f"{rid}: missing required '{key}'")
+
+
+def get_text_fields(
+    tool_input: Dict[str, Any],
+    fields: List[str],
+    rid: str,
+    logger: Optional[Any] = None,
+) -> str:
+    """Extract text fields from tool input, log missing ones if logger provided."""
+    texts: List[str] = []
+    missing: List[str] = []
+    for f in fields:
+        val = tool_input.get(f)
+        if isinstance(val, str):
+            texts.append(val)
+        else:
+            missing.append(f)
+
+    if missing and logger is not None:
+        # keep original call signature; annotate logger as Any
+        logger.log(
+            agent_id="-",
+            tool="-schema-",
+            allowed=True,
+            reason=f"Missing expected fields for {rid}: {missing}",
+            extra={"event": "missing_fields", "rule": rid, "missing": missing},
+        )
+    return "\n".join(texts).strip()
+
+
+def deny_response(
+    tool_name: str,
+    state: Dict[str, Any],
+    reason: str,
+    violation: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Return a standard structured deny response."""
+    return {
+        "allowed": False,
+        "reason": reason,
+        "tool": tool_name,
+        "agent_state": state,
+        "violation": violation or {},
+    }
+
+
+def is_tool_blocked(tool_name: str, state: Dict[str, Any], ttl: int) -> bool:
+    """Check if a tool is still blocked based on TTL. Cleans up expired entries."""
+    # Expect state["blocked_tools"] to be a dict[str, float]
+    blocked_tools = state.get("blocked_tools")
+    if not isinstance(blocked_tools, dict):
+        return False
+    blocked_at = blocked_tools.get(tool_name)
+    if not isinstance(blocked_at, (int, float)):
+        return False
+    if time.time() - float(blocked_at) > ttl:
+        # TTL expired → unblock
+        try:
+            del blocked_tools[tool_name]
+        except Exception:
+            pass
+        return False
+    return True
+
+
+def max_tokens_for_format(fmt: str) -> int:
+    """Return max tokens allowed for given response format."""
+    if fmt == "boolean":
+        return 5
+    elif fmt == "string":
+        return 50
+    elif fmt == "json":
+        return 80
+    return 40  # default fallback
+
+
+def check_match(llm_output: str, trigger: str, mode: str) -> bool:
+    """
+    Determines if the LLM output matches the trigger value.
+    Supports: exact, regex, jsonpath.
+    """
+    try:
+        if mode == "exact":
+            return llm_output.strip().lower() == trigger.strip().lower()
+        elif mode == "regex":
+            return re.search(trigger, llm_output, re.IGNORECASE) is not None
+        elif mode == "jsonpath":
+            from jsonpath_ng.ext import parse
+
+            parsed = parse(trigger).find(json.loads(llm_output))
+            return bool(parsed)
+    except Exception as e:
+        raise VerifierError(f"Failed during match check: {e}") from e
+
+    return False  # unsupported mode
+
+
+class ReferenceLoader:
+    """
+    Minimal, predictable reference file resolver with mtime caching.
+
+    Resolution order for a given 'filename':
+      1) absolute path -> use as-is
+      2) policy_dir / filename
+      3) SAFENTIC_REF_BASE / filename   (optional single base for monorepos/CI)
+
+    This keeps v1 simple and transparent. You can extend later if needed.
+    """
+
+    def __init__(self, reference_dir: str):
+        # Treat this as the policy directory (directory of policy.yaml)
+        self.reference_dir: str = os.path.abspath(reference_dir)
+        base_env = os.getenv("SAFENTIC_REF_BASE")  # optional single base
+        self.ref_base_env: Optional[str] = (
+            os.path.abspath(os.path.expanduser(base_env)) if base_env else None
+        )
+
+        # mtime cache keyed by absolute path
+        self._ref_cache: Dict[str, Dict[str, Union[float, str]]] = {}
+
+    # --------------- public API ---------------
+
+    def load(self, filename: str) -> str:
+        """
+        Resolve and load the reference file, caching by mtime.
+        Raises ReferenceFileError with attempted paths when not found or unreadable/empty.
+        """
+        candidates = list(self._candidate_paths(filename))
+
+        resolved = next((p for p in candidates if os.path.isfile(p)), None)
+        if not resolved:
+            details: Dict[str, Any] = {
+                "requested": filename,
+                "attempted": candidates,
+                "hint": "Use a path relative to your policy file, or set SAFENTIC_REF_BASE to a directory that contains your reference docs.",
+            }
+            raise ReferenceFileError(
+                f"Reference file not found: {filename}. Details: {details}"
+            )
+
+        mtime = os.path.getmtime(resolved)
+        cached = self._ref_cache.get(resolved)
+        if cached and cached.get("mtime") == mtime:
+            # cached["text"] is a str by construction; help mypy with a cast
+            return str(cached.get("text"))
+
+        try:
+            with open(resolved, "r", encoding="utf-8") as f:
+                text = f.read()
+        except Exception as e:
+            raise ReferenceFileError(f"Failed to read reference file {resolved}: {e}")
+
+        if not text.strip():
+            raise ReferenceFileError(f"Reference file is empty: {resolved}")
+
+        self._ref_cache[resolved] = {"mtime": mtime, "text": text}
+        return text
+
+    def clear_cache(self) -> None:
+        self._ref_cache.clear()
+
+    # --------------- internals ---------------
+
+    def _candidate_paths(self, filename: str) -> Iterable[str]:
+        # 1) absolute path
+        if os.path.isabs(filename):
+            yield os.path.abspath(os.path.expanduser(filename))
+            return
+
+        # 2) policy_dir / filename
+        yield os.path.abspath(os.path.join(self.reference_dir, filename))
+
+        # 3) SAFENTIC_REF_BASE / filename (optional)
+        if self.ref_base_env:
+            yield os.path.abspath(os.path.join(self.ref_base_env, filename))

safentic/layer.py

@@ -1,69 +1,96 @@
-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:
-    """
-    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, agent, api_key: str, agent_id: str = "", enforcer: PolicyEnforcer = None, raise_on_block: bool = True):
-        if not api_key:
-            raise InvalidAPIKeyError("Missing API key")
-
-        validation_response = validate_api_key(api_key)
-        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 call_tool(self, tool_name: str, tool_args: dict) -> dict:
-        """
-        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)
-
-        self.logger.log(
-            agent_id=self.agent_id,
-            tool=tool_name,
-            allowed=result["allowed"],
-            reason=result["reason"] if not result["allowed"] else None
-        )
-
-        if not result["allowed"]:
-            if self.raise_on_block:
-                raise SafenticError(result["reason"])
-            return {"error": result["reason"]}
-
-        return self.agent.call_tool(tool_name, **tool_args)
+from typing import Any, Protocol
+import os
+from dotenv import load_dotenv
+
+from .policy_enforcer import PolicyEnforcer
+from .logger.audit import AuditLogger
+from .helper.helper import validate_api_key
+from .policy_engine import PolicyEngine
+from ._internal.errors import (
+    SafenticError,
+    InvalidAPIKeyError,
+    InvalidAgentInterfaceError,
+)
+
+load_dotenv()
+
+
+class AgentProtocol(Protocol):
+    """Minimal interface expected from a wrapped agent."""
+
+    def call_tool(self, tool_name: str, **kwargs: Any) -> dict[str, Any]: ...
+
+
+class SafetyLayer:
+    """
+    Developer-facing wrapper that enforces Safentic policies around an agent.
+    All tool calls must go through `call_tool()`.
+    """
+
+    def __init__(
+        self,
+        agent: AgentProtocol,
+        api_key: str,
+        agent_id: str = "",
+        raise_on_block: bool = True,
+    ) -> None:
+        if not api_key:
+            raise InvalidAPIKeyError("Missing API key")
+
+        validation_response = validate_api_key(api_key)
+        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: AgentProtocol = agent
+        self.api_key: str = api_key
+        self.agent_id: str = agent_id
+        self.raise_on_block: bool = raise_on_block
+        self.logger: AuditLogger = AuditLogger()
+
+        # Decide where policy.yaml lives (env var > default repo path)
+        policy_path = os.getenv(
+            "SAFENTIC_POLICY_PATH",
+            os.path.join(
+                os.path.dirname(__file__), "..", "policy_file_docs", "policy.yaml"
+            ),
+        )
+
+        # Build engine and inject API key to verifier
+        engine = PolicyEngine(policy_path=policy_path)
+        engine.llm.set_api_key(api_key)
+
+        # Strict enforcer injection
+        self.enforcer = PolicyEnforcer(policy_engine=engine)
+        self.enforcer.reset(agent_id)
+
+    def call_tool(self, tool_name: str, tool_args: dict[str, Any]) -> dict[str, Any]:
+        """
+        Intercepts a tool call and enforces policies before execution.
+        If blocked, raises `SafenticError` or returns an error response (configurable).
+        """
+        result: dict[str, Any] = self.enforcer.enforce(
+            self.agent_id, tool_name, tool_args
+        )
+
+        self.logger.log(
+            agent_id=self.agent_id,
+            tool=tool_name,
+            allowed=result["allowed"],
+            reason=result["reason"] if not result["allowed"] else None,
+        )
+
+        if not result["allowed"]:
+            if self.raise_on_block:
+                raise SafenticError(result["reason"])
+            return {
+                "error": result["reason"],
+                "tool": tool_name,
+                "violation": result.get("violation"),
+            }
+
+        return self.agent.call_tool(tool_name, **tool_args)

safentic/logger/audit.py

@@ -1,83 +1,181 @@
-import logging
-from datetime import datetime
-import os
-import json
-
-class AuditLogger:
-    def __init__(self, config: dict = None):
-        config = config or {}
-
-        # Allow disabling via config or env
-        self.enabled = config.get("enabled", True)
-        if os.getenv("SAFE_AUDIT_LOG") == "0":
-            self.enabled = False
-
-        # File paths from config or default
-        self.txt_log_path = config.get("destination", "safentic/logs/txt_logs/safentic_audit.log")
-        self.jsonl_path = config.get("jsonl", "safentic/logs/json_logs/safentic_audit.jsonl")
-
-        # Ensure directories exist
-        os.makedirs(os.path.dirname(self.txt_log_path), exist_ok=True)
-        os.makedirs(os.path.dirname(self.jsonl_path), exist_ok=True)
-
-        # Set up logger
-        self.logger = logging.getLogger("safentic.audit")
-
-        level_str = config.get("level", "INFO").upper()
-        level_map = {
-            "DEBUG": logging.DEBUG,
-            "INFO": logging.INFO,
-            "WARNING": logging.WARNING,
-            "ERROR": logging.ERROR,
-            "CRITICAL": logging.CRITICAL
-        }
-        level = level_map.get(level_str, logging.INFO)
-        self.logger.setLevel(level)
-
-        # Prevent duplicate handlers (e.g., in notebooks)
-        if not self.logger.handlers:
-            formatter = logging.Formatter("%(asctime)s | %(levelname)s | %(message)s")
-
-            stream_handler = logging.StreamHandler()
-            stream_handler.setFormatter(formatter)
-            self.logger.addHandler(stream_handler)
-
-            file_handler = logging.FileHandler(self.txt_log_path)
-            file_handler.setFormatter(formatter)
-            self.logger.addHandler(file_handler)
-
-    def log(self, agent_id: str, tool: str, allowed: bool, reason: str = None):
-        if not self.enabled:
-            return
-
-        entry = {
-            "timestamp": datetime.now().isoformat(),
-            "agent_id": agent_id,
-            "tool": tool,
-            "allowed": allowed,
-            "reason": reason or "No violation"
-        }
-
-        log_level = logging.INFO if allowed else logging.WARNING
-        self.logger.log(log_level, f"[AUDIT] {entry}")
-
-        try:
-            with open(self.jsonl_path, "a", encoding="utf-8") as f:
-                f.write(json.dumps(entry) + "\n")
-        except Exception as e:
-            self.logger.error(f"Failed to write structured audit log: {e}")
-
-    def set_level(self, level: str):
-        level_map = {
-            "DEBUG": logging.DEBUG,
-            "INFO": logging.INFO,
-            "WARNING": logging.WARNING,
-            "ERROR": logging.ERROR,
-            "CRITICAL": logging.CRITICAL
-        }
-
-        level = level.upper()
-        if level in level_map:
-            self.logger.setLevel(level_map[level])
-        else:
-            raise ValueError(f"Unsupported log level: {level}")
+from __future__ import annotations
+
+import json
+import logging
+import os
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+
+class AuditLogger:
+    def __init__(self, config: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Minimal, flexible audit logger with text + JSONL outputs.
+
+        Precedence rules
+        ----------------
+        Enabled:
+          1) config["enabled"] (bool)
+          2) SAFENTIC_AUDIT_ENABLED env (truthy/falsey; "0","false","no" disable)
+          3) SAFE_AUDIT_LOG env ("0" disables; legacy)
+          4) default: True
+
+        Paths:
+          Text log (human-readable):
+            1) config["destination"]
+            2) SAFENTIC_LOG_PATH env (or SAFE_LOG_PATH legacy)
+            3) default: safentic/logs/txt_logs/safentic_audit.log
+
+          JSONL log (structured):
+            1) config["jsonl"]
+            2) SAFENTIC_JSON_LOG_PATH env (or SAFE_JSON_LOG_PATH legacy)
+            3) default: safentic/logs/json_logs/safentic_audit.jsonl
+
+        Level:
+          1) config["level"]
+          2) SAFENTIC_LOG_LEVEL env
+          3) default: INFO
+        """
+        cfg: Dict[str, Any] = config or {}
+
+        # --------------------
+        # Enabled flag
+        # --------------------
+        enabled_cfg = cfg.get("enabled")
+        enabled_env = os.getenv("SAFENTIC_AUDIT_ENABLED")
+
+        def _is_truthy(v: str) -> bool:
+            return str(v).strip().lower() not in {"0", "false", "no", "off", ""}
+
+        if enabled_cfg is not None:
+            self.enabled: bool = bool(enabled_cfg)
+        elif enabled_env is not None:
+            self.enabled = _is_truthy(enabled_env)
+        else:
+            # legacy disable switch
+            self.enabled = os.getenv("SAFE_AUDIT_LOG") != "0"
+
+        # default to True if unset by any path
+        if (
+            enabled_cfg is None
+            and enabled_env is None
+            and os.getenv("SAFE_AUDIT_LOG") is None
+        ):
+            self.enabled = True
+
+        # --------------------
+        # Paths (with env overrides)
+        # --------------------
+        txt_from_cfg = cfg.get("destination")
+        txt_from_env = os.getenv("SAFENTIC_LOG_PATH") or os.getenv("SAFE_LOG_PATH")
+        self.txt_log_path: str = (
+            txt_from_cfg or txt_from_env or "safentic/logs/txt_logs/safentic_audit.log"
+        )
+
+        json_from_cfg = cfg.get("jsonl")
+        json_from_env = os.getenv("SAFENTIC_JSON_LOG_PATH") or os.getenv(
+            "SAFE_JSON_LOG_PATH"
+        )
+        self.jsonl_path: str = (
+            json_from_cfg
+            or json_from_env
+            or "safentic/logs/json_logs/safentic_audit.jsonl"
+        )
+
+        # Ensure directories exist (handle bare filenames)
+        txt_dir = os.path.dirname(self.txt_log_path) or "."
+        json_dir = os.path.dirname(self.jsonl_path) or "."
+        os.makedirs(txt_dir, exist_ok=True)
+        os.makedirs(json_dir, exist_ok=True)
+
+        # --------------------
+        # Logger setup
+        # --------------------
+        self.logger: logging.Logger = logging.getLogger("safentic.audit")
+
+        # Level with env override
+        level_str = (
+            cfg.get("level") or os.getenv("SAFENTIC_LOG_LEVEL") or "INFO"
+        ).upper()
+        level_map = {
+            "DEBUG": logging.DEBUG,
+            "INFO": logging.INFO,
+            "WARNING": logging.WARNING,
+            "ERROR": logging.ERROR,
+            "CRITICAL": logging.CRITICAL,
+        }
+        level = level_map.get(level_str, logging.INFO)
+        self.logger.setLevel(level)
+
+        # Avoid duplicate handlers across multiple instantiations:
+        formatter = logging.Formatter("%(asctime)s | %(levelname)s | %(message)s")
+
+        # StreamHandler (only one; don't confuse with FileHandler which subclasses StreamHandler)
+        if not any(
+            isinstance(h, logging.StreamHandler)
+            and not isinstance(h, logging.FileHandler)
+            for h in self.logger.handlers
+        ):
+            stream_handler = logging.StreamHandler()
+            stream_handler.setFormatter(formatter)
+            self.logger.addHandler(stream_handler)
+
+        # FileHandler for the text log (ensure we don't add duplicates for same file)
+        desired_file = os.path.abspath(self.txt_log_path)
+        has_file_handler = any(
+            isinstance(h, logging.FileHandler)
+            and getattr(h, "baseFilename", None) == desired_file
+            for h in self.logger.handlers
+        )
+        if not has_file_handler:
+            file_handler = logging.FileHandler(self.txt_log_path)
+            file_handler.setFormatter(formatter)
+            self.logger.addHandler(file_handler)
+
+    def log(
+        self,
+        agent_id: str,
+        tool: str,
+        allowed: bool,
+        reason: Optional[str] = None,
+        extra: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Write audit logs to console, file, and JSONL. Supports structured extra metadata."""
+        if not self.enabled:
+            return
+
+        entry: Dict[str, Any] = {
+            "timestamp": datetime.now().isoformat(),
+            "agent_id": agent_id,
+            "tool": tool,
+            "allowed": allowed,
+            "reason": reason or "No violation",
+        }
+
+        if extra:
+            entry["extra"] = extra  # structured metadata
+
+        log_level = logging.INFO if allowed else logging.WARNING
+        self.logger.log(log_level, f"[AUDIT] {entry}")
+
+        try:
+            with open(self.jsonl_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry) + "\n")
+        except Exception as e:  # pragma: no cover - logging fallback path
+            # Only log this internal failure to the text logger; do not raise.
+            self.logger.error(f"Failed to write structured audit log: {e}")
+
+    def set_level(self, level: str) -> None:
+        level_map = {
+            "DEBUG": logging.DEBUG,
+            "INFO": logging.INFO,
+            "WARNING": logging.WARNING,
+            "ERROR": logging.ERROR,
+            "CRITICAL": logging.CRITICAL,
+        }
+
+        level_upper = level.upper()
+        if level_upper in level_map:
+            self.logger.setLevel(level_map[level_upper])
+        else:
+            raise ValueError(f"Unsupported log level: {level}")