strands-deepkeep 0.1.0__py3-none-any.whl

strands_deepkeep/__init__.py

@@ -0,0 +1,13 @@
+"""DeepKeep AI Firewall hooks for Strands Agents."""
+
+from strands_deepkeep.guardrail import (
+    DeepKeepAPIError,
+    DeepKeepClient,
+    DeepKeepGuardrail,
+)
+
+__all__ = [
+    "DeepKeepAPIError",
+    "DeepKeepClient",
+    "DeepKeepGuardrail",
+]

strands_deepkeep/guardrail.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+try:
+    from strands.plugins import Plugin
+except ModuleNotFoundError:  # pragma: no cover - used only when Strands is not installed in a test environment.
+    class Plugin:  # type: ignore[no-redef]
+        def __init__(self) -> None:
+            pass
+
+
+class DeepKeepAPIError(Exception):
+    """Raised when the DeepKeep API returns an error or a network request fails."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class DeepKeepClient:
+    """HTTP client for DeepKeep OpenAI-compatible moderation endpoints."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("DEEPKEEP_API_KEY")
+        self.base_url = (base_url or os.environ.get("DEEPKEEP_BASE_URL") or "").rstrip("/")
+        self.timeout = timeout
+
+        if not self.api_key:
+            raise ValueError("DeepKeep API key is required. Pass api_key or set DEEPKEEP_API_KEY.")
+        if not self.base_url:
+            raise ValueError("DeepKeep base URL is required. Pass base_url or set DEEPKEEP_BASE_URL.")
+
+    def pre_moderate(
+        self,
+        *,
+        model: str,
+        input: str | list[str],
+        title: str = "",
+        chat: str = "",
+    ) -> dict[str, Any]:
+        return self._post(
+            "/api/v3/openai/moderations/pre",
+            {"model": model, "input": input, "title": title, "chat": chat},
+        )
+
+    def post_moderate(
+        self,
+        *,
+        model: str,
+        output: str | list[str],
+        title: str = "",
+        chat: str = "",
+    ) -> dict[str, Any]:
+        return self._post(
+            "/api/v3/openai/moderations/post",
+            {"model": model, "output": output, "title": title, "chat": chat},
+        )
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.post(
+                    f"{self.base_url}{path}",
+                    headers={"X-API-Key": self.api_key},
+                    json=payload,
+                )
+        except httpx.RequestError as exc:
+            raise DeepKeepAPIError(f"DeepKeep network error: {exc}") from exc
+
+        if response.status_code >= 400:
+            raise DeepKeepAPIError(
+                f"DeepKeep API error {response.status_code}: {response.text}",
+                status_code=response.status_code,
+            )
+
+        return response.json()
+
+
+class DeepKeepGuardrail(Plugin):
+    """Strands hook provider that applies DeepKeep pre- and post-moderation."""
+
+    @property
+    def name(self) -> str:
+        return "deepkeep-guardrail"
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        pre_model: str | None = None,
+        post_model: str | None = None,
+        title: str = "",
+        chat: str = "",
+        timeout: float = 30.0,
+        block_message: str = "DeepKeep blocked this content.",
+    ) -> None:
+        if not pre_model and not post_model:
+            raise ValueError("At least one of pre_model or post_model is required.")
+
+        super().__init__()
+
+        self.client = DeepKeepClient(api_key=api_key, base_url=base_url, timeout=timeout)
+        self.pre_model = pre_model
+        self.post_model = post_model
+        self.title = title
+        self.chat = chat
+        self.block_message = block_message
+
+    def register_hooks(self, registry: Any) -> None:
+        from strands.hooks import AfterModelCallEvent, BeforeInvocationEvent
+
+        if self.pre_model:
+            registry.add_callback(BeforeInvocationEvent, self.before_invocation)
+        if self.post_model:
+            registry.add_callback(AfterModelCallEvent, self.after_model_call)
+
+    def init_agent(self, agent: Any) -> None:
+        from strands.hooks import AfterModelCallEvent, BeforeInvocationEvent
+
+        if self.pre_model:
+            agent.add_hook(self.before_invocation, BeforeInvocationEvent)
+        if self.post_model:
+            agent.add_hook(self.after_model_call, AfterModelCallEvent)
+
+    def before_invocation(self, event: Any) -> None:
+        messages = getattr(event, "messages", None)
+        content = _last_user_text(messages)
+        result = self.client.pre_moderate(
+            model=self.pre_model or "",
+            input=content,
+            title=self.title,
+            chat=self.chat,
+        )
+        _store_decision(event, "deepkeep_pre", result)
+
+        action = _highest_priority_action(result)
+        if action == "block":
+            event.cancel = self.block_message
+        elif action in {"redact", "modify"} and messages is not None:
+            event.messages = _replace_last_user_text(messages, _modified_content(result))
+
+    def after_model_call(self, event: Any) -> None:
+        stop_response = getattr(event, "stop_response", None)
+        message = getattr(stop_response, "message", None)
+        content = _message_text(message)
+        result = self.client.post_moderate(
+            model=self.post_model or "",
+            output=content,
+            title=self.title,
+            chat=self.chat,
+        )
+        _store_decision(event, "deepkeep_post", result)
+
+        action = _highest_priority_action(result)
+        if action == "block" and message is not None:
+            _replace_message_text(message, "")
+            _add_message_metadata(message, result)
+        elif action in {"redact", "modify"} and message is not None:
+            _replace_message_text(message, _modified_content(result))
+            _add_message_metadata(message, result)
+
+
+def _store_decision(event: Any, key: str, result: dict[str, Any]) -> None:
+    invocation_state = getattr(event, "invocation_state", None)
+    if isinstance(invocation_state, dict):
+        invocation_state[key] = result
+
+
+def _last_user_text(messages: Any) -> str:
+    if not messages:
+        return ""
+    for message in reversed(messages):
+        if isinstance(message, dict) and message.get("role") == "user":
+            return _message_text(message)
+    return _message_text(messages[-1])
+
+
+def _message_text(message: Any) -> str:
+    if not isinstance(message, dict):
+        return ""
+    parts: list[str] = []
+    for block in message.get("content", []):
+        if isinstance(block, dict) and isinstance(block.get("text"), str):
+            parts.append(block["text"])
+    return "\n".join(parts)
+
+
+def _replace_last_user_text(messages: list[dict[str, Any]], text: str) -> list[dict[str, Any]]:
+    updated = [dict(message) for message in messages]
+    for index in range(len(updated) - 1, -1, -1):
+        if updated[index].get("role") == "user":
+            _replace_message_text(updated[index], text)
+            return updated
+    if updated:
+        _replace_message_text(updated[-1], text)
+    return updated
+
+
+def _replace_message_text(message: dict[str, Any], text: str) -> None:
+    content = message.get("content")
+    if not isinstance(content, list):
+        message["content"] = [{"text": text}]
+        return
+
+    for block in content:
+        if isinstance(block, dict) and "text" in block:
+            block["text"] = text
+            return
+    content.insert(0, {"text": text})
+
+
+def _add_message_metadata(message: dict[str, Any], result: dict[str, Any]) -> None:
+    metadata = message.setdefault("metadata", {})
+    custom = metadata.setdefault("custom", {})
+    custom["deepkeep"] = result
+
+
+def _highest_priority_action(result: dict[str, Any]) -> str | None:
+    priority = {"block": 3, "redact": 2, "modify": 2, "alert": 1}
+    selected: str | None = None
+    for item in result.get("verbosity", []):
+        action = item.get("details", {}).get("guardrail_action")
+        if action in priority and (selected is None or priority[action] > priority[selected]):
+            selected = action
+    return selected
+
+
+def _modified_content(result: dict[str, Any]) -> str:
+    modified_content: str | None = None
+    for item in result.get("verbosity", []):
+        for modified in item.get("details", {}).get("modified", []):
+            content = modified.get("content")
+            if isinstance(content, str):
+                modified_content = content
+    if modified_content is not None:
+        return modified_content
+    inputs = result.get("inputs", [])
+    if inputs and isinstance(inputs[0], dict) and isinstance(inputs[0].get("content"), str):
+        return inputs[0]["content"]
+    return ""

strands_deepkeep-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: strands-deepkeep
+Version: 0.1.0
+Summary: DeepKeep AI Firewall hook integration for Strands Agents
+Author-email: DeepKeep <info@deepkeep.ai>
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/Deepkeepai/strands-deepkeep#readme
+Project-URL: Homepage, https://deepkeep.ai
+Keywords: deepkeep,strands,hooks,moderation,guardrails
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: strands-agents>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Dynamic: license-file
+
+# strands-deepkeep
+
+Strands Agents hook provider for the [DeepKeep AI Firewall](https://deepkeep.ai/capabilities/ai-firewall).
+
+DeepKeep runs before a Strands invocation reaches the model and after the model returns. It can block unsafe content, pass safe content through, and apply redacted or modified text returned by DeepKeep.
+
+## Installation
+
+```bash
+pip install strands-deepkeep
+```
+
+## Quick start
+
+```python
+import os
+
+from strands import Agent
+from strands_deepkeep import DeepKeepGuardrail
+
+agent = Agent(
+    plugins=[
+        DeepKeepGuardrail(
+            api_key=os.environ["DEEPKEEP_API_KEY"],
+            base_url=os.environ["DEEPKEEP_BASE_URL"],
+            pre_model="input-firewall-id",
+            post_model="output-firewall-id",
+        )
+    ]
+)
+
+result = agent("Summarize this customer support request")
+```
+
+`pre_model` and `post_model` are DeepKeep firewall IDs. Each value is sent to the matching moderation endpoint as the `model` field.
+
+## Behavior
+
+- `allow` and `alert` decisions let the invocation continue.
+- `block` decisions cancel the invocation before the model or clear blocked model output after the model call.
+- `redact` and `modify` decisions replace the latest user text before the invocation or replace generated assistant text after the model call.
+- DeepKeep API decisions are stored in `invocation_state` as `deepkeep_pre` and `deepkeep_post` for audit and logging.
+
+## Environment
+
+You can pass credentials directly or set:
+
+```bash
+export DEEPKEEP_API_KEY="dk-..."
+export DEEPKEEP_BASE_URL="https://your-deepkeep-instance.example"
+```
+
+## Strands catalog entry
+
+Submit the integration to Strands by adding `site/src/content/catalog/strands-deepkeep.yaml` to `strands-agents/harness-sdk`:
+
+```yaml
+name: strands-deepkeep
+description: DeepKeep AI Firewall guardrails for Strands Agents using lifecycle hooks around model input and output.
+integrationType: plugin
+languages:
+  python:
+    package: strands-deepkeep
+github: https://github.com/Deepkeepai/strands-deepkeep
+docsUrl: https://github.com/Deepkeepai/strands-deepkeep#readme
+addedDate: 2026-08-26
+maintainedBy: partner
+```

strands_deepkeep-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+strands_deepkeep/__init__.py,sha256=gSoqQLftHu8aiBnyhY91Io47EtRbyVlhjpzr9BEUvhM,248
+strands_deepkeep/guardrail.py,sha256=C4WQpv3tsjRw_PMNrIjdHuPGa6DuQpvQdlu90-VPoyE,8703
+strands_deepkeep-0.1.0.dist-info/licenses/LICENSE,sha256=gvDg5qsSNm4LlpTtK4v1K-DbrSfq4ZXGCyLKsjKxros,1065
+strands_deepkeep-0.1.0.dist-info/METADATA,sha256=WS8JzfEveIklBIFYl_yoI9r1dpwIcZ--ZPxP50pFJCQ,3372
+strands_deepkeep-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+strands_deepkeep-0.1.0.dist-info/top_level.txt,sha256=EDlhIPQW1bASQELWp0urde-JDwXCKTuA8BFk8ywjMvg,17
+strands_deepkeep-0.1.0.dist-info/RECORD,,

strands_deepkeep-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

strands_deepkeep-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepKeep
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

strands_deepkeep-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+strands_deepkeep