{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Module 8 — Reliability & Error Handling\n",
    "\n",
    "Three patterns for resilient agentic pipelines:\n",
    "\n",
    "1. **Programmatic tool calling** — let Claude loop through tool calls inside `code_execution_20260120` so only the relevant slice reaches the context window.\n",
    "2. **Structured error responses** — return JSON with `errorCategory`, `isRetryable`, and `message` so Claude can reason about retry vs. pivot.\n",
    "3. **PostToolUse hooks** — normalize tool output before the model sees it.\n",
    "\n",
    "> **ZDR note:** programmatic tool calling is **not ZDR-eligible** (execution state held server-side)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Structured error response from a tool handler\n",
    "\n",
    "Raw string errors give Claude no actionable signal. Categorize and tag retryability — that's what drives the agentic loop's decision."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class _DemoCRM:\n",
    "    def search_contacts(self, query):\n",
    "        raise TimeoutError(\"demo: pretend the CRM is slow\")\n",
    "\n",
    "crm_client = _DemoCRM()\n",
    "\n",
    "def handle_crm_tool(tool_input):\n",
    "    try:\n",
    "        result = crm_client.search_contacts(tool_input[\"query\"])\n",
    "        return {\"contacts\": result}\n",
    "    except TimeoutError:\n",
    "        return {\n",
    "            \"errorCategory\": \"API_TIMEOUT\",\n",
    "            \"isRetryable\": True,\n",
    "            \"message\": \"CRM API timed out after 30s. Retry with a narrower query.\",\n",
    "        }\n",
    "    except PermissionError:\n",
    "        return {\n",
    "            \"errorCategory\": \"INVALID_PERMISSIONS\",\n",
    "            \"isRetryable\": False,\n",
    "            \"message\": \"API key lacks read access to the contacts endpoint. Escalate to admin.\",\n",
    "        }\n",
    "\n",
    "import json\n",
    "print(json.dumps(handle_crm_tool({\"query\": \"warm-leads\"}), indent=2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. PostToolUse hook config\n",
    "\n",
    "Hooks run shell commands after each tool call but **before** the result reaches the model. Use them to normalize date formats, currency, or encoding so Claude always sees uniform data. The cell below scaffolds the JSON config; install it under `.claude/hooks.json` for Claude Code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "hooks_config = '''{\n",
    "  \"hooks\": {\n",
    "    \"PostToolUse\": [\n",
    "      {\n",
    "        \"matcher\": {\"tool_name\": \"fetch_crm_data\"},\n",
    "        \"hooks\": [\n",
    "          {\n",
    "            \"type\": \"command\",\n",
    "            \"command\": \"python normalize_dates.py\"\n",
    "          }\n",
    "        ]\n",
    "      }\n",
    "    ]\n",
    "  }\n",
    "}\n",
    "'''\n",
    "\n",
    "Path(\"module8_demo\").mkdir(exist_ok=True)\n",
    "Path(\"module8_demo/hooks.json\").write_text(hooks_config, encoding=\"utf-8\")\n",
    "print(\"wrote module8_demo/hooks.json\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}