Add cookbook: Governed RAG pipeline with TealTiger governance guardrails

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"]
+

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/)"
+   ]
+  }
+ ]
+}