diff --git a/index.toml b/index.toml index 016d751..c5357b0 100644 --- a/index.toml +++ b/index.toml @@ -406,3 +406,10 @@ title = "Building a Cost-Aware Agent with Hooks" notebook = "cost_aware_agent.ipynb" new = true topics = ["Agents"] + +[[cookbook]] +title = "Governed RAG Pipeline with TealTiger" +notebook = "governed_rag_pipeline_with_tealtiger.ipynb" +new = true +topics = ["rag", "governance", "security", "pii-detection", "tealtiger"] + diff --git a/notebooks/governed_rag_pipeline_with_tealtiger.ipynb b/notebooks/governed_rag_pipeline_with_tealtiger.ipynb new file mode 100644 index 0000000..98a7b1e --- /dev/null +++ b/notebooks/governed_rag_pipeline_with_tealtiger.ipynb @@ -0,0 +1,265 @@ +{ + "nbformat": 4, + "nbformat_minor": 0, + "metadata": { + "colab": { + "provenance": [], + "toc_visible": true + }, + "kernelspec": { + "name": "python3", + "display_name": "Python 3" + }, + "language_info": { + "name": "python" + } + }, + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Governed RAG Pipeline with TealTiger\n", + "\n", + "This cookbook shows how to add deterministic governance guardrails to a Haystack RAG pipeline using [TealTiger](https://haystack.deepset.ai/integrations/tealtiger).\n", + "\n", + "You'll learn how to:\n", + "- Scan queries for PII before they reach the LLM\n", + "- Enforce cost budgets per session\n", + "- Detect secrets in generated responses\n", + "- Produce structured audit receipts for compliance\n", + "\n", + "All governance runs deterministically (regex + policy rules) with no LLM in the governance path and under 2ms overhead." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!pip install haystack-ai haystack-tealtiger" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Set up the Governed RAG Pipeline\n", + "\n", + "We'll build a simple RAG pipeline with an in-memory document store and wrap it with TealTiger governance checks at the query boundary." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "from haystack import Pipeline, Document\n", + "from haystack.document_stores.in_memory import InMemoryDocumentStore\n", + "from haystack.components.retrievers.in_memory import InMemoryBM25Retriever\n", + "from haystack.components.builders import PromptBuilder\n", + "from haystack.components.generators import OpenAIGenerator\n", + "\n", + "# Set your OpenAI API key\n", + "os.environ[\"OPENAI_API_KEY\"] = \"your-api-key-here\"\n", + "\n", + "# Create a document store with sample documents\n", + "document_store = InMemoryDocumentStore()\n", + "documents = [\n", + " Document(content=\"TealTiger is an open-source AI governance SDK that provides deterministic policy enforcement for AI agents.\"),\n", + " Document(content=\"Haystack is a production-ready framework for building RAG pipelines and AI applications.\"),\n", + " Document(content=\"PII detection scans text for sensitive data like SSNs (e.g., 123-45-6789), credit cards, and email addresses.\"),\n", + " Document(content=\"The company's annual revenue was $4.2M in 2025, with a net profit margin of 12%.\"),\n", + "]\n", + "document_store.write_documents(documents)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Add TealTiger Governance\n", + "\n", + "We'll configure governance policies:\n", + "- **PII block**: Deny queries containing SSNs, credit cards, or email addresses\n", + "- **Cost limit**: Cap session cost at $0.50\n", + "- **Secret detection**: Block responses containing API keys or tokens" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from haystack_tealtiger import TealTigerGovernanceChecker\n", + "from tealtiger import GovernancePolicy, GovernanceMode\n", + "\n", + "# Configure governance policies\n", + "governance = TealTigerGovernanceChecker(\n", + " policies=[\n", + " GovernancePolicy.pii_block([\"ssn\", \"credit_card\", \"email\"]),\n", + " GovernancePolicy.cost_limit(max_per_session=0.50),\n", + " GovernancePolicy.secret_detection(),\n", + " ],\n", + " mode=GovernanceMode.ENFORCE, # Block violating requests\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Build the Pipeline\n", + "\n", + "The governance checker runs as a component in the pipeline. It scans the query before it reaches the retriever/LLM." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Build the RAG pipeline with governance\n", + "template = \"\"\"\n", + "Given the following context, answer the question.\n", + "\n", + "Context:\n", + "{% for doc in documents %}\n", + "- {{ doc.content }}\n", + "{% endfor %}\n", + "\n", + "Question: {{ query }}\n", + "Answer:\n", + "\"\"\"\n", + "\n", + "pipe = Pipeline()\n", + "pipe.add_component(\"governance\", governance)\n", + "pipe.add_component(\"retriever\", InMemoryBM25Retriever(document_store=document_store))\n", + "pipe.add_component(\"prompt_builder\", PromptBuilder(template=template))\n", + "pipe.add_component(\"llm\", OpenAIGenerator(model=\"gpt-4o-mini\"))\n", + "\n", + "# Connect components\n", + "pipe.connect(\"governance.query\", \"retriever.query\")\n", + "pipe.connect(\"retriever\", \"prompt_builder.documents\")\n", + "pipe.connect(\"governance.query\", \"prompt_builder.query\")\n", + "pipe.connect(\"prompt_builder\", \"llm\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Run a Clean Query (Allowed)\n", + "\n", + "This query has no PII and is within budget — governance allows it through." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# This query is clean — no PII, within budget\n", + "result = pipe.run({\"governance\": {\"query\": \"What is TealTiger?\"}})\n", + "print(\"Answer:\", result[\"llm\"][\"replies\"][0])\n", + "print(\"\\nGovernance decision:\", governance.last_decision)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Run a Query with PII (Blocked)\n", + "\n", + "This query contains an SSN — governance will block it in ENFORCE mode." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# This query contains an SSN — governance will block it\n", + "try:\n", + " result = pipe.run({\"governance\": {\"query\": \"Look up records for SSN 123-45-6789\"}})\n", + "except Exception as e:\n", + " print(f\"Blocked: {e}\")\n", + " print(f\"Reason: {governance.last_decision.reason_codes}\")\n", + " print(f\"Risk score: {governance.last_decision.risk_score}\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Inspect the Audit Trail\n", + "\n", + "Every governance decision produces a structured TEEC receipt — useful for SOC2/HIPAA compliance evidence." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# View all governance decisions from this session\n", + "for i, decision in enumerate(governance.decisions):\n", + " print(f\" Decision {i+1}: [{decision.action}] \"\n", + " f\"reason={decision.reason_codes} \"\n", + " f\"risk={decision.risk_score} \"\n", + " f\"latency={decision.evaluation_time_ms:.2f}ms\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Switch to MONITOR Mode (Dry Run)\n", + "\n", + "In MONITOR mode, governance evaluates policies and records decisions but never blocks — useful for rolling out governance without risk." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Switch to MONITOR mode — logs violations but allows everything through\n", + "governance.mode = GovernanceMode.MONITOR\n", + "\n", + "result = pipe.run({\"governance\": {\"query\": \"Look up SSN 123-45-6789\"}})\n", + "print(\"Query allowed through (MONITOR mode)\")\n", + "print(f\"Decision recorded: {governance.last_decision.action}\")\n", + "print(f\"Would have blocked: {governance.last_decision.reason_codes}\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "| Mode | Behavior |\n", + "|------|----------|\n", + "| **ENFORCE** | Evaluates policies, blocks violations |\n", + "| **MONITOR** | Evaluates policies, records decisions, allows all through (dry run) |\n", + "| **OBSERVE** | Skips evaluation, passes through with minimal audit |\n", + "\n", + "**Resources:**\n", + "- [TealTiger Integration Page](https://haystack.deepset.ai/integrations/tealtiger)\n", + "- [TealTiger Docs](https://docs.tealtiger.ai)\n", + "- [GitHub](https://github.com/agentguard-ai/tealtiger)\n", + "- [PyPI](https://pypi.org/project/haystack-tealtiger/)" + ] + } + ] +}