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

safentic/__init__.py

@@ -1,8 +1,5 @@
-from .layer import SafetyLayer, SafenticError
+from .layer import SafetyLayer
+from ._internal.errors import SafenticError
 
-__all__ = [
-    "SafetyLayer",
-    "SafenticError",
-]
-
-__version__ = "1.0.5"
+__all__ = ["SafetyLayer", "SafenticError"]
+__version__ = "1.0.6"

safentic/_internal/errors.py

@@ -0,0 +1,26 @@
+class SafenticError(Exception):
+    """Base class for all Safentic errors."""
+
+
+class PolicyValidationError(SafenticError):
+    """Raised when a policy file or rule is invalid."""
+
+
+class ReferenceFileError(SafenticError):
+    """Raised when a reference file is missing, unreadable, or empty."""
+
+
+class EnforcementError(SafenticError):
+    """Raised when enforcement fails unexpectedly."""
+
+
+class VerifierError(SafenticError):
+    """Raised when the LLM verifier fails unexpectedly."""
+
+
+class InvalidAPIKeyError(SafenticError):
+    """Raised when an API key is missing or invalid."""
+
+
+class InvalidAgentInterfaceError(SafenticError):
+    """Raised when the wrapped agent doesn't expose the expected interface."""

safentic/adapters/mcp_adapter.py

@@ -0,0 +1,46 @@
+from typing import Any, Dict, Mapping, cast
+from safentic.policy_enforcer import PolicyEnforcer
+
+
+def handle_mcp_action(
+    action_request: Mapping[str, Any], enforcer: PolicyEnforcer
+) -> Dict[str, Any]:
+    """
+    Accepts an MCP ActionRequest and returns a Safentic policy enforcement result.
+    Requires a PolicyEnforcer instance to be passed in.
+
+    Expected shape (minimal):
+    {
+        "tool": {
+            "name": str,
+            "input": dict[str, Any]
+        },
+        "agent": {
+            "id": str
+        }
+    }
+    """
+
+    tool: Dict[str, Any] = cast(Dict[str, Any], action_request.get("tool", {}))
+    agent: Dict[str, Any] = cast(Dict[str, Any], action_request.get("agent", {}))
+
+    tool_name: str = cast(str, tool.get("name", "unknown_tool"))
+    tool_args: Dict[str, Any] = cast(
+        Dict[str, Any], tool.get("input", {})
+    )  # Expected to include "body" or "note"
+    agent_id: str = cast(str, agent.get("id", "unknown_agent"))
+
+    result: Dict[str, Any] = enforcer.enforce(
+        agent_id=agent_id,
+        tool_name=tool_name,
+        tool_args=tool_args,
+    )
+
+    return {
+        "tool": tool_name,
+        "agent_id": agent_id,
+        "allowed": result["allowed"],
+        "reason": result["reason"],
+        "agent_state": result.get("agent_state", {}),
+        "violation": result.get("violation"),  # Optional violation metadata
+    }

safentic/cli/__init__.py

@@ -0,0 +1,3 @@
+from typing import List
+
+__all__: List[str] = []

safentic/cli/commands/check_tool.py

@@ -0,0 +1,47 @@
+from typing import Any, Dict, Optional
+
+from safentic.policy_engine import PolicyEngine
+from safentic.policy_enforcer import PolicyEnforcer
+from safentic.cli.utils import resolve_policy_path, load_json_arg, ok, error
+
+
+def run(
+    policy: Optional[str],
+    tool_name: str,
+    agent_id: str,
+    input_json: Optional[str],
+    input_file: Optional[str],
+    dry_run: bool,
+    allow_fail: bool,
+    no_llm: bool = False,
+) -> Dict[str, Any]:
+    """
+    Run a one-off policy enforcement for a tool + payload.
+    Returns a JSON payload. Raises SystemExit(2) if blocked and allow_fail=False.
+    """
+    policy_path = resolve_policy_path(policy)
+
+    try:
+        engine = PolicyEngine(policy_path=policy_path, dry_run=dry_run, no_llm=no_llm)
+        enforcer = PolicyEnforcer(policy_engine=engine)
+
+        payload: Dict[str, Any] = load_json_arg(input_json, input_file)
+        decision = enforcer.enforce(
+            agent_id=agent_id, tool_name=tool_name, tool_args=payload
+        )
+
+        result = ok(
+            f"Check completed for tool: {tool_name}",
+            {"policy_path": policy_path, "decision": decision},
+        )
+
+        if not decision.get("allowed", False) and not allow_fail:
+            # Signal to CI callers that this is a block
+            raise SystemExit(2)
+
+        return result
+
+    except SystemExit:
+        raise
+    except Exception as e:
+        return error("check-tool failed", {"details": str(e)})

safentic/cli/commands/logs.py

@@ -0,0 +1,66 @@
+import io
+import os
+import time
+from typing import Dict, Any, Optional
+
+from safentic.cli.utils import resolve_log_path, ok, error, print_json
+
+
+def _stream_tail(path: str) -> None:
+    """Follow a file until interrupted (like tail -f)."""
+    with open(path, "r", encoding="utf-8") as f:
+        f.seek(0, io.SEEK_END)
+        while True:
+            line = f.readline()
+            if not line:
+                time.sleep(0.25)
+                continue
+            print(line.rstrip())
+
+
+def run_tail(
+    path: Optional[str] = None, follow: bool = False, prefer_json: bool = True
+) -> Optional[Dict[str, Any]]:
+    """
+    Tail logs (defaults to JSONL). If follow=True, stream and do not return a JSON envelope.
+    If follow=False, return last 200 lines as a JSON payload.
+    """
+    resolved_path, source = resolve_log_path(user_path=path, prefer_json=prefer_json)
+
+    if not os.path.exists(resolved_path):
+        return error(
+            "Log file not found",
+            {
+                "path": resolved_path,
+                "resolved_from": source,
+                "hint": "Generate logs via agent or check-tool first.",
+            },
+        )
+
+    if follow:
+        # Emit a one-time prelude so users know what is being tailed
+        print_json(
+            ok("Following log file", {"path": resolved_path, "resolved_from": source})
+        )
+        try:
+            _stream_tail(resolved_path)
+        except KeyboardInterrupt:
+            return None
+        return None
+
+    try:
+        with open(resolved_path, "r", encoding="utf-8") as f:
+            lines = f.readlines()[-200:]
+        return ok(
+            "Fetched recent logs",
+            {
+                "path": resolved_path,
+                "resolved_from": source,
+                "lines": [ln.rstrip() for ln in lines],
+            },
+        )
+    except Exception as e:
+        return error(
+            "Failed to read log file",
+            {"path": resolved_path, "resolved_from": source, "details": str(e)},
+        )

safentic/cli/commands/validate_policy.py

@@ -0,0 +1,59 @@
+import os
+from typing import Any, Dict, Optional
+
+from safentic.policy_engine import PolicyEngine
+from safentic.cli.utils import resolve_policy_path, ok, error
+import yaml
+
+
+def run(
+    policy: Optional[str] = None,
+    dry_run: bool = False,
+    strict: bool = False,
+    no_llm: bool = False,
+) -> Dict[str, Any]:
+    """Validate a policy file using the SDK loader/validator."""
+    policy_path = resolve_policy_path(policy)
+
+    if not os.path.exists(policy_path):
+        return error(
+            f"Policy validation failed for {policy_path}",
+            {"details": f"Policy file not found: {policy_path}"},
+        )
+
+    try:
+        engine = PolicyEngine(policy_path=policy_path, dry_run=dry_run, no_llm=no_llm)
+        tools_cfg: Dict[str, Any] = engine.policy_cfg.get("tools", {}) or {}
+        tool_count = len(tools_cfg)
+        rule_count = sum(
+            len((cfg or {}).get("rules", [])) for cfg in tools_cfg.values()
+        )
+
+        missing_refs: list[str] = []
+        if strict:
+            with open(policy_path, "r") as f:
+                policy_yaml = yaml.safe_load(f)
+            for tool in policy_yaml.get("tools", {}).values():
+                for rule in tool.get("rules", []):
+                    ref_file = rule.get("reference_file")
+                    if ref_file and not os.path.exists(ref_file):
+                        missing_refs.append(ref_file)
+            if missing_refs:
+                return error(
+                    "Policy validation failed: missing reference files.",
+                    {"missing_files": missing_refs},
+                )
+
+        return ok(
+            "Policy validated successfully.",
+            {
+                "policy_path": os.path.abspath(policy_path),
+                "tools": tool_count,
+                "rules": rule_count,
+                "dry_run": engine.dry_run,
+                "no_llm": no_llm,
+                "strict": strict,
+            },
+        )
+    except Exception as e:
+        return error(f"Policy validation failed for {policy_path}", {"details": str(e)})

safentic/cli/main.py

@@ -0,0 +1,153 @@
+import argparse
+import sys
+from typing import Any, Optional, Dict
+
+from safentic.cli.commands.validate_policy import run as run_validate
+from safentic.cli.commands.check_tool import run as run_check
+from safentic.cli.commands.logs import run_tail as run_logs_tail
+from safentic.cli.utils import print_output, set_output_mode
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="safentic",
+        description="Safentic CLI — validate policies, simulate tool checks, and tail audit logs.",
+    )
+    parser.add_argument("--version", action="version", version="safentic-cli 0.1.0")
+
+    # Common flags available on each subcommand
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "--policy", help="Path to policy.yaml (overrides SAFENTIC_POLICY_PATH)"
+    )
+    common.add_argument(
+        "--dry-run", action="store_true", help="Simulate enforcement (never block)"
+    )
+    common.add_argument(
+        "--json", action="store_true", help="Output machine-readable JSON"
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # validate-policy
+    p_val = sub.add_parser(
+        "validate-policy",
+        help="Validate a policy file and references",
+        parents=[common],
+        add_help=True,
+    )
+    p_val.add_argument(
+        "--strict",
+        action="store_true",
+        help="Fail if reference_file paths do not exist",
+    )
+    p_val.add_argument(
+        "--no-llm", action="store_true", help="Skip LLM-based checks for speed"
+    )
+    p_val.set_defaults(cmd="validate-policy")
+
+    # check-tool
+    p_chk = sub.add_parser(
+        "check-tool",
+        help="Run a one-off enforcement for a tool + JSON input",
+        parents=[common],
+        add_help=True,
+    )
+    p_chk.add_argument(
+        "--tool", required=True, help="Tool name to check (e.g., issue_refund)"
+    )
+    p_chk.add_argument(
+        "--agent-id", default="cli-agent", help="Agent ID (default: cli-agent)"
+    )
+    g = p_chk.add_mutually_exclusive_group()
+    g.add_argument("--input-json", help="Raw JSON string for tool input")
+    g.add_argument("--input-file", help="Path to JSON file for tool input")
+    p_chk.add_argument(
+        "--allow-fail",
+        action="store_true",
+        help="Exit code 0 even if blocked (local dev)",
+    )
+    p_chk.add_argument(
+        "--no-llm", action="store_true", help="Skip LLM-based checks for speed"
+    )
+    p_chk.set_defaults(cmd="check-tool")
+
+    # logs (tail)
+    p_logs = sub.add_parser("logs", help="Work with audit logs")
+    sub_logs = p_logs.add_subparsers(dest="logs_cmd", required=True)
+
+    p_tail = sub_logs.add_parser(
+        "tail",
+        help="Tail the audit log (JSONL by default)",
+        parents=[common],
+        add_help=True,
+    )
+    p_tail.add_argument("--path", help="Path to the log file (overrides env/config)")
+    p_tail.add_argument(
+        "-f",
+        "--follow",
+        action="store_true",
+        help="Follow appended lines (like tail -f)",
+    )
+    p_tail.set_defaults(cmd="logs:tail")
+
+    return parser
+
+
+def _maybe_exit_on_error(payload: Optional[Dict[str, Any]]) -> None:
+    """Exit with code 1 if payload indicates an error."""
+    if payload is not None and not payload.get("ok", False):
+        sys.exit(1)
+
+
+def main(argv: Optional[list[Any]] = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    payload: Dict[str, Any] = {}
+    # Set global output mode
+    set_output_mode(getattr(args, "json", False))
+
+    if args.command == "validate-policy":
+        payload = run_validate(
+            policy=args.policy,
+            dry_run=getattr(args, "dry_run", False),
+            strict=getattr(args, "strict", False),
+            no_llm=getattr(args, "no_llm", False),
+        )
+        print_output(payload)
+        _maybe_exit_on_error(payload)
+        return
+
+    if args.command == "check-tool":
+        try:
+            payload = run_check(
+                policy=args.policy,
+                tool_name=args.tool,
+                agent_id=args.agent_id,
+                input_json=getattr(args, "input_json", None),
+                input_file=getattr(args, "input_file", None),
+                dry_run=getattr(args, "dry_run", False),
+                allow_fail=getattr(args, "allow_fail", False),
+                no_llm=getattr(args, "no_llm", False),
+            )
+            print_output(payload)
+            _maybe_exit_on_error(payload)
+        except SystemExit:
+            # allow exit code 2 (blocked) to propagate for CI
+            raise
+        return
+
+    if args.command == "logs" and args.logs_cmd == "tail":
+        log_payload: Optional[Dict[str, Any]] = run_logs_tail(
+            path=getattr(args, "path", None),
+            follow=getattr(args, "follow", False),
+            prefer_json=True,
+        )
+        if log_payload is not None:
+            print_output(log_payload)
+        _maybe_exit_on_error(log_payload)
+        return
+
+
+if __name__ == "__main__":
+    main()

safentic/cli/utils.py

@@ -0,0 +1,169 @@
+import os
+import json
+from typing import Any, Dict, Optional, Tuple
+
+# -------------------------------------------------
+# Output formatting
+# -------------------------------------------------
+
+_OUTPUT_JSON = False  # default: pretty (plain) output
+
+
+def set_output_mode(json_mode: bool) -> None:
+    """Set global output mode for the CLI."""
+    global _OUTPUT_JSON
+    _OUTPUT_JSON = bool(json_mode)
+
+
+def ok(message: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    return {"ok": True, "message": message, "data": data or {}}
+
+
+def error(message: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    return {"ok": False, "message": message, "error": data or {}}
+
+
+def _pretty(payload: Dict[str, Any]) -> str:
+    if payload.get("ok", True):
+        msg = f"{payload.get('message','OK')}"
+        data = payload.get("data") or {}
+        if data:
+            parts = []
+            for k, v in data.items():
+                if isinstance(v, (list, tuple)):
+                    if k == "lines":
+                        parts.append(f"{k}:\n" + "\n".join(str(x) for x in v))
+                    else:
+                        parts.append(f"{k}: {len(v)} items")
+                elif isinstance(v, dict):
+                    # Show small dicts inline, otherwise key count
+                    items = ", ".join(f"{ik}={iv}" for ik, iv in list(v.items())[:6])
+                    suffix = "" if len(v) <= 6 else ", …"
+                    parts.append(f"{k}: {items}{suffix}")
+                else:
+                    parts.append(f"{k}: {v}")
+            if parts:
+                return msg + "\n" + "\n".join(parts)
+        return msg
+    else:
+        msg = f"{payload.get('message','Error')}"
+        err = payload.get("error") or {}
+        if err:
+            try:
+                return msg + "\n" + json.dumps(err, indent=2)
+            except Exception:
+                return msg + "\n" + str(err)
+        return msg
+
+
+def print_output(payload: Dict[str, Any]) -> None:
+    if _OUTPUT_JSON:
+        print(json.dumps(payload, indent=2))
+    else:
+        print(_pretty(payload))
+
+
+def print_json(payload: Dict[str, Any]) -> None:
+    """Sometimes needed for streaming prelude messages."""
+    print(json.dumps(payload, indent=2))
+
+
+# -------------------------------------------------
+# Helpers: policy & logs path resolution, input loading
+# -------------------------------------------------
+
+
+def resolve_policy_path(arg_path: Optional[str]) -> str:
+    """
+    Precedence:
+      1) --policy (arg)
+      2) SAFENTIC_POLICY_PATH (env)
+      3) repo default: config/policy.yaml
+    """
+    if arg_path:
+        return os.path.abspath(arg_path)
+    env_path = os.getenv("SAFENTIC_POLICY_PATH")
+    if env_path:
+        return os.path.abspath(env_path)
+    return os.path.abspath(
+        os.path.join(os.path.dirname(__file__), "..", "..", "config", "policy.yaml")
+    )
+
+
+def load_json_arg(
+    input_json: Optional[str], input_file: Optional[str]
+) -> Dict[str, Any]:
+    """Load JSON from either a raw string or a file path (mutually exclusive).
+    Ensures the top-level value is a JSON object (dict).
+    """
+    if input_json and input_file:
+        raise ValueError("Provide either --input-json OR --input-file, not both.")
+
+    parsed: Any = None
+    if input_json:
+        try:
+            parsed = json.loads(input_json)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in --input-json: {e}") from e
+        if isinstance(parsed, dict):
+            return parsed
+        raise ValueError(
+            'Expected a JSON object for --input-json (e.g., {"key": "value"}).'
+        )
+
+    if input_file:
+        if not os.path.isfile(input_file):
+            raise FileNotFoundError(f"Input file not found: {input_file}")
+        with open(input_file, "r", encoding="utf-8") as f:
+            try:
+                parsed = json.load(f)
+            except json.JSONDecodeError as e:
+                raise ValueError(f"Invalid JSON in --input-file: {e}") from e
+        if isinstance(parsed, dict):
+            return parsed
+        raise ValueError(
+            "Expected a JSON object in --input-file (top-level must be an object)."
+        )
+
+    return {}
+
+
+def resolve_log_path(
+    user_path: Optional[str] = None, prefer_json: bool = True
+) -> Tuple[str, str]:
+    """
+    Resolve log path dynamically with precedence:
+      1) explicit --path (user_path)
+      2) environment variables (SAFENTIC_JSON_LOG_PATH / SAFENTIC_LOG_PATH / SAFE_JSON_LOG_PATH / SAFE_LOG_PATH)
+      3) AuditLogger config (jsonl_path / txt_log_path)
+      4) repo default fallback under safentic/logs/...
+    Returns (resolved_path, source_hint).
+    """
+    if user_path:
+        return os.path.abspath(user_path), "cli_arg"
+
+    env_keys_json = ["SAFENTIC_JSON_LOG_PATH", "SAFE_JSON_LOG_PATH"]
+    env_keys_txt = ["SAFENTIC_LOG_PATH", "SAFE_LOG_PATH"]
+    for key in env_keys_json if prefer_json else env_keys_txt:
+        val = os.getenv(key)
+        if val:
+            return os.path.abspath(val), f"env:{key}"
+
+    # Try AuditLogger configuration (lazy import)
+    try:
+        from safentic.logger.audit import AuditLogger
+
+        logger = AuditLogger()
+        resolved = logger.jsonl_path if prefer_json else logger.txt_log_path
+        if resolved:
+            return os.path.abspath(resolved), "audit_logger"
+    except Exception:
+        pass
+
+    # Fallback
+    fallback = (
+        os.path.join("safentic", "logs", "json_logs", "safentic_audit.jsonl")
+        if prefer_json
+        else os.path.join("safentic", "logs", "txt_logs", "safentic_audit.log")
+    )
+    return os.path.abspath(fallback), "fallback"

safentic/config.py

@@ -1,2 +1,2 @@
-BASE_API_PATH = "https://safentic-api.onrender.com/"
-API_KEY_ENDPOINT = "auth/validate"
+BASE_API_PATH = "https://safentic-api.onrender.com/"
+API_KEY_ENDPOINT = "auth/validate"

safentic/decorators.py

@@ -0,0 +1,49 @@
+# safentic/decorators.py
+
+from functools import wraps
+from typing import Any, Callable, TypeVar, ParamSpec
+
+from safentic.adapters.mcp_adapter import handle_mcp_action
+from safentic.policy_engine import PolicyEngine
+from safentic.policy_enforcer import PolicyEnforcer
+
+engine = PolicyEngine(policy_path="config/policy.yaml")
+enforcer = PolicyEnforcer(policy_engine=engine)
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def enforce(
+    tool_name: str, agent_id: str = "default-agent"
+) -> Callable[[Callable[P, R]], Callable[P, R | str]]:
+    """
+    Decorator that routes tool calls through Safentic via MCP.
+
+    Note: The wrapped function may return its original type R, or a str when blocked.
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R | str]:
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R | str:
+            tool_input: dict[str, Any] = kwargs or {"note": args[0]} if args else {}
+
+            action_request: dict[str, Any] = {
+                "tool": {"name": tool_name, "input": tool_input},
+                "agent": {"id": agent_id},
+            }
+
+            # 🔹 Always pass the enforcer
+            result: dict[str, Any] = handle_mcp_action(action_request, enforcer)
+
+            if not result["allowed"]:
+                print(
+                    f"\n[BLOCKED by Safentic] {tool_name.upper()} — {result['reason']}"
+                )
+                return f"[BLOCKED] {result['reason']}"
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator