deepintshield 1.0.0__py3-none-any.whl

deepintshield/__init__.py

@@ -0,0 +1,54 @@
+"""
+DeepintShield — unified Python SDK.
+
+Quick start
+-----------
+
+    from deepintshield import DeepintShield
+
+    shield = DeepintShield(virtual_key="sk-...")
+    openai_client = shield.openai()
+    response = openai_client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "hello"}],
+    )
+
+The gateway defaults to ``https://app.deepintshield.com`` and is overridable via
+``base_url=...`` or the ``DEEPINTSHIELD_BASE_URL`` env var.
+"""
+
+from .client import DeepintShield
+from .config import DEFAULT_BASE_URL, ShieldConfig
+from .errors import DeepintShieldBlockedError, DeepintShieldError
+from .rag import allowed_chunk_ids, build_chunk, filter_chunks
+from .types import (
+    NON_BLOCKING_DECISIONS,
+    GuardrailDecision,
+    GuardrailResult,
+    GuardrailStage,
+    RetrievedChunk,
+    ToolInvocation,
+)
+from .version import __version__
+
+# Backwards-compatible alias.
+DeepintShieldClient = DeepintShield
+
+__all__ = [
+    "__version__",
+    "DEFAULT_BASE_URL",
+    "DeepintShield",
+    "DeepintShieldClient",
+    "DeepintShieldBlockedError",
+    "DeepintShieldError",
+    "GuardrailDecision",
+    "GuardrailResult",
+    "GuardrailStage",
+    "NON_BLOCKING_DECISIONS",
+    "RetrievedChunk",
+    "ShieldConfig",
+    "ToolInvocation",
+    "allowed_chunk_ids",
+    "build_chunk",
+    "filter_chunks",
+]

deepintshield/agent.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import functools
+import json
+from typing import TYPE_CHECKING, Any, Callable, Mapping
+
+from .errors import DeepintShieldBlockedError
+from .types import GuardrailResult, ToolInvocation
+
+if TYPE_CHECKING:
+    from .client import DeepintShield
+
+
+class AgentSurface:
+    """
+    Agentic guardrails: input/output scanning plus tool/MCP evaluation.
+
+    >>> shield = DeepintShield.from_env()
+    >>>
+    >>> @shield.agent.tool
+    >>> def read_file(path: str) -> str: ...
+    >>>
+    >>> shield.agent.check_input("user message")
+    >>> shield.agent.check_output("assistant reply")
+    >>> shield.agent.evaluate_tool(name="read_file", args={"path": "/tmp"})
+    """
+
+    def __init__(self, client: "DeepintShield") -> None:
+        self._client = client
+
+    # ── stage helpers ────────────────────────────────────────────────────────
+
+    def check_input(self, text: str, **kwargs: Any) -> GuardrailResult:
+        return self._client.guard(stage="input", input=text, **kwargs)
+
+    def check_output(self, text: str, **kwargs: Any) -> GuardrailResult:
+        return self._client.guard(stage="output", output=text, **kwargs)
+
+    # ── tool invocation ─────────────────────────────────────────────────────
+
+    def evaluate_tool(
+        self,
+        invocation: ToolInvocation | Mapping[str, Any] | None = None,
+        *,
+        name: str | None = None,
+        args: Any = None,
+        server_label: str = "",
+        action_class: str = "read",
+        domains: list[str] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        actor_type: str = "agent",
+        raise_on_block: bool = True,
+        **kwargs: Any,
+    ) -> GuardrailResult:
+        if invocation is None:
+            if name is None:
+                raise ValueError("evaluate_tool requires either invocation or name=...")
+            invocation = ToolInvocation(
+                tool_name=name,
+                tool_input=args if args is not None else {},
+                server_label=server_label,
+                action_class=action_class,
+                domains=list(domains or []),
+                metadata=dict(metadata or {}),
+            )
+        tool = invocation if isinstance(invocation, ToolInvocation) else ToolInvocation(**dict(invocation))
+        tool_input = (
+            tool.tool_input
+            if isinstance(tool.tool_input, str)
+            else json.dumps(tool.tool_input, default=str, sort_keys=True)
+        )
+        return self._client.guard(
+            stage="mcp" if tool.server_label else "action",
+            actor_type=actor_type,
+            tool_input=tool_input,
+            server_label=tool.server_label or None,
+            tool_name=tool.tool_name,
+            action_class=tool.action_class,
+            domains=tool.domains,
+            metadata=tool.metadata,
+            raise_on_block=raise_on_block,
+            **kwargs,
+        )
+
+    # ── decorator ───────────────────────────────────────────────────────────
+
+    def tool(
+        self,
+        func: Callable | None = None,
+        *,
+        action_class: str = "read",
+        server_label: str = "",
+        name: str | None = None,
+    ) -> Callable:
+        """
+        Decorator that guards a function call through DeepintShield before execution.
+
+        >>> @shield.agent.tool(action_class="write")
+        ... def write_file(path: str, content: str) -> None: ...
+        """
+
+        def decorate(fn: Callable) -> Callable:
+            tool_name = name or fn.__name__
+
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                self.evaluate_tool(
+                    name=tool_name,
+                    args={"args": list(args), "kwargs": dict(kwargs)},
+                    action_class=action_class,
+                    server_label=server_label,
+                )
+                return fn(*args, **kwargs)
+
+            return wrapper
+
+        if func is not None and callable(func):
+            return decorate(func)
+        return decorate
+
+    # ── full loop helper ────────────────────────────────────────────────────
+
+    def guard_turn(
+        self,
+        *,
+        user_input: str,
+        model_output: str | None = None,
+        tool_calls: list[Mapping[str, Any]] | None = None,
+        raise_on_block: bool = True,
+    ) -> dict[str, GuardrailResult]:
+        """
+        Evaluate a single agent turn: input, tool calls (if any), output (if any).
+        Returns a dict of stage -> result.
+        """
+        results: dict[str, GuardrailResult] = {}
+        results["input"] = self.check_input(user_input, **{"raise_on_block": raise_on_block})  # type: ignore[arg-type]
+        for call in tool_calls or []:
+            key = f"tool:{call.get('name') or call.get('tool_name')}"
+            results[key] = self.evaluate_tool(
+                name=call.get("name") or call.get("tool_name", "unknown"),
+                args=call.get("args") or call.get("tool_input"),
+                action_class=call.get("action_class", "read"),
+                server_label=call.get("server_label", ""),
+                raise_on_block=raise_on_block,
+            )
+        if model_output is not None:
+            results["output"] = self.check_output(model_output, raise_on_block=raise_on_block)
+        return results

deepintshield/client.py

@@ -0,0 +1,291 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Iterable, Mapping
+
+import httpx
+
+from .config import DEFAULT_BASE_URL, ShieldConfig
+from .errors import DeepintShieldBlockedError, DeepintShieldError
+from .types import GuardrailResult, RetrievedChunk, ToolInvocation
+
+
+class DeepintShield:
+    """
+    Unified DeepintShield client.
+
+    >>> shield = DeepintShield(virtual_key="sk-...")
+    >>> openai = shield.openai()               # native openai.OpenAI pointed at the gateway
+    >>> resp = shield.chat(model="gpt-4o-mini", messages=[...])
+    >>> shield.rag.filter(query="...", chunks=[...])
+    >>> shield.agent.evaluate_tool(name="read_file", args={"path": "/tmp"})
+    """
+
+    def __init__(
+        self,
+        virtual_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        default_headers: Mapping[str, str] | None = None,
+        app_name: str = "deepintshield",
+        agent_name: str = "deepintshield-agent",
+        requester: str = "sdk-user",
+        requester_role: str = "member",
+        persist: bool = True,
+    ) -> None:
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.virtual_key = (virtual_key or "").strip() or None
+        self.timeout = timeout
+        self.default_headers = dict(default_headers or {})
+        self.app_name = app_name
+        self.agent_name = agent_name
+        self.requester = requester
+        self.requester_role = requester_role
+        self.persist = persist
+        self._client = httpx.Client(timeout=timeout)
+
+        from .rag import RAGSurface
+        from .agent import AgentSurface
+        from .providers import ProviderRegistry
+
+        self.rag = RAGSurface(self)
+        self.agent = AgentSurface(self)
+        self.providers = ProviderRegistry(self)
+
+    # ─────────────────────────── constructors / context ──────────────────────
+
+    @classmethod
+    def from_env(cls) -> "DeepintShield":
+        cfg = ShieldConfig.from_env()
+        return cls(
+            virtual_key=cfg.virtual_key,
+            base_url=cfg.base_url,
+            timeout=cfg.timeout,
+            app_name=cfg.app_name,
+            agent_name=cfg.agent_name,
+            requester=cfg.requester,
+            requester_role=cfg.requester_role,
+            persist=cfg.persist,
+        )
+
+    @classmethod
+    def from_config(cls, config: ShieldConfig) -> "DeepintShield":
+        return cls(
+            virtual_key=config.virtual_key,
+            base_url=config.base_url,
+            timeout=config.timeout,
+            default_headers=config.default_headers,
+            app_name=config.app_name,
+            agent_name=config.agent_name,
+            requester=config.requester,
+            requester_role=config.requester_role,
+            persist=config.persist,
+        )
+
+    def __enter__(self) -> "DeepintShield":
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ─────────────────────────── keys and headers ────────────────────────────
+
+    def virtual_key_or_raise(self) -> str:
+        if not self.virtual_key:
+            raise DeepintShieldError("DEEPINTSHIELD_VIRTUAL_KEY is required")
+        return self.virtual_key
+
+    def api_key(self) -> str:
+        return self.virtual_key_or_raise()
+
+    def headers(self, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+        out = {"content-type": "application/json", **self.default_headers}
+        if self.virtual_key:
+            out["x-bf-vk"] = self.virtual_key
+        if extra:
+            out.update(dict(extra))
+        return out
+
+    # ─────────────────────────── provider endpoints ──────────────────────────
+
+    def endpoint(self, provider: str) -> str:
+        return f"{self.base_url}/{provider.strip('/')}"
+
+    def openai_base_url(self) -> str:
+        return self.endpoint("openai")
+
+    def anthropic_base_url(self) -> str:
+        return self.endpoint("anthropic")
+
+    def bedrock_endpoint_url(self) -> str:
+        return self.endpoint("bedrock")
+
+    def genai_base_url(self) -> str:
+        return self.endpoint("genai")
+
+    def langchain_base_url(self) -> str:
+        return self.endpoint("langchain")
+
+    def litellm_base_url(self) -> str:
+        return self.endpoint("litellm")
+
+    def pydanticai_base_url(self) -> str:
+        return self.endpoint("pydanticai")
+
+    def openai_passthrough_base_url(self) -> str:
+        return f"{self.base_url}/openai_passthrough/v1"
+
+    def anthropic_passthrough_base_url(self) -> str:
+        return f"{self.base_url}/anthropic_passthrough"
+
+    def genai_passthrough_base_url(self) -> str:
+        return f"{self.base_url}/genai_passthrough"
+
+    # ─────────────────────────── provider shortcuts ──────────────────────────
+
+    def openai(self, *, passthrough: bool = False, **kwargs: Any):
+        from .providers.openai import build_client
+        return build_client(self, passthrough=passthrough, **kwargs)
+
+    def anthropic(self, *, passthrough: bool = False, **kwargs: Any):
+        from .providers.anthropic import build_client
+        return build_client(self, passthrough=passthrough, **kwargs)
+
+    def bedrock(self, **kwargs: Any):
+        from .providers.bedrock import build_client
+        return build_client(self, **kwargs)
+
+    def genai(self, *, passthrough: bool = False, **kwargs: Any):
+        from .providers.genai import build_client
+        return build_client(self, passthrough=passthrough, **kwargs)
+
+    def langchain(self, model: str = "gpt-4o-mini", **kwargs: Any):
+        from .providers.langchain import build_client
+        return build_client(self, model=model, **kwargs)
+
+    def langgraph(self):
+        from .providers.langgraph import LangGraphShield
+        return LangGraphShield(self)
+
+    def litellm(self):
+        from .providers.litellm import LiteLLMShield
+        return LiteLLMShield(self)
+
+    def pydanticai(self, model: str = "gpt-4o-mini", **kwargs: Any):
+        from .providers.pydanticai import build_agent
+        return build_agent(self, model=model, **kwargs)
+
+    # ─────────────────────────── HTTP + guardrails ───────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Mapping[str, Any] | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        response = self._client.request(
+            method=method,
+            url=f"{self.base_url}{path}",
+            headers=self.headers(extra_headers),
+            json=json_body,
+        )
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = {"raw": response.text}
+        if response.status_code >= 400:
+            raise DeepintShieldError.from_response(response.status_code, payload)
+        return payload
+
+    def chat(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        stream: bool = False,
+        extra_headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Unified chat completion via the gateway OpenAI-compatible endpoint."""
+        return self.request(
+            "POST",
+            "/v1/chat/completions",
+            json_body={"model": model, "messages": messages, "stream": stream, **kwargs},
+            extra_headers=extra_headers,
+        )
+
+    def evaluate_guardrail(
+        self,
+        *,
+        stage: str,
+        actor_type: str = "sdk_user",
+        actor_id: str | None = None,
+        actor_role: str | None = None,
+        actor_customer_id: str | None = None,
+        actor_team_id: str | None = None,
+        model: str | None = None,
+        provider: str | None = None,
+        input: str | None = None,
+        output: str | None = None,
+        tool_input: str | None = None,
+        server_label: str | None = None,
+        tool_name: str | None = None,
+        action_class: str | None = None,
+        domains: list[str] | None = None,
+        app_name: str | None = None,
+        agent_name: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        persist: bool | None = None,
+    ) -> GuardrailResult:
+        body: dict[str, Any] = {
+            "stage": stage,
+            "actor_type": actor_type,
+            "actor_id": actor_id or self.requester,
+            "actor_role": actor_role or self.requester_role,
+            "model": model,
+            "provider": provider,
+            "input": input,
+            "output": output,
+            "tool_input": tool_input,
+            "server_label": server_label,
+            "tool_name": tool_name,
+            "action_class": action_class,
+            "domains": domains or [],
+            "app_name": app_name or self.app_name,
+            "agent_name": agent_name or self.agent_name,
+            "persist": self.persist if persist is None else persist,
+        }
+        if actor_customer_id:
+            body["actor_customer_id"] = actor_customer_id
+        if actor_team_id:
+            body["actor_team_id"] = actor_team_id
+        if metadata:
+            body["metadata"] = dict(metadata)
+        payload = self.request("POST", "/api/guardrails/evaluate", json_body=body)
+        return GuardrailResult.from_response(stage, payload)
+
+    def guard(
+        self,
+        *,
+        stage: str,
+        raise_on_block: bool = True,
+        **kwargs: Any,
+    ) -> GuardrailResult:
+        """Evaluate a guardrail and optionally raise on block."""
+        result = self.evaluate_guardrail(stage=stage, **kwargs)
+        if raise_on_block and result.blocked:
+            raise DeepintShieldBlockedError(
+                f"DeepintShield blocked at stage={stage}: {result.reason or result.decision}",
+                stage=stage,
+                decision=result.decision,
+                reason=result.reason,
+                payload=result.raw,
+            )
+        return result

deepintshield/config.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+DEFAULT_BASE_URL = "https://app.deepintshield.com"
+
+
+@dataclass(slots=True)
+class ShieldConfig:
+    virtual_key: str = ""
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = 30.0
+    app_name: str = "deepintshield"
+    agent_name: str = "deepintshield-agent"
+    requester: str = "sdk-user"
+    requester_role: str = "member"
+    persist: bool = True
+    default_headers: dict[str, str] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_env(cls) -> "ShieldConfig":
+        return cls(
+            virtual_key=(os.getenv("DEEPINTSHIELD_VIRTUAL_KEY") or "").strip(),
+            base_url=os.getenv("DEEPINTSHIELD_BASE_URL", DEFAULT_BASE_URL).rstrip("/"),
+            timeout=float(os.getenv("DEEPINTSHIELD_TIMEOUT", "30")),
+            app_name=os.getenv("DEEPINTSHIELD_APP_NAME", "deepintshield"),
+            agent_name=os.getenv("DEEPINTSHIELD_AGENT_NAME", "deepintshield-agent"),
+            requester=os.getenv("DEEPINTSHIELD_REQUESTER", "sdk-user"),
+            requester_role=os.getenv("DEEPINTSHIELD_REQUESTER_ROLE", "member"),
+            persist=os.getenv("DEEPINTSHIELD_PERSIST", "true").lower() not in {"0", "false", "no"},
+        )

deepintshield/errors.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class DeepintShieldError(Exception):
+    def __init__(self, message: str, status_code: int | None = None, payload: dict | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.payload = payload or {}
+
+    @classmethod
+    def from_response(cls, status_code: int, payload: dict | None) -> "DeepintShieldError":
+        error = (payload or {}).get("error", {})
+        message = (
+            error.get("message")
+            or (payload or {}).get("message")
+            or f"DeepintShield request failed with status {status_code}"
+        )
+        return cls(message=message, status_code=status_code, payload=payload or {})
+
+
+class DeepintShieldBlockedError(DeepintShieldError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        stage: str | None = None,
+        decision: str | None = None,
+        reason: str | None = None,
+        status_code: int | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message=message, status_code=status_code, payload=payload)
+        self.stage = stage
+        self.decision = decision
+        self.reason = reason

deepintshield/providers/__init__.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..client import DeepintShield
+
+
+class ProviderRegistry:
+    """Lazy accessor for provider builders, so optional deps stay optional."""
+
+    def __init__(self, client: "DeepintShield") -> None:
+        self._client = client
+
+    def openai(self, **kwargs: Any):
+        from . import openai as mod
+        return mod.build_client(self._client, **kwargs)
+
+    def anthropic(self, **kwargs: Any):
+        from . import anthropic as mod
+        return mod.build_client(self._client, **kwargs)
+
+    def bedrock(self, **kwargs: Any):
+        from . import bedrock as mod
+        return mod.build_client(self._client, **kwargs)
+
+    def genai(self, **kwargs: Any):
+        from . import genai as mod
+        return mod.build_client(self._client, **kwargs)
+
+    def langchain(self, **kwargs: Any):
+        from . import langchain as mod
+        return mod.build_client(self._client, **kwargs)
+
+    def langgraph(self):
+        from .langgraph import LangGraphShield
+        return LangGraphShield(self._client)
+
+    def litellm(self):
+        from .litellm import LiteLLMShield
+        return LiteLLMShield(self._client)
+
+    def pydanticai(self, **kwargs: Any):
+        from . import pydanticai as mod
+        return mod.build_agent(self._client, **kwargs)
+
+
+__all__ = ["ProviderRegistry"]

deepintshield/providers/anthropic.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..client import DeepintShield
+
+
+def build_client(shield: "DeepintShield", *, passthrough: bool = False, **kwargs: Any):
+    """Return a native ``anthropic.Anthropic`` client pointed at the gateway."""
+    try:
+        import anthropic
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError("Install anthropic: pip install 'deepintshield[anthropic]'") from exc
+
+    base_url = shield.anthropic_passthrough_base_url() if passthrough else shield.anthropic_base_url()
+    return anthropic.Anthropic(
+        base_url=kwargs.pop("base_url", base_url),
+        api_key=kwargs.pop("api_key", shield.api_key()),
+        default_headers={**shield.headers(), **(kwargs.pop("default_headers", None) or {})},
+        **kwargs,
+    )

deepintshield/providers/bedrock.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..client import DeepintShield
+
+
+def build_client(shield: "DeepintShield", *, region_name: str | None = None, **kwargs: Any):
+    """Return a boto3 ``bedrock-runtime`` client routed through the gateway."""
+    try:
+        import boto3
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError("Install boto3: pip install 'deepintshield[bedrock]'") from exc
+
+    key = shield.api_key()
+    client = boto3.client(
+        service_name="bedrock-runtime",
+        endpoint_url=kwargs.pop("endpoint_url", shield.bedrock_endpoint_url()),
+        region_name=region_name or os.getenv("AWS_REGION", "us-west-2"),
+        aws_access_key_id=kwargs.pop("aws_access_key_id", key),
+        aws_secret_access_key=kwargs.pop("aws_secret_access_key", key),
+        **kwargs,
+    )
+    headers = shield.headers()
+
+    def _inject_headers(request, **_kwargs):
+        for name, value in headers.items():
+            request.headers.add_header(name, value)
+
+    client.meta.events.register_first("before-sign.bedrock-runtime.*", _inject_headers)
+    return client