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

safentic/policy_enforcer.py

@@ -0,0 +1,116 @@
+import time
+from typing import (
+    Any,
+    Dict,
+    Optional,
+)
+
+from .policy_engine import PolicyEngine
+from .logger.audit import AuditLogger
+from ._internal.errors import EnforcementError
+from .helper.helper import deny_response, is_tool_blocked
+
+
+class PolicyEnforcer:
+    """
+    Runtime wrapper to evaluate and enforce tool usage policies.
+    Tracks agent-specific violations, supports audit logging,
+    and handles TTL-based tool blocks.
+
+    Requires a PolicyEngine instance at construction (no implicit defaults).
+    """
+
+    TOOL_BLOCK_TTL = 60  # seconds
+
+    def __init__(
+        self, policy_engine: PolicyEngine, audit_logger: Optional[AuditLogger] = None
+    ) -> None:
+        if not isinstance(policy_engine, PolicyEngine):
+            raise EnforcementError(
+                "PolicyEnforcer requires a valid PolicyEngine instance"
+            )
+
+        self.policy_engine = policy_engine
+        self.agent_states: Dict[str, Dict[str, Any]] = {}
+        self.audit_logger = audit_logger or AuditLogger()
+
+    def enforce(
+        self, agent_id: str, tool_name: str, tool_args: dict[Any, Any]
+    ) -> dict[Any, Any]:
+        """
+        Evaluates a tool action for a given agent.
+        Returns a dict[Any, Any] with 'allowed', 'reason', and agent state metadata.
+        """
+        try:
+            state = self.agent_states.setdefault(
+                agent_id,
+                {
+                    "blocked_tools": {},  # tool_name -> timestamp of block
+                    "violation_count": 0,
+                    "last_violation": None,
+                },
+            )
+
+            # 1) TTL check
+            if is_tool_blocked(tool_name, state, self.TOOL_BLOCK_TTL):
+                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 deny_response(tool_name, state, reason)
+
+            # 2) Policy evaluation
+            violation = self.policy_engine.evaluate_policy(
+                tool_name, tool_args, agent_id=agent_id
+            )
+            if violation:
+                level = violation.get("level", "block")
+                reason = violation.get("reason", "Policy violation")
+
+                # --- FIX: handle boolean violation reasons gracefully ---
+                if isinstance(reason, bool):
+                    reason = "Policy violation (boolean trigger)"
+
+                if level == "warn":
+                    self.audit_logger.log(
+                        agent_id=agent_id,
+                        tool=tool_name,
+                        allowed=True,
+                        reason=f"Warning: {reason}",
+                    )
+                    return {
+                        "allowed": True,
+                        "reason": f"Warning: {reason}",
+                        "violation": violation,
+                        "agent_state": state,
+                    }
+
+                # 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 deny_response(tool_name, state, reason, violation)
+
+            # 3) Allowed
+            self.audit_logger.log(agent_id=agent_id, tool=tool_name, allowed=True)
+            return {
+                "allowed": True,
+                "reason": "Action permitted",
+                "agent_state": state,
+            }
+
+        except Exception as e:
+            raise EnforcementError(
+                f"Failed to enforce policy for {tool_name}: {e}"
+            ) from e
+
+    def reset(self, agent_id: Optional[str] = None) -> None:
+        """Clears violation state for one or all agents."""
+        if agent_id:
+            self.agent_states.pop(agent_id, None)
+        else:
+            self.agent_states.clear()

safentic/policy_engine.py

@@ -0,0 +1,141 @@
+import os
+import yaml
+from typing import Optional, Dict, Any
+
+from .verifiers.llm_verifier import LLMVerifier
+from .logger.audit import AuditLogger
+from ._internal.errors import PolicyValidationError
+from .helper.helper import require, get_text_fields, ReferenceLoader
+
+
+class PolicyEngine:
+    """
+    Loads and evaluates policies defined in YAML.
+    Orchestrates verifiers and returns unified decision objects.
+    """
+
+    VALID_RULE_TYPES = {"llm_verifier"}
+    VALID_LEVELS = {"block", "warn"}  # enforcement levels
+    VALID_RESP_FORMAT = {"boolean"}
+    VALID_MATCH_MODE = {"exact", "contains"}
+
+    def __init__(
+        self,
+        policy_path: str,
+        logger: Optional[AuditLogger] = None,
+        dry_run: bool = False,
+        no_llm: bool = False,  # <-- Added flag
+    ):
+        if not policy_path:
+            raise PolicyValidationError("Policy path must be provided to PolicyEngine")
+
+        self.policy_path = policy_path
+        self.logger = logger or AuditLogger()
+        self.dry_run = dry_run
+        self.no_llm = no_llm  # <-- Store flag
+
+        self.policy_cfg = self._load_policy()
+        self._validate_policy_cfg()
+
+        reference_dir = os.path.dirname(os.path.abspath(self.policy_path)) or "."
+        self.ref_loader = ReferenceLoader(reference_dir)
+        self.llm = LLMVerifier()
+
+    def _load_policy(self) -> Dict[str, Any]:
+        try:
+            with open(self.policy_path, "r", encoding="utf-8") as f:
+                return yaml.safe_load(f) or {}
+        except FileNotFoundError:
+            raise PolicyValidationError(f"Policy file not found: {self.policy_path}")
+        except yaml.YAMLError as e:
+            raise PolicyValidationError(f"Invalid YAML in {self.policy_path}: {e}")
+
+    def _validate_policy_cfg(self) -> None:
+        tools = self.policy_cfg.get("tools")
+        if not isinstance(tools, dict):
+            raise PolicyValidationError(
+                "policy.tools must be a mapping of tool names to configs"
+            )
+
+        for tool_name, cfg in tools.items():
+            rules = cfg.get("rules", [])
+            if not isinstance(rules, list):
+                raise PolicyValidationError(f"{tool_name}.rules must be a list")
+
+            for idx, rule in enumerate(rules):
+                rid = f"{tool_name}[{idx}]"
+                rtype = rule.get("type")
+                if rtype not in self.VALID_RULE_TYPES:
+                    raise PolicyValidationError(f"{rid}: unknown type '{rtype}'")
+
+                if rtype == "llm_verifier":
+                    require(rule, rid, "instruction")
+                    require(rule, rid, "fields")
+                    require(rule, rid, "reference_file")
+
+                    fields = rule["fields"]
+                    if not isinstance(fields, list) or not all(
+                        isinstance(x, str) for x in fields
+                    ):
+                        raise PolicyValidationError(
+                            f"{rid}: 'fields' must be a list[str]"
+                        )
+
+                    if (
+                        rule.get("response_format", "boolean")
+                        not in self.VALID_RESP_FORMAT
+                    ):
+                        raise PolicyValidationError(f"{rid}: invalid response_format")
+
+                    if rule.get("match_mode", "exact") not in self.VALID_MATCH_MODE:
+                        raise PolicyValidationError(f"{rid}: invalid match_mode")
+
+                    if rule.get("level", "block") not in self.VALID_LEVELS:
+                        raise PolicyValidationError(f"{rid}: invalid level")
+
+    def evaluate_policy(
+        self, tool_name: str, tool_input: Dict[str, Any], agent_id: str
+    ) -> Optional[Dict[str, Any]]:
+        tools_cfg = self.policy_cfg.get("tools", {})
+        tool_cfg = tools_cfg.get(tool_name, {})
+        rules = tool_cfg.get("rules", [])
+
+        for rule in rules:
+            rtype = rule.get("type")
+            if rtype not in self.VALID_RULE_TYPES:
+                continue
+
+            if rtype == "llm_verifier":
+                if self.no_llm:
+                    continue  # <-- Skip LLM checks if flag is set
+
+                fields = rule.get("fields", [])
+                rid = f"{tool_name}:{rule.get('description','llm_verifier')}"
+                text = get_text_fields(tool_input, fields, rid=rid, logger=self.logger)
+                if not text:
+                    continue
+
+                reference = self.ref_loader.load(rule["reference_file"])
+                result = self.llm.evaluate(
+                    instruction=rule["instruction"],
+                    agent_output=text,
+                    reference_text=reference,
+                    rule=rule,
+                    tool=tool_name,
+                    agent_id=agent_id,
+                )
+
+                if result:
+                    if self.dry_run:
+                        result["reason"] = "[DRY_RUN] " + result["reason"]
+                        self.logger.log(
+                            agent_id,
+                            tool_name,
+                            allowed=True,
+                            reason=result["reason"],
+                            extra=result,
+                        )
+                        return None
+                    return result
+
+        return None

safentic/verifiers/llm_verifier.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Any, Dict, Optional, Union
+
+from openai import OpenAI
+from ..logger.audit import AuditLogger
+
+
+JSONDict = Dict[str, Any]
+LLMOut = Union[str, bool, JSONDict]
+
+
+class LLMVerifier:
+    """
+    Evaluates agent tool output using an LLM to determine policy compliance.
+    Controlled entirely by developer-authored rules in policy.yaml.
+    """
+
+    def __init__(self, api_key: Optional[str] = None) -> None:
+        self.api_key = api_key or os.getenv("OPENAI_API_KEY", "")
+        if not self.api_key:
+            raise ValueError("OPENAI_API_KEY not set and no api_key provided.")
+        self.client: OpenAI = OpenAI(api_key=self.api_key)
+        self.logger: AuditLogger = AuditLogger()
+
+    def set_api_key(self, api_key: str) -> None:
+        """Allows runtime injection of the API key (e.g., from SafetyLayer)."""
+        self.api_key = api_key
+        self.client = OpenAI(api_key=api_key)
+
+    # -------------------------
+    # Formatting helpers
+    # -------------------------
+
+    def max_tokens_for_format(self, fmt: str) -> int:
+        fmt_l = (fmt or "").lower()
+        if fmt_l == "boolean":
+            return 5
+        if fmt_l == "string":
+            return 50
+        if fmt_l == "json":
+            return 80
+        return 40  # default fallback
+
+    def _to_bool(self, value: Union[str, bool]) -> bool:
+        """Normalize a string/bool into a boolean."""
+        if isinstance(value, bool):
+            return value
+        v = value.strip().lower()
+        return v in ("yes", "true", "1")
+
+    def _normalize_output(self, raw: str, response_format: str) -> LLMOut:
+        """
+        Coerce the model output into the expected response_format.
+
+        - boolean: returns True/False
+        - string: returns a trimmed string
+        - json:   returns a dict (if parseable), else raises
+        """
+        fmt = (response_format or "string").lower()
+
+        if fmt == "boolean":
+            # accept "yes"/"true"/"1" as True; "no"/"false"/"0" as False
+            return self._to_bool(raw)
+
+        if fmt == "json":
+            try:
+                parsed = json.loads(raw)
+            except Exception as e:
+                raise ValueError(f"Expected JSON from model but failed to parse: {e}")
+            if not isinstance(parsed, dict):
+                raise ValueError("Expected a JSON object (dict) from model.")
+            return parsed
+
+        # default string
+        return raw.strip()
+
+    # -------------------------
+    # Matching helpers
+    # -------------------------
+
+    def _check_match(
+        self,
+        llm_output: LLMOut,
+        trigger: str,
+        mode: str,
+        response_format: str,
+    ) -> bool:
+        """
+        Determine if the normalized model output matches the trigger using the chosen mode.
+        - For boolean response_format, we compare booleans directly.
+        - For string, we support exact/contains/regex.
+        - For json, you can use 'jsonpath' (optional) or fallback to string contains on the canonicalized JSON.
+        """
+        fmt = (response_format or "string").lower()
+        mode_l = (mode or "exact").lower()
+
+        if fmt == "boolean":
+            # Map trigger -> boolean and compare directly.
+            out_bool = (
+                llm_output
+                if isinstance(llm_output, bool)
+                else self._to_bool(str(llm_output))
+            )
+            trig_bool = self._to_bool(str(trigger))
+            return out_bool is trig_bool
+
+        if fmt == "json":
+            if mode_l == "jsonpath":
+                try:
+                    from jsonpath_ng.ext import parse
+
+                    results = parse(trigger).find(
+                        llm_output if isinstance(llm_output, dict) else {}
+                    )
+                    return bool(results)
+                except Exception:
+                    return False
+            # fallback: contains over a stable string form of the json
+            s = (
+                json.dumps(llm_output, separators=(",", ":"), ensure_ascii=False)
+                if isinstance(llm_output, dict)
+                else str(llm_output)
+            )
+            return str(trigger).lower() in s.lower()
+
+        # string-like matching
+        s = str(llm_output).strip()
+        trig = str(trigger).strip()
+        if mode_l == "exact":
+            return s.lower() == trig.lower()
+        if mode_l == "contains":
+            return trig.lower() in s.lower()
+        if mode_l == "regex":
+            try:
+                return re.search(trig, s, re.IGNORECASE) is not None
+            except re.error:
+                return False
+        # default conservative
+        return False
+
+    # -------------------------
+    # Public API
+    # -------------------------
+
+    def evaluate(
+        self,
+        instruction: str,
+        agent_output: str,
+        reference_text: str,
+        rule: Dict[str, Any],
+        tool: str,
+        agent_id: str,
+    ) -> Dict[str, Any]:
+        """
+        Performs LLM evaluation and returns structured result.
+        Never raises for trigger mismatches; only raises for fatal formatting errors.
+        """
+        response_format: str = rule.get("response_format", "boolean")
+        match_mode: str = rule.get("match_mode", "exact")
+        response_trigger: str = rule.get("response_trigger", "yes")
+        level: str = rule.get("level", "block")
+        severity: str = rule.get("severity", "medium")
+        reference_filename: Optional[str] = rule.get("reference_file")
+        model_name: str = rule.get("model", "gpt-4")
+
+        prompt = f"""{instruction}
+
+Agent Response:
+{agent_output}
+
+Company Policy:
+{reference_text}
+
+Respond only with: {response_format}"""
+
+        try:
+            res = self.client.chat.completions.create(
+                model=model_name,
+                messages=[
+                    {
+                        "role": "system",
+                        "content": "You are a compliance checker for internal company policy.",
+                    },
+                    {"role": "user", "content": prompt},
+                ],
+                max_tokens=self.max_tokens_for_format(response_format),
+                temperature=0,
+            )
+
+            raw_text = (res.choices[0].message.content or "").strip()
+
+            # Normalize into the declared format
+            normalized = self._normalize_output(raw_text, response_format)
+
+            # Perform trigger check safely for str/bool/json
+            matched = self._check_match(
+                llm_output=normalized,
+                trigger=response_trigger,
+                mode=match_mode,
+                response_format=response_format,
+            )
+
+        except Exception as e:
+            # Surface a clear, single-line reason to upstream callers
+            raise RuntimeError(f"LLM evaluation failed: {e}") from e
+
+        if matched:
+            reason = (
+                f"LLM rule triggered (trigger='{response_trigger}', "
+                f"mode='{match_mode}', fmt='{response_format}')"
+            )
+            self.logger.log(
+                agent_id=agent_id, tool=tool, allowed=(level != "block"), reason=reason
+            )
+            return {
+                "level": level,
+                "severity": severity,
+                "matched_value": (
+                    normalized if not isinstance(normalized, dict) else "[json]"
+                ),
+                "reference_file": reference_filename,
+                "description": rule.get("description", ""),
+                "tags": rule.get("tags", []),
+                "reason": reason,
+            }
+
+        # No match → allow
+        self.logger.log(
+            agent_id=agent_id,
+            tool=tool,
+            allowed=True,
+            reason="No match",
+        )
+        return {}

safentic-1.0.6.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: safentic
+Version: 1.0.6
+Summary: Safentic SDK for AI agent runtime enforcement interception.
+Author-email: Safentic <contact@safentic.com>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://safentic.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: PyYAML
+Requires-Dist: langchain
+Requires-Dist: langchain-community
+Requires-Dist: langchain-openai
+Requires-Dist: openai
+Requires-Dist: python-dotenv
+Requires-Dist: sentence-transformers==3.2.1
+Requires-Dist: requests
+Requires-Dist: SQLAlchemy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pip-audit-extra; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Dynamic: license-file
+
+# Safentic SDK
+
+- **Safentic is a runtime guardrail SDK for agentic AI systems.**
+- It intercepts and evaluates tool calls between agent intent and execution, enforcing custom safety policies and generating structured audit logs for compliance.
+
+## Installation
+`pip install safentic`
+
+# Quickstart: Wrap Your Agent
+
+- Safentic works at the action boundary, not inside the model itself. You wrap your agent with SafetyLayer:
+
+```
+from safentic.layer import SafetyLayer
+from agent import AgentClassInstance  # your existing agent
+
+agent = AgentClassInstance()
+```
+
+## Wrap with Safentic
+``` layer = SafetyLayer(agent=agent, api_key="your-api-key", agent_id="demo-agent") ```
+
+## Example tool call
+```
+try:
+    result = layer.call_tool("some_tool", {"body": "example input"})
+    print(result)
+except Exception as e:
+    print("Blocked:", e)
+```
+
+## Output:
+
+- Blocked: Blocked by policy
+
+# Configuring Your Policy File
+
+- Safentic enforces rules defined in a YAML configuration file (e.g. policy.yaml).
+- By default, it looks for config/policy.yaml, or you can set the path with:
+
+```
+export SAFENTIC_POLICY_PATH=/path/to/policy.yaml
+```
+
+## Schema
+
+- At the moment, Safentic supports the llm_verifier rule type.
+
+``` 
+tools:
+  <tool_name>:
+    rules:
+      - type: llm_verifier
+        description: "<short description of what this rule enforces>"
+        instruction: "<prompt instruction given to the verifier LLM>"
+        model: "<llm model name, e.g. gpt-4>"
+        fields: [<list of input fields to check>]
+        reference_file: "<path to reference text file, optional>"
+        response_format: boolean
+        response_trigger: yes
+        match_mode: exact
+        level: block         # enforcement level: block | warn
+        severity: high       # severity: low | medium | high
+        tags: [<labels for filtering/searching logs>]
+
+logging:
+  level: INFO
+  destination: "safentic/logs/txt_logs/safentic_audit.log"
+  jsonl: "safentic/logs/json_logs/safentic_audit.jsonl"
+
+Example Policy (obfuscated)
+tools:
+  sample_tool:
+    rules:
+      - type: llm_verifier
+        description: "Block outputs that contain disallowed terms"
+        instruction: "Does this text contain disallowed terms or references?"
+        model: gpt-4
+        fields: [body]
+        reference_file: sample_guidelines.txt
+        response_format: boolean
+        response_trigger: yes
+        match_mode: exact
+        level: block
+        severity: high
+        tags: [sample, denylist]
+
+  another_tool:
+    rules: []  # Explicitly allow all actions for this tool
+
+logging:
+  level: INFO
+  destination: "safentic/logs/txt_logs/safentic_audit.log"
+  jsonl: "safentic/logs/json_logs/safentic_audit.jsonl"
+```
+
+## Audit Logs
+
+- Every decision is logged with context for compliance and debugging:
+
+```
+{
+  "timestamp": "2025-09-09T14:25:11Z",
+  "agent_id": "demo-agent",
+  "tool": "sample_tool",
+  "allowed": false,
+  "reason": "Blocked by policy",
+  "rule": "sample_tool:denylist_check",
+  "severity": "high",
+  "level": "block",
+  "tags": ["sample", "denylist"]
+}
+```
+
+### Log Fields
+
+- timestamp – when the action was evaluated
+- agent_id – the agent issuing the action
+- tool – tool name
+- allowed – whether the action was permitted
+- reason – why it was allowed or blocked
+- rule – the rule that applied (if any)
+- severity – severity of the violation
+- level – enforcement level (block, warn)
+- tags – categories attached to the rule
+- extra – additional metadata (e.g., missing fields, matched text)
+
+# CLI Commands
+
+- Safentic ships with a CLI for validating policies, running one-off checks, and inspecting logs:
+
+## Validate a policy file
+```
+safentic validate-policy --policy config/policy.yaml --strict
+```
+
+## Run a one-off tool check
+```
+safentic check-tool --tool sample_tool \
+  --input-json '{"body": "some text"}' \
+  --policy config/policy.yaml
+```
+## Tail the audit log (JSONL by default)
+```
+safentic logs tail --path safentic/logs/json_logs/safentic_audit.jsonl -f
+```
+
+## Environment Variables
+
+Set these before running Safentic:
+
+- ```OPENAI_API_KEY``` – **required** for rules that use llm_verifier (e.g., GPT-4).
+- ```SAFENTIC_POLICY_PATH``` – path to your policy.yaml (default: config/policy.yaml).
+- ```SAFENTIC_LOG_PATH``` – override the default text audit log path.
+- ```SAFENTIC_JSON_LOG_PATH``` – override the default JSONL audit log path.
+- ```LOG_LEVEL``` – optional, sets verbosity (DEBUG, INFO, etc.).
+
+# Supported Stacks
+
+- Safentic integrates with frameworks like LangChain, AutoGen, and MCP by wrapping the tool dispatcher rather than modifying the model or prompts.