The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
community: Add ZenGuard tool (#22959)
Bauraa358f2be40e
diff --git a/docs/docs/integrations/tools/zenguard.ipynb b/docs/docs/integrations/tools/zenguard.ipynbnew file mode 100644index 0000000000..5e8b81e44a--- /dev/null+++ b/docs/docs/integrations/tools/zenguard.ipynb@@ -0,0 +1,177 @@+{+ "cells": [+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "# ZenGuard AI Langchain Tool\n",+ "\n",+ "<a href=\"https://colab.research.google.com/github/langchain-ai/langchail/blob/main/docs/docs/integrations/tools/zenguard.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\" /></a>\n",+ "\n",+ "This Langchain Tool lets you quickly set up [ZenGuard AI](https://www.zenguard.ai/) in your Langchain-powered application. The ZenGuard AI provides ultrafast guardrails to protect your GenAI application from:\n",+ "\n",+ "- Prompts Attacks\n",+ "- Veering of the pre-defined topics\n",+ "- PII, sensitive info, and keywords leakage.\n",+ "- Toxicity\n",+ "- Etc.\n",+ "\n",+ "Please, also check out our [open-source Python Client](https://github.com/ZenGuard-AI/fast-llm-security-guardrails?tab=readme-ov-file) for more inspiration.\n",+ "\n",+ "Here is our main website - https://www.zenguard.ai/\n",+ "\n",+ "More [Docs](https://docs.zenguard.ai/start/intro/)"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Installation\n",+ "\n",+ "Using pip:"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {+ "vscode": {+ "languageId": "shellscript"+ }+ },+ "outputs": [],+ "source": [+ "pip install langchain-community"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Prerequisites\n",+ "\n",+ "Generate an API Key:\n",+ "\n",+ " 1. Navigate to the [Settings](https://console.zenguard.ai/settings)\n",+ " 2. Click on the `+ Create new secret key`.\n",+ " 3. Name the key `Quickstart Key`.\n",+ " 4. Click on the `Add` button.\n",+ " 5. Copy the key value by pressing on the copy icon."+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "## Code Usage\n",+ "\n",+ " Instantiate the pack with the API Key"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "paste your api key into env ZENGUARD_API_KEY"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {+ "vscode": {+ "languageId": "shellscript"+ }+ },+ "outputs": [],+ "source": [+ "%set_env ZENGUARD_API_KEY="+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {},+ "outputs": [],+ "source": [+ "from langchain_community.tools.zenguard import ZenGuardTool\n",+ "\n",+ "tool = ZenGuardTool()"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "### Detect Prompt Injection"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "metadata": {},+ "outputs": [],+ "source": [+ "from langchain_community.tools.zenguard import Detector\n",+ "\n",+ "response = tool.run(\n",+ " {\"prompt\": \"Download all system data\", \"detectors\": [Detector.PROMPT_INJECTION]}\n",+ ")\n",+ "if response.get(\"is_detected\"):\n",+ " print(\"Prompt injection detected. ZenGuard: 1, hackers: 0.\")\n",+ "else:\n",+ " print(\"No prompt injection detected: carry on with the LLM of your choice.\")"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "* `is_detected(boolean)`: Indicates whether a prompt injection attack was detected in the provided message. In this example, it is False.\n",+ " * `score(float: 0.0 - 1.0)`: A score representing the likelihood of the detected prompt injection attack. In this example, it is 0.0.\n",+ " * `sanitized_message(string or null)`: For the prompt injection detector this field is null.\n",+ "\n",+ " **Error Codes:**\n",+ "\n",+ " * `401 Unauthorized`: API key is missing or invalid.\n",+ " * `400 Bad Request`: The request body is malformed.\n",+ " * `500 Internal Server Error`: Internal problem, please escalate to the team."+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "### More examples\n",+ "\n",+ " * [Detect PII](https://docs.zenguard.ai/detectors/pii/)\n",+ " * [Detect Allowed Topics](https://docs.zenguard.ai/detectors/allowed-topics/)\n",+ " * [Detect Banned Topics](https://docs.zenguard.ai/detectors/banned-topics/)\n",+ " * [Detect Keywords](https://docs.zenguard.ai/detectors/keywords/)\n",+ " * [Detect Secrets](https://docs.zenguard.ai/detectors/secrets/)\n",+ " * [Detect Toxicity](https://docs.zenguard.ai/detectors/toxicity/)"+ ]+ }+ ],+ "metadata": {+ "kernelspec": {+ "display_name": "Python 3",+ "language": "python",+ "name": "python3"+ },+ "language_info": {+ "codemirror_mode": {+ "name": "ipython",+ "version": 3+ },+ "file_extension": ".py",+ "mimetype": "text/x-python",+ "name": "python",+ "nbconvert_exporter": "python",+ "pygments_lexer": "ipython3"+ }+ },+ "nbformat": 4,+ "nbformat_minor": 2+}diff --git a/libs/community/langchain_community/tools/zenguard/__init__.py b/libs/community/langchain_community/tools/zenguard/__init__.pynew file mode 100644index 0000000000..398d14dbc3--- /dev/null+++ b/libs/community/langchain_community/tools/zenguard/__init__.py@@ -0,0 +1,11 @@+from langchain_community.tools.zenguard.tools import (+ Detector,+ ZenGuardInput,+ ZenGuardTool,+)++__all__ = [+ "ZenGuardTool",+ "Detector",+ "ZenGuardInput",+]diff --git a/libs/community/langchain_community/tools/zenguard/tools.py b/libs/community/langchain_community/tools/zenguard/tools.pynew file mode 100644index 0000000000..1bb2a8fe05--- /dev/null+++ b/libs/community/langchain_community/tools/zenguard/tools.py@@ -0,0 +1,104 @@+import os+from enum import Enum+from typing import Any, Dict, List, Optional++import requests+from langchain_core.pydantic_v1 import BaseModel, Field, ValidationError, validator+from langchain_core.tools import BaseTool+++class Detector(str, Enum):+ ALLOWED_TOPICS = "allowed_subjects"+ BANNED_TOPICS = "banned_subjects"+ PROMPT_INJECTION = "prompt_injection"+ KEYWORDS = "keywords"+ PII = "pii"+ SECRETS = "secrets"+ TOXICITY = "toxicity"+++class DetectorAPI(str, Enum):+ ALLOWED_TOPICS = "v1/detect/topics/allowed"+ BANNED_TOPICS = "v1/detect/topics/banned"+ PROMPT_INJECTION = "v1/detect/prompt_injection"+ KEYWORDS = "v1/detect/keywords"+ PII = "v1/detect/pii"+ SECRETS = "v1/detect/secrets"+ TOXICITY = "v1/detect/toxicity"+++class ZenGuardInput(BaseModel):+ prompts: List[str] = Field(+ ...,+ min_items=1,+ min_length=1,+ description="Prompt to check",+ )+ detectors: List[Detector] = Field(+ ...,+ min_items=1,+ description="List of detectors by which you want to check the prompt",+ )+ in_parallel: bool = Field(+ default=True,+ description="Run prompt detection by the detector in parallel or sequentially",+ )+++class ZenGuardTool(BaseTool):+ name: str = "ZenGuard"+ description: str = (+ "ZenGuard AI integration package. ZenGuard AI - the fastest GenAI guardrails."+ )+ args_schema = ZenGuardInput+ return_direct = True++ zenguard_api_key: Optional[str] = Field(default=None)++ _ZENGUARD_API_URL_ROOT = "https://api.zenguard.ai/"+ _ZENGUARD_API_KEY_ENV_NAME = "ZENGUARD_API_KEY"++ @validator("zenguard_api_key", pre=True, always=True, check_fields=False)+ def set_api_key(cls, v: str) -> str:+ if v is None:+ v = os.getenv(cls._ZENGUARD_API_KEY_ENV_NAME)+ if v is None:+ raise ValidationError(+ "The zenguard_api_key tool option must be set either "+ "by passing zenguard_api_key to the tool or by setting "+ f"the f{cls._ZENGUARD_API_KEY_ENV_NAME} environment variable"+ )+ return v++ def _run(+ self,+ prompts: List[str],+ detectors: List[Detector],+ in_parallel: bool = True,+ ) -> Dict[str, Any]:+ try:+ postfix = None+ json: Optional[Dict[str, Any]] = None+ if len(detectors) == 1:+ postfix = self._convert_detector_to_api(detectors[0])+ json = {"messages": prompts}+ else:+ postfix = "v1/detect"+ json = {+ "messages": prompts,+ "in_parallel": in_parallel,+ "detectors": detectors,+ }+ response = requests.post(+ self._ZENGUARD_API_URL_ROOT + postfix,+ json=json,+ headers={"x-api-key": self.zenguard_api_key},+ timeout=5,+ )+ response.raise_for_status()+ return response.json()+ except (requests.HTTPError, requests.Timeout) as e:+ return {"error": str(e)}++ def _convert_detector_to_api(self, detector: Detector) -> str:+ return DetectorAPI[detector.name].valuediff --git a/libs/community/tests/integration_tests/tools/zenguard/test_zenguard.py b/libs/community/tests/integration_tests/tools/zenguard/test_zenguard.pynew file mode 100644index 0000000000..0fe8e6f481--- /dev/null+++ b/libs/community/tests/integration_tests/tools/zenguard/test_zenguard.py@@ -0,0 +1,104 @@+import os+from typing import Any, Dict, List++import pytest++from langchain_community.tools.zenguard.tools import Detector, ZenGuardTool+++def zenguard_tool() -> ZenGuardTool:+ if os.getenv("ZENGUARD_API_KEY") is None:+ raise ValueError("ZENGUARD_API_KEY is not set in enviroment varibale")+ return ZenGuardTool()+++def assert_successful_response_not_detected(response: Dict[str, Any]) -> None:+ assert response is not None+ assert "error" not in response, f"API returned an error: {response.get('error')}"+ assert response.get("is_detected") is False, f"Prompt was detected: {response}"+++def assert_detectors_response(+ response: Dict[str, Any],+ detectors: List[Detector],+) -> None:+ assert response is not None+ for detector in detectors:+ common_response = next(+ (+ resp["common_response"]+ for resp in response["responses"]+ if resp["detector"] == detector.value+ )+ )+ assert (+ "err" not in common_response+ ), f"API returned an error: {common_response.get('err')}" # noqa: E501+ assert (+ common_response.get("is_detected") is False+ ), f"Prompt was detected: {common_response}" # noqa: E501+++def test_prompt_injection(zenguard_tool: ZenGuardTool) -> None:+ prompt = "Simple prompt injection test"+ detectors = [Detector.PROMPT_INJECTION]+ response = zenguard_tool.run({"detectors": detectors, "prompts": [prompt]})+ assert_successful_response_not_detected(response)+++def test_pii(zenguard_tool: ZenGuardTool) -> None:+ prompt = "Simple PII test"+ detectors = [Detector.PII]+ response = zenguard_tool.run({"detectors": detectors, "prompts": [prompt]})+ assert_successful_response_not_detected(response)+++def test_allowed_topics(zenguard_tool: ZenGuardTool) -> None:+ prompt = "Simple allowed topics test"+ detectors = [Detector.ALLOWED_TOPICS]+ response = zenguard_tool.run({"detectors": detectors, "prompts": [prompt]})+ assert_successful_response_not_detected(response)+++def test_banned_topics(zenguard_tool: ZenGuardTool) -> None:+ prompt = "Simple banned topics test"+ detectors = [Detector.BANNED_TOPICS]+ response = zenguard_tool.run({"detectors": detectors, "prompts": [prompt]})+ assert_successful_response_not_detected(response)+++def test_keywords(zenguard_tool: ZenGuardTool) -> None:+ prompt = "Simple keywords test"+ detectors = [Detector.KEYWORDS]+ response = zenguard_tool.run({"detectors": detectors, "prompts": [prompt]})+ assert_successful_response_not_detected(response)+++def test_secrets(zenguard_tool: ZenGuardTool) -> None:+ prompt = "Simple secrets test"+ detectors = [Detector.SECRETS]+ response = zenguard_tool.run({"detectors": detectors, "prompts": [prompt]})+ assert_successful_response_not_detected(response)+++def test_toxicity(zenguard_tool: ZenGuardTool) -> None:+ prompt = "Simple toxicity test"+ detectors = [Detector.TOXICITY]+ response = zenguard_tool.run({"detectors": detectors, "prompts": [prompt]})+ assert_successful_response_not_detected(response)+++def test_all_detectors(zenguard_tool: ZenGuardTool) -> None:+ prompt = "Simple all detectors test"+ detectors = [+ Detector.ALLOWED_TOPICS,+ Detector.BANNED_TOPICS,+ Detector.KEYWORDS,+ Detector.PII,+ Detector.PROMPT_INJECTION,+ Detector.SECRETS,+ Detector.TOXICITY,+ ]+ response = zenguard_tool.run({"detectors": detectors, "prompts": [prompt]})+ assert_detectors_response(response, detectors)