sernixa 0.1.0__py3-none-any.whl

sernixa/__init__.py

@@ -0,0 +1,94 @@
+import importlib.metadata as _im
+
+try:
+    __version__ = _im.version("sernixa")
+except _im.PackageNotFoundError:
+    __version__ = "unknown"
+
+from .client import (
+    APPROVED_STATUSES,
+    TERMINAL_STATUSES,
+    Client,
+    action_metadata,
+    create_delegation_token,
+    delegated_request_body_hash,
+    delegation_scope,
+    delegated_request_signature_payload,
+    intercept,
+    is_approved_status,
+    is_replay_error,
+    is_revoked_error,
+    is_scope_error,
+    is_terminal_status,
+    sign_delegated_request,
+    with_delegation,
+)
+from .dlp import DlpResult, protect_metadata
+from .exceptions import (
+    SernixaApiError,
+    SernixaBlockedError,
+    SernixaConfigurationError,
+    SernixaDelegationScopeError,
+    SernixaError,
+    SernixaExpiredError,
+    SernixaRateLimitError,
+    SernixaReplayError,
+    SernixaRejectedError,
+    SernixaSignatureError,
+    SernixaTimeoutError,
+    SernixaValidationError,
+)
+from .adapters import (
+    McpInvocationContext,
+    McpToolBoundary,
+    SernixaCrewAITool,
+    SernixaLangChainTool,
+    crewai_tool,
+    langchain_tool,
+    mcp_tool,
+    secure_crewai_tool,
+    secure_langchain_tool,
+)
+
+__all__ = [
+    "Client",
+    "intercept",
+    "create_delegation_token",
+    "with_delegation",
+    "delegation_scope",
+    "delegated_request_signature_payload",
+    "delegated_request_body_hash",
+    "sign_delegated_request",
+    "action_metadata",
+    "protect_metadata",
+    "DlpResult",
+    "is_approved_status",
+    "is_terminal_status",
+    "is_replay_error",
+    "is_scope_error",
+    "is_revoked_error",
+    "APPROVED_STATUSES",
+    "TERMINAL_STATUSES",
+    "SernixaError",
+    "SernixaConfigurationError",
+    "SernixaValidationError",
+    "SernixaRateLimitError",
+    "SernixaBlockedError",
+    "SernixaDelegationScopeError",
+    "SernixaReplayError",
+    "SernixaSignatureError",
+    "SernixaRejectedError",
+    "SernixaExpiredError",
+    "SernixaTimeoutError",
+    "SernixaApiError",
+    "langchain_tool",
+    "secure_langchain_tool",
+    "SernixaLangChainTool",
+    "crewai_tool",
+    "secure_crewai_tool",
+    "SernixaCrewAITool",
+    "mcp_tool",
+    "McpToolBoundary",
+    "McpInvocationContext",
+    "__version__",
+]

sernixa/adapters/__init__.py

@@ -0,0 +1,17 @@
+from .autogen import autogen_tool
+from .crewai import SernixaCrewAITool, crewai_tool, secure_crewai_tool
+from .langchain import SernixaLangChainTool, langchain_tool, secure_langchain_tool
+from .mcp import McpInvocationContext, McpToolBoundary, mcp_tool
+
+__all__ = [
+    "autogen_tool",
+    "crewai_tool",
+    "langchain_tool",
+    "secure_crewai_tool",
+    "secure_langchain_tool",
+    "SernixaCrewAITool",
+    "SernixaLangChainTool",
+    "McpInvocationContext",
+    "McpToolBoundary",
+    "mcp_tool",
+]

sernixa/adapters/_common.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable
+from typing import Any, Callable, TypeVar
+
+from sernixa.client import Client
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def secure_callable(
+    *,
+    client: Client | None = None,
+    intent_id: str,
+    risk_level: str = "LOW",
+    operation_class: str = "tool_call",
+    data_sensitivity: str = "internal",
+    systems_touched: list[str] | None = None,
+    framework: str,
+    action_id: str | None = None,
+    **metadata: Any,
+) -> Callable[[F], F]:
+    active_client = client or Client()
+    return active_client.intercept(
+        intent_id=intent_id,
+        risk_level=risk_level,
+        operation_class=operation_class,
+        data_sensitivity=data_sensitivity,
+        systems_touched=systems_touched or [framework],
+        metadata={"framework": framework, **metadata},
+        action_id=action_id,
+    )
+
+
+def callable_name(value: Any, fallback: str) -> str:
+    for attr in ("name", "__name__"):
+        candidate = getattr(value, attr, None)
+        if isinstance(candidate, str) and candidate.strip():
+            return candidate.strip()
+    return fallback
+
+
+def action_id_for(framework: str, tool_name: str) -> str:
+    normalized = "".join(char if char.isalnum() or char in "._-" else "-" for char in tool_name)
+    return f"{framework}.{normalized.strip('-') or 'tool'}"
+
+
+def ensure_callable(value: Any, label: str) -> Callable[..., Any]:
+    if not callable(value):
+        raise TypeError(f"{label} must be callable.")
+    return value
+
+
+def is_awaitable(value: Any) -> bool:
+    return inspect.isawaitable(value) or isinstance(value, Awaitable)

sernixa/adapters/autogen.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+from sernixa.client import Client
+
+from ._common import secure_callable
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def autogen_tool(
+    *,
+    intent_id: str,
+    risk_level: str = "LOW",
+    operation_class: str = "tool_call",
+    data_sensitivity: str = "internal",
+    systems_touched: list[str] | None = None,
+    client: Client | None = None,
+    **metadata: Any,
+) -> Callable[[F], F]:
+    """Wrap an AutoGen function tool before registering it with an agent."""
+    return secure_callable(
+        client=client,
+        intent_id=intent_id,
+        risk_level=risk_level,
+        operation_class=operation_class,
+        data_sensitivity=data_sensitivity,
+        systems_touched=systems_touched,
+        framework="autogen",
+        **metadata,
+    )

sernixa/adapters/crewai.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+from sernixa.client import Client
+
+from ._common import action_id_for, callable_name, secure_callable
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def crewai_tool(
+    *,
+    intent_id: str,
+    risk_level: str = "LOW",
+    operation_class: str = "tool_call",
+    data_sensitivity: str = "internal",
+    systems_touched: list[str] | None = None,
+    client: Client | None = None,
+    action_id: str | None = None,
+    **metadata: Any,
+) -> Callable[[F], F]:
+    """Wrap a CrewAI tool callable while preserving normal Python ergonomics."""
+    return secure_callable(
+        client=client,
+        intent_id=intent_id,
+        risk_level=risk_level,
+        operation_class=operation_class,
+        data_sensitivity=data_sensitivity,
+        systems_touched=systems_touched,
+        framework="crewai",
+        action_id=action_id,
+        **metadata,
+    )
+
+
+class SernixaCrewAITool:
+    """Proxy for CrewAI-style tool objects and callables.
+
+    CrewAI tools commonly expose `run`, `_run`, or direct `__call__` execution.
+    The proxy guards those boundaries without requiring CrewAI as an SDK
+    dependency.
+    """
+
+    def __init__(
+        self,
+        tool: Any,
+        *,
+        intent_id: str,
+        risk_level: str = "LOW",
+        operation_class: str = "tool_call",
+        data_sensitivity: str = "internal",
+        systems_touched: list[str] | None = None,
+        client: Client | None = None,
+        action_id: str | None = None,
+        **metadata: Any,
+    ) -> None:
+        self._tool = tool
+        self._client = client or Client()
+        self._tool_name = callable_name(tool, "crewai-tool")
+        self._config = {
+            "intent_id": intent_id,
+            "risk_level": risk_level,
+            "operation_class": operation_class,
+            "data_sensitivity": data_sensitivity,
+            "systems_touched": systems_touched or ["crewai"],
+            "metadata": {
+                "framework": "crewai",
+                "tool_name": self._tool_name,
+                **metadata,
+            },
+            "action_id": action_id or action_id_for("crewai", self._tool_name),
+        }
+
+    @property
+    def name(self) -> str:
+        return self._tool_name
+
+    @property
+    def description(self) -> str | None:
+        description = getattr(self._tool, "description", None)
+        return str(description) if description is not None else None
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._tool, name)
+
+    def _guard(self, method_name: str, *args: Any, **kwargs: Any) -> Any:
+        method = getattr(self._tool, method_name)
+
+        @self._client.intercept(**self._config)
+        def guarded_call() -> Any:
+            return method(*args, **kwargs)
+
+        return guarded_call()
+
+    def run(self, *args: Any, **kwargs: Any) -> Any:
+        if hasattr(self._tool, "run"):
+            return self._guard("run", *args, **kwargs)
+        return self.__call__(*args, **kwargs)
+
+    def _run(self, *args: Any, **kwargs: Any) -> Any:
+        if hasattr(self._tool, "_run"):
+            return self._guard("_run", *args, **kwargs)
+        return self.__call__(*args, **kwargs)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self._guard("__call__", *args, **kwargs)
+
+
+def secure_crewai_tool(
+    tool: Any,
+    *,
+    intent_id: str,
+    risk_level: str = "LOW",
+    operation_class: str = "tool_call",
+    data_sensitivity: str = "internal",
+    systems_touched: list[str] | None = None,
+    client: Client | None = None,
+    action_id: str | None = None,
+    **metadata: Any,
+) -> SernixaCrewAITool:
+    """Wrap an existing CrewAI tool object/callable with Sernixa."""
+    return SernixaCrewAITool(
+        tool,
+        intent_id=intent_id,
+        risk_level=risk_level,
+        operation_class=operation_class,
+        data_sensitivity=data_sensitivity,
+        systems_touched=systems_touched,
+        client=client,
+        action_id=action_id,
+        **metadata,
+    )

sernixa/adapters/langchain.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+from sernixa.client import Client
+
+from ._common import action_id_for, callable_name, secure_callable
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def langchain_tool(
+    *,
+    intent_id: str,
+    risk_level: str = "LOW",
+    operation_class: str = "tool_call",
+    data_sensitivity: str = "internal",
+    systems_touched: list[str] | None = None,
+    client: Client | None = None,
+    action_id: str | None = None,
+    **metadata: Any,
+) -> Callable[[F], F]:
+    """Wrap a LangChain tool function before or after `@tool` decoration."""
+    return secure_callable(
+        client=client,
+        intent_id=intent_id,
+        risk_level=risk_level,
+        operation_class=operation_class,
+        data_sensitivity=data_sensitivity,
+        systems_touched=systems_touched,
+        framework="langchain",
+        action_id=action_id,
+        **metadata,
+    )
+
+
+class SernixaLangChainTool:
+    """Proxy for LangChain-style tools.
+
+    The proxy intentionally depends only on LangChain's public calling shapes
+    (`invoke`, `ainvoke`, `run`, `arun`, and `__call__`) so the SDK remains
+    usable without importing LangChain at runtime.
+    """
+
+    def __init__(
+        self,
+        tool: Any,
+        *,
+        intent_id: str,
+        risk_level: str = "LOW",
+        operation_class: str = "tool_call",
+        data_sensitivity: str = "internal",
+        systems_touched: list[str] | None = None,
+        client: Client | None = None,
+        action_id: str | None = None,
+        **metadata: Any,
+    ) -> None:
+        self._tool = tool
+        self._client = client or Client()
+        self._tool_name = callable_name(tool, "langchain-tool")
+        self._config = {
+            "intent_id": intent_id,
+            "risk_level": risk_level,
+            "operation_class": operation_class,
+            "data_sensitivity": data_sensitivity,
+            "systems_touched": systems_touched or ["langchain"],
+            "metadata": {
+                "framework": "langchain",
+                "tool_name": self._tool_name,
+                **metadata,
+            },
+            "action_id": action_id or action_id_for("langchain", self._tool_name),
+        }
+
+    @property
+    def name(self) -> str:
+        return self._tool_name
+
+    @property
+    def description(self) -> str | None:
+        description = getattr(self._tool, "description", None)
+        return str(description) if description is not None else None
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._tool, name)
+
+    def _guard(self, method_name: str, *args: Any, **kwargs: Any) -> Any:
+        method = getattr(self._tool, method_name)
+
+        @self._client.intercept(**self._config)
+        def guarded_call() -> Any:
+            return method(*args, **kwargs)
+
+        return guarded_call()
+
+    async def _aguard(self, method_name: str, *args: Any, **kwargs: Any) -> Any:
+        method = getattr(self._tool, method_name)
+
+        @self._client.intercept(**self._config)
+        async def guarded_call() -> Any:
+            return await method(*args, **kwargs)
+
+        return await guarded_call()
+
+    def invoke(self, input: Any, config: Any | None = None, **kwargs: Any) -> Any:
+        return self._guard("invoke", input, config=config, **kwargs)
+
+    async def ainvoke(self, input: Any, config: Any | None = None, **kwargs: Any) -> Any:
+        return await self._aguard("ainvoke", input, config=config, **kwargs)
+
+    def run(self, *args: Any, **kwargs: Any) -> Any:
+        return self._guard("run", *args, **kwargs)
+
+    async def arun(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._aguard("arun", *args, **kwargs)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        if hasattr(self._tool, "invoke"):
+            return self.invoke(*args, **kwargs)
+        return self._guard("__call__", *args, **kwargs)
+
+
+def secure_langchain_tool(
+    tool: Any,
+    *,
+    intent_id: str,
+    risk_level: str = "LOW",
+    operation_class: str = "tool_call",
+    data_sensitivity: str = "internal",
+    systems_touched: list[str] | None = None,
+    client: Client | None = None,
+    action_id: str | None = None,
+    **metadata: Any,
+) -> SernixaLangChainTool:
+    """Wrap an existing LangChain BaseTool/Runnable-style object with Sernixa."""
+    return SernixaLangChainTool(
+        tool,
+        intent_id=intent_id,
+        risk_level=risk_level,
+        operation_class=operation_class,
+        data_sensitivity=data_sensitivity,
+        systems_touched=systems_touched,
+        client=client,
+        action_id=action_id,
+        **metadata,
+    )

sernixa/adapters/mcp.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, TypeVar
+
+from sernixa.client import Client, safe_serialize
+
+from ._common import action_id_for, is_awaitable, secure_callable
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass(frozen=True)
+class McpInvocationContext:
+    """Metadata Sernixa records at an MCP-style tool boundary.
+
+    This is not a full MCP protocol server. It is a small, explicit shape for
+    guarding the moment a host or agent invokes a tool exposed through MCP-like
+    routing.
+    """
+
+    server_name: str
+    tool_name: str
+    toolset_id: str | None = None
+    client_name: str | None = None
+    session_id: str | None = None
+    request_id: str | None = None
+    resource_hints: list[str] = field(default_factory=list)
+
+    def to_metadata(self, arguments: Any | None = None) -> dict[str, Any]:
+        metadata: dict[str, Any] = {
+            "mcp_server": self.server_name,
+            "mcp_tool": self.tool_name,
+            "mcp_toolset_id": self.toolset_id,
+            "mcp_client": self.client_name,
+            "mcp_session_id": self.session_id,
+            "mcp_request_id": self.request_id,
+            "mcp_resource_hints": list(self.resource_hints),
+        }
+        if arguments is not None:
+            metadata["mcp_arguments"] = safe_serialize(arguments)
+        return {key: value for key, value in metadata.items() if value not in (None, [], {})}
+
+
+def mcp_tool(
+    *,
+    intent_id: str,
+    server_name: str,
+    tool_name: str,
+    risk_level: str = "LOW",
+    operation_class: str = "tool_call",
+    data_sensitivity: str = "internal",
+    systems_touched: list[str] | None = None,
+    client: Client | None = None,
+    toolset_id: str | None = None,
+    **metadata: Any,
+) -> Callable[[F], F]:
+    """Decorate an MCP-style tool handler with Sernixa governance."""
+    context = McpInvocationContext(
+        server_name=server_name,
+        tool_name=tool_name,
+        toolset_id=toolset_id,
+    )
+    return secure_callable(
+        client=client,
+        intent_id=intent_id,
+        risk_level=risk_level,
+        operation_class=operation_class,
+        data_sensitivity=data_sensitivity,
+        systems_touched=systems_touched or [server_name],
+        framework="mcp",
+        action_id=action_id_for("mcp", f"{server_name}.{tool_name}"),
+        **context.to_metadata(),
+        **metadata,
+    )
+
+
+class McpToolBoundary:
+    """Guard explicit MCP-style tool invocations.
+
+    Use this at the MCP host/router boundary, before dispatching a tool call to
+    the underlying tool implementation.
+    """
+
+    def __init__(
+        self,
+        *,
+        client: Client | None = None,
+        server_name: str,
+        toolset_id: str | None = None,
+        systems_touched: list[str] | None = None,
+    ) -> None:
+        self.client = client or Client()
+        self.server_name = server_name
+        self.toolset_id = toolset_id
+        self.systems_touched = systems_touched or [server_name]
+
+    def invoke(
+        self,
+        *,
+        tool_name: str,
+        arguments: dict[str, Any] | None,
+        handler: Callable[..., Any],
+        intent_id: str,
+        risk_level: str = "LOW",
+        operation_class: str = "tool_call",
+        data_sensitivity: str = "internal",
+        client_name: str | None = None,
+        session_id: str | None = None,
+        request_id: str | None = None,
+        resource_hints: list[str] | None = None,
+        **metadata: Any,
+    ) -> Any:
+        context = McpInvocationContext(
+            server_name=self.server_name,
+            tool_name=tool_name,
+            toolset_id=self.toolset_id,
+            client_name=client_name,
+            session_id=session_id,
+            request_id=request_id,
+            resource_hints=resource_hints or [],
+        )
+
+        @self.client.intercept(
+            intent_id=intent_id,
+            risk_level=risk_level,
+            operation_class=operation_class,
+            data_sensitivity=data_sensitivity,
+            systems_touched=self.systems_touched,
+            metadata={"framework": "mcp", **context.to_metadata(arguments), **metadata},
+            action_id=action_id_for("mcp", f"{self.server_name}.{tool_name}"),
+        )
+        def guarded_call() -> Any:
+            return handler(**(arguments or {}))
+
+        return guarded_call()
+
+    async def ainvoke(
+        self,
+        *,
+        tool_name: str,
+        arguments: dict[str, Any] | None,
+        handler: Callable[..., Any],
+        intent_id: str,
+        risk_level: str = "LOW",
+        operation_class: str = "tool_call",
+        data_sensitivity: str = "internal",
+        client_name: str | None = None,
+        session_id: str | None = None,
+        request_id: str | None = None,
+        resource_hints: list[str] | None = None,
+        **metadata: Any,
+    ) -> Any:
+        context = McpInvocationContext(
+            server_name=self.server_name,
+            tool_name=tool_name,
+            toolset_id=self.toolset_id,
+            client_name=client_name,
+            session_id=session_id,
+            request_id=request_id,
+            resource_hints=resource_hints or [],
+        )
+
+        @self.client.intercept(
+            intent_id=intent_id,
+            risk_level=risk_level,
+            operation_class=operation_class,
+            data_sensitivity=data_sensitivity,
+            systems_touched=self.systems_touched,
+            metadata={"framework": "mcp", **context.to_metadata(arguments), **metadata},
+            action_id=action_id_for("mcp", f"{self.server_name}.{tool_name}"),
+        )
+        async def guarded_call() -> Any:
+            result = handler(**(arguments or {}))
+            if is_awaitable(result):
+                return await result
+            return result
+
+        return await guarded_call()