Upload folder using huggingface_hub

knowledge_transfer_week1_part3.ipynb

@@ -2,6 +2,7 @@
   "cells": [
     {
       "cell_type": "markdown",
+      "id": "9c686d08",
       "metadata": {},
       "source": [
         "# KT1 Part 3 — Streaming, Filesystem MCP, and Gradio\n",
@@ -17,8 +18,7 @@
         "| **Gradio** | Wrap the streaming agent in a chat UI you can share with a URL |\n",
         "\n",
         "By the end you'll have a KB-grounded customer support assistant running in a local Gradio app, streaming its reasoning and tool calls token-by-token."
-      ],
-      "id": "9c686d08"
+      ]
     },
     {
       "cell_type": "markdown",
@@ -33,7 +33,10 @@
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "f92d6179",
       "metadata": {},
+      "outputs": [],
       "source": [
         "import os\n",
         "import warnings\n",
@@ -51,13 +54,11 @@
         "    azure_deployment=os.getenv(\"AZURE_OPENAI_CHAT_DEPLOYMENT_NAME\"),\n",
         "    api_version=os.getenv(\"AZURE_OPENAI_API_VERSION\"),\n",
         ")"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "f92d6179"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "8991899e",
       "metadata": {},
       "source": [
         "---\n",
@@ -78,11 +79,11 @@
         "| `custom` | Whatever you emit via `get_stream_writer()` | You want to surface app-specific progress events |\n",
         "\n",
         "You can combine modes: `stream_mode=[\"updates\", \"messages\"]` yields `(mode_name, event)` tuples and you route by mode."
-      ],
-      "id": "8991899e"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "4918396a",
       "metadata": {},
       "source": [
         "### A workflow to stream\n",
@@ -90,12 +91,14 @@
         "To keep the focus on streaming, we'll reuse the **support-ticket triage** workflow from Part 2 Pattern 1. The demo ticket below routes down the auto-respond path — three LLM calls (classify → generate → polish) gives us plenty of events to observe.\n",
         "\n",
         "If you already ran Part 2, this is the same shape — skim it."
-      ],
-      "id": "4918396a"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "795c4f3d",
       "metadata": {},
+      "outputs": [],
       "source": [
         "from typing_extensions import TypedDict\n",
         "from typing import Annotated, Literal\n",
@@ -227,24 +230,24 @@
         "\n",
         "support_chain = workflow.compile()\n",
         "display(Image(support_chain.get_graph().draw_mermaid_png()))"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "795c4f3d"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "bb33e148",
       "metadata": {},
       "source": [
         "### Mode 1 — `updates`: node-level progress\n",
         "\n",
         "Yields one event per node, containing only what that node **changed**. The simplest mode — a clean \"step by step\" feed."
-      ],
-      "id": "bb33e148"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "d2f79113",
       "metadata": {},
+      "outputs": [],
       "source": [
         "ticket = {\n",
         "    \"customer_message\": \"My subscription was double-charged this month — please refund the extra charge.\",\n",
@@ -256,36 +259,34 @@
         "    for node, delta in event.items():\n",
         "        keys = list(delta.keys())\n",
         "        print(f\"  {node:10s} -> updated {keys}\")"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "d2f79113"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "d1a0556e",
       "metadata": {},
       "source": [
         "### Mode 2 — `values`: cumulative state snapshots\n",
         "\n",
         "One event per checkpoint, each containing the **full state**. You get one snapshot for the initial input plus one after every node runs — so on our 3-node happy path, that's 4 snapshots. Useful when you want to render the latest known values to a UI without tracking deltas yourself."
-      ],
-      "id": "d1a0556e"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "bf7b3c36",
       "metadata": {},
+      "outputs": [],
       "source": [
         "print(\"Streaming 'values' mode:\\n\")\n",
         "for i, snapshot in enumerate(support_chain.stream(ticket, stream_mode=\"values\")):\n",
         "    filled = [k for k, v in snapshot.items() if v not in (None, \"\", [], {})]\n",
         "    print(f\"  step {i}: filled fields = {filled}\")"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "bf7b3c36"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "8bf9bad5",
       "metadata": {},
       "source": [
         "### Mode 3 — `messages`: token-by-token streaming\n",
@@ -293,12 +294,14 @@
         "This is the one you want for ChatGPT-style UX. Each event is a `(chunk, metadata)` tuple where `chunk` is an `AIMessageChunk` holding a few tokens. `metadata` tells you which **node** emitted the chunk — so you can filter to just the node whose output you want to render.\n",
         "\n",
         "Use the **async** variant (`astream`) — token streaming is async-native on the SDK side."
-      ],
-      "id": "8bf9bad5"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "eb480690",
       "metadata": {},
+      "outputs": [],
       "source": [
         "print(\"Streaming 'messages' mode — tokens from the 'polish_response' node only:\\n\")\n",
         "\n",
@@ -306,24 +309,24 @@
         "    if metadata.get(\"langgraph_node\") == \"polish_response\" and chunk.content:\n",
         "        print(chunk.content, end=\"\", flush=True)\n",
         "print()"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "eb480690"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "75bd4132",
       "metadata": {},
       "source": [
         "### Mode 4 — `custom`: emit your own events\n",
         "\n",
         "Sometimes a node does meaningful work **between** LLM calls — a DB query, a long loop, a parse — and you want the UI to know. Call `get_stream_writer()` inside the node to push a custom event; the caller receives it in `stream_mode=\"custom\"`."
-      ],
-      "id": "75bd4132"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "9c14989f",
       "metadata": {},
+      "outputs": [],
       "source": [
         "from langgraph.config import get_stream_writer\n",
         "\n",
@@ -354,13 +357,11 @@
         "print(\"Streaming 'custom' events:\\n\")\n",
         "for event in demo_chain.stream(ticket, stream_mode=\"custom\"):\n",
         "    print(f\"  {event}\")"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "9c14989f"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "c29456c8",
       "metadata": {},
       "source": [
         "### What to notice\n",
@@ -369,11 +370,11 @@
         "- **Modes are cheap to combine.** `stream_mode=[\"updates\", \"messages\"]` returns `(mode, event)` tuples — drive multiple UI elements from one subscription.\n",
         "- **`astream` pairs with `messages`.** Token streaming is async on the SDK side; use the async variant so tokens flow promptly.\n",
         "- **`get_stream_writer()` is the escape hatch.** Anything that isn't an LLM token or a node boundary — progress text, tool latency, partial parses — belongs in `custom`."
-      ],
-      "id": "c29456c8"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "04f00e37",
       "metadata": {},
       "source": [
         "---\n",
@@ -402,11 +403,11 @@
         "| `list_allowed_directories` | Show which paths this server is permitted to access |\n",
         "\n",
         "We'll only wire `read_text_file` to the agent — the others aren't needed once the file inventory is baked into the prompt. Like Playwright, the server ships as a Node process you run with `npx` — no Python package to install."
-      ],
-      "id": "04f00e37"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "eb4331ea",
       "metadata": {},
       "source": [
         "### One-time install\n",
@@ -419,22 +420,24 @@
         "```\n",
         "\n",
         "That's it. The first time `MultiServerMCPClient` connects, `npx` fetches and caches the server package — no separate install step."
-      ],
-      "id": "eb4331ea"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "e6d91476",
       "metadata": {},
       "source": [
         "### Build a mini knowledge base\n",
         "\n",
         "Three small markdown files covering the ticket types from Section 1: billing, password/access, shipping. In a real deployment this would be hundreds of articles versioned in git — the MCP boundary stays identical."
-      ],
-      "id": "e6d91476"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "21f7349f",
       "metadata": {},
+      "outputs": [],
       "source": [
         "from pathlib import Path\n",
         "\n",
@@ -497,24 +500,24 @@
         "print(\"KB files in\", kb_dir.resolve(), \":\")\n",
         "for f in sorted(kb_dir.iterdir()):\n",
         "    print(f\"  - {f.name}  ({f.stat().st_size} bytes)\")"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "21f7349f"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "20f8f26b",
       "metadata": {},
       "source": [
         "### The notebook compatibility shim (same as Part 2)\n",
         "\n",
         "MCP's stdio transport expects real file descriptors, which Jupyter's captured streams don't always provide. This shim gets us past that — only needed inside notebooks."
-      ],
-      "id": "20f8f26b"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "7f9070ed",
       "metadata": {},
+      "outputs": [],
       "source": [
         "import sys, io\n",
         "\n",
@@ -528,13 +531,11 @@
         "        stream.fileno()\n",
         "    except (AttributeError, io.UnsupportedOperation):\n",
         "        stream.fileno = _safe_fileno"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "7f9070ed"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "25a4c631",
       "metadata": {},
       "source": [
         "### Connect and list the tools\n",
@@ -542,12 +543,14 @@
         "We pass the absolute path to `support_kb/` as the one allowed directory, and set the server's `cwd` to the same path so bare basenames (e.g. `\"billing.md\"`) resolve correctly inside the sandbox. The server **refuses any read outside that path** — a simple but real sandbox; if the agent ever tried to read `/etc/passwd`, the call would error at the MCP boundary rather than in our Python code.\n",
         "\n",
         "After pulling the full tool list for reference, we keep only `read_text_file` and hand that to the agent. Trimming the surface is the cheapest guardrail there is: fewer tools = fewer things the LLM can get wrong."
-      ],
-      "id": "25a4c631"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "52cc53df",
       "metadata": {},
+      "outputs": [],
       "source": [
         "from langchain_mcp_adapters.client import MultiServerMCPClient\n",
         "\n",
@@ -565,13 +568,11 @@
         "# Narrow the surface: only read_text_file. Discovery is done in the prompt.\n",
         "kb_tools = [t for t in all_kb_tools if t.name == \"read_text_file\"]\n",
         "print(f\"Exposing {len(kb_tools)} tool(s): {[t.name for t in kb_tools]}\")"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "52cc53df"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "97ad3345",
       "metadata": {},
       "source": [
         "### A small KB-lookup helper agent\n",
@@ -584,12 +585,14 @@
         "- **The LLM only ever passes a basename.** Combined with the server's CWD being the KB folder, that means paths can't drift outside the sandbox — no path sanitizer needed.\n",
         "\n",
         "The prompt also pins a sentinel (`NO_RELEVANT_ARTICLE`) so the downstream node can branch cleanly on a hit vs. a miss."
-      ],
-      "id": "97ad3345"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "1a05c23a",
       "metadata": {},
+      "outputs": [],
       "source": [
         "from langchain.agents import create_agent\n",
         "\n",
@@ -613,13 +616,11 @@
         "what you guess the customer needs — the downstream node will pick the right variant.\"\"\"\n",
         "\n",
         "kb_lookup_agent = create_agent(llm, kb_tools, system_prompt=kb_lookup_prompt)"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "1a05c23a"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "bf2a23fe",
       "metadata": {},
       "source": [
         "### Plug it into the triage graph\n",
@@ -631,12 +632,14 @@
         "```\n",
         "\n",
         "The escalation path is unchanged — human agents don't need the auto-grounding step. We also redefine `generate_response` as `generate_grounded_response`, which reads `kb_context` and tells the LLM to quote from it. Compile the new graph and render the mermaid — you'll see the extra node slotted in."
-      ],
-      "id": "bf2a23fe"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "ceaf62b6",
       "metadata": {},
+      "outputs": [],
       "source": [
         "from langgraph.checkpoint.memory import MemorySaver\n",
         "\n",
@@ -825,13 +828,11 @@
         "\n",
         "support_chain_v2 = workflow_v2.compile(checkpointer=MemorySaver())\n",
         "display(Image(support_chain_v2.get_graph().draw_mermaid_png()))"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "ceaf62b6"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "238049af",
       "metadata": {},
       "source": [
         "### Streaming the extended graph\n",
@@ -839,12 +840,14 @@
         "Same `stream_mode=[\"updates\", \"messages\"]` trick from Section 1. Now the `updates` stream also fires for `fetch_kb_context` — proof the new node ran — and we filter `messages` to `polish_response` so only the final reply tokens render inline.\n",
         "\n",
         "The KB helper's single `read_text_file` call happens inside `fetch_kb_context`; we don't surface it in the outer stream here, but you could by emitting `get_stream_writer()` events from the node (Mode 4 from Section 1)."
-      ],
-      "id": "238049af"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "00ad5451",
       "metadata": {},
+      "outputs": [],
       "source": [
         "from langchain_core.messages import AIMessageChunk\n",
         "import uuid\n",
@@ -890,13 +893,11 @@
         "                printed_reply_header = True\n",
         "            print(chunk.content, end=\"\", flush=True)\n",
         "print()"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "00ad5451"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "a8c27f08",
       "metadata": {},
       "source": [
         "### What to notice\n",
@@ -906,11 +907,11 @@
         "- **The sandbox is the config.** The MCP server only sees the directory you named in `args`, and with `cwd` pointed at the same folder, bare basenames resolve correctly. Different agent, different folder — no code changes.\n",
         "- **Grounding beats general knowledge.** Quotes from `billing.md` in the final reply are auditable; invented policy isn't.\n",
         "- **Scales naturally.** Swap the markdown folder for a vector-store MCP (e.g. Chroma) once the KB outgrows keyword lookups — the node's code barely changes."
-      ],
-      "id": "a8c27f08"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "25ed67ff",
       "metadata": {},
       "source": [
         "---\n",
@@ -926,35 +927,35 @@
         "- **Native streaming**: if your function is an `async` generator that yields partial responses, Gradio renders each yield as an in-place update\n",
         "\n",
         "We'll wire the **KB-grounded triage graph** from Section 2 (`support_chain_v2`) into a `ChatInterface`. Each message the user types becomes a fresh ticket; the graph runs end-to-end (classify → fetch_kb_context → generate → polish) and the stream surfaces node progress and polished tokens."
-      ],
-      "id": "25ed67ff"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "e7ffdf12",
       "metadata": {},
       "source": [
         "### Make sure Gradio is installed\n",
         "\n",
         "Already added to `pyproject.toml` — the line below is a safety net in case you're on an older sync."
-      ],
-      "id": "e7ffdf12"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "a67347ff",
       "metadata": {},
+      "outputs": [],
       "source": [
         "import importlib, subprocess, sys\n",
         "if importlib.util.find_spec(\"gradio\") is None:\n",
         "    subprocess.check_call([sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"gradio\"])\n",
         "import gradio as gr\n",
         "print(\"gradio version:\", gr.__version__)"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "a67347ff"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "02f11d8f",
       "metadata": {},
       "source": [
         "### The streaming response function\n",
@@ -962,12 +963,14 @@
         "`gr.ChatInterface` expects an `async def` generator with signature `(message, history, request) -> AsyncIterator[str]`. We accumulate tokens in a **buffer** and `yield` the running total on every chunk — Gradio replaces the message with each yield, so yielding deltas would flicker.\n",
         "\n",
         "We derive `thread_id` from `request.session_hash`, which Gradio mints once per browser session. Combined with the graph's `MemorySaver` checkpointer and the new `conversation` field on `TicketStateV2`, that's what gives us multi-turn memory: each session gets an isolated thread, `generate_grounded_response` sees prior turns, `polish_and_log` appends the current one."
-      ],
-      "id": "02f11d8f"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "a3614a3b",
       "metadata": {},
+      "outputs": [],
       "source": [
         "async def respond(message: str, history: list[tuple[str, str]], request: gr.Request):\n",
         "    ticket = {\n",
@@ -1012,13 +1015,11 @@
         "                streaming_reply = True\n",
         "                reply_buffer += chunk.content\n",
         "                yield reply_buffer"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "a3614a3b"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "a7bb9501",
       "metadata": {},
       "source": [
         "### Launch the app\n",
@@ -1026,12 +1027,14 @@
         "`demo.launch()` starts a local server and prints a URL. Open it in a browser, paste in a support ticket, and watch the agent consult the KB live.\n",
         "\n",
         "> To stop the server, run `demo.close()` in a later cell."
-      ],
-      "id": "a7bb9501"
+      ]
     },
     {
       "cell_type": "code",
+      "execution_count": null,
+      "id": "cd4df22f",
       "metadata": {},
+      "outputs": [],
       "source": [
         "demo = gr.ChatInterface(\n",
         "    fn=respond,\n",
@@ -1045,13 +1048,11 @@
         ")\n",
         "\n",
         "demo.launch(inline=False, share=False)"
-      ],
-      "execution_count": null,
-      "outputs": [],
-      "id": "cd4df22f"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "f2ea03da",
       "metadata": {},
       "source": [
         "### What to notice\n",
@@ -1060,11 +1061,11 @@
         "- **The reply wipes the last status.** The moment polish_response tokens arrive, we stop yielding status markers and start yielding the accumulated reply buffer. That buffer replaces whatever status was showing, so the final UI state is just the clean reply.\n",
         "- **Session-scoped memory.** `request.session_hash` drives the `thread_id`, so each browser session gets its own thread in the `MemorySaver` checkpointer. Open a second tab and you start a fresh conversation — no leakage.\n",
         "- **History accumulates via reducer.** `TicketStateV2.conversation` uses `Annotated[list, operator.add]`. `polish_and_log` appends `{user, assistant}` each turn; `generate_grounded_response` reads the list on the next turn so the prompt sees the full thread."
-      ],
-      "id": "f2ea03da"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "13f3f73f",
       "metadata": {},
       "source": [
         "---\n",
@@ -1089,11 +1090,11 @@
         ">   → write requirements.txt + packages.txt → gradio deploy\n",
         ">   → set Space secrets → test the live URL\n",
         "> ```"
-      ],
-      "id": "13f3f73f"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "0e74c0d3",
       "metadata": {},
       "source": [
         "### 4.1 — Create a Hugging Face account\n",
@@ -1115,11 +1116,11 @@
         "    - **Type / Role**: choose **\"Write\"** — you need write access to create and update Spaces. A \"Read\" token is not enough.\n",
         "4. Click **Create Token**. Copy the token (it starts with `hf_...`) **right now** — HF only shows it once. If you close the page without copying, you'll have to create a new one.\n",
         "5. Paste it somewhere safe temporarily (a password manager is ideal). **Do not commit it to git or paste it into a notebook cell** — tokens in notebooks tend to leak into screenshots and commit history."
-      ],
-      "id": "0e74c0d3"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "7bd9a531",
       "metadata": {},
       "source": [
         "### 4.3 — Install the CLI tools and log in\n",
@@ -1148,11 +1149,11 @@
         "Success is confirmed when the CLI reports that your token was saved (typically under `~/.cache/huggingface/token`).\n",
         "\n",
         "> If you ever need to revoke access (e.g. laptop stolen), go back to the tokens page on the HF website and delete that named token — it invalidates immediately across all your machines."
-      ],
-      "id": "7bd9a531"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "63f79ba3",
       "metadata": {},
       "source": [
         "### 4.4 — Prepare the deployable app\n",
@@ -1169,29 +1170,16 @@
         "- `demo.launch()` takes no arguments — HF injects `GRADIO_SERVER_NAME=0.0.0.0` and the right port via env vars, so default launch works.\n",
         "\n",
         "The cell below is just a sanity check — it confirms `app.py` is present in your working directory before you try to deploy."
-      ],
-      "id": "63f79ba3"
+      ]
     },
     {
       "cell_type": "code",
-      "metadata": {},
-      "source": [
-        "from pathlib import Path\n",
-        "\n",
-        "app_file = Path(\"app.py\")\n",
-        "assert app_file.exists(), (\n",
-        "    \"app.py not found in the current directory. It ships alongside this notebook — \"\n",
-        "    \"make sure you're running from the repo root.\"\n",
-        ")\n",
-        "size = app_file.stat().st_size\n",
-        "lines = app_file.read_text().count(\"\\n\") + 1\n",
-        "print(f\"app.py found: {size:,} bytes, {lines} lines\")\n",
-        "print(\"\\nFirst 15 lines:\\n\")\n",
-        "print(\"\\n\".join(app_file.read_text().splitlines()[:15]))"
-      ],
       "execution_count": 27,
+      "id": "9a69bead",
+      "metadata": {},
       "outputs": [
         {
+          "name": "stdout",
           "output_type": "stream",
           "text": [
             "app.py found: 15,310 bytes, 406 lines\n",
@@ -1216,44 +1204,43 @@
           ]
         }
       ],
-      "id": "9a69bead"
+      "source": [
+        "from pathlib import Path\n",
+        "\n",
+        "app_file = Path(\"app.py\")\n",
+        "assert app_file.exists(), (\n",
+        "    \"app.py not found in the current directory. It ships alongside this notebook — \"\n",
+        "    \"make sure you're running from the repo root.\"\n",
+        ")\n",
+        "size = app_file.stat().st_size\n",
+        "lines = app_file.read_text().count(\"\\n\") + 1\n",
+        "print(f\"app.py found: {size:,} bytes, {lines} lines\")\n",
+        "print(\"\\nFirst 15 lines:\\n\")\n",
+        "print(\"\\n\".join(app_file.read_text().splitlines()[:15]))"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "87ad3526",
       "metadata": {},
       "source": [
         "### 4.5 — Declare Python dependencies\n",
         "\n",
         "HF Spaces uses `requirements.txt` (one package per line) to rebuild your environment. The `pyproject.toml` for this repo carries packages we used across *all three* notebooks — we only need the subset that `app.py` actually imports.\n",
         "\n",
+        "> Note: when deploying with modern Gradio (`gradio[mcp,oauth]`), keep `mcp` at `>=1.21.0,<2.0.0` to avoid resolver conflicts.\n",
+        "\n",
         "Run the cell below — it writes a minimal `requirements.txt` next to `app.py`."
-      ],
-      "id": "87ad3526"
+      ]
     },
     {
       "cell_type": "code",
-      "metadata": {},
-      "source": [
-        "requirements_txt = \"\"\"gradio>=5.0.0\n",
-        "langchain==1.2.11\n",
-        "langchain-openai==1.1.12\n",
-        "langchain-community>=0.4.1\n",
-        "langchain-mcp-adapters==0.1.14\n",
-        "langgraph>=1.1.2\n",
-        "mcp==1.15.0\n",
-        "pydantic==2.12.5\n",
-        "python-dotenv>=1.2.1\n",
-        "\"\"\"\n",
-        "\n",
-        "with open(\"requirements.txt\", \"w\") as f:\n",
-        "    f.write(requirements_txt)\n",
-        "\n",
-        "print(\"Wrote requirements.txt:\")\n",
-        "print(requirements_txt)"
-      ],
       "execution_count": 28,
+      "id": "729400ed",
+      "metadata": {},
       "outputs": [
         {
+          "name": "stdout",
           "output_type": "stream",
           "text": [
             "Wrote requirements.txt:\n",
@@ -1270,10 +1257,28 @@
           ]
         }
       ],
-      "id": "729400ed"
+      "source": [
+        "requirements_txt = \"\"\"gradio>=5.0.0\n",
+        "langchain==1.2.11\n",
+        "langchain-openai==1.1.12\n",
+        "langchain-community>=0.4.1\n",
+        "langchain-mcp-adapters==0.1.14\n",
+        "langgraph>=1.1.2\n",
+        "mcp>=1.21.0,<2.0.0\n",
+        "pydantic==2.12.5\n",
+        "python-dotenv>=1.2.1\n",
+        "\"\"\"\n",
+        "\n",
+        "with open(\"requirements.txt\", \"w\") as f:\n",
+        "    f.write(requirements_txt)\n",
+        "\n",
+        "print(\"Wrote requirements.txt:\")\n",
+        "print(requirements_txt)"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "52da9fe7",
       "metadata": {},
       "source": [
         "### 4.6 — Declare system packages (Node.js for MCP)\n",
@@ -1281,26 +1286,16 @@
         "Our app uses the **Filesystem MCP server**, which runs under Node via `npx`. The default Python Space image doesn't have Node. HF lets you install **system packages** (anything available via `apt-get`) by listing them in a `packages.txt` file at the project root.\n",
         "\n",
         "The cell below writes `packages.txt` with the two entries we need. Run it, then verify the file is in your project root."
-      ],
-      "id": "52da9fe7"
+      ]
     },
     {
       "cell_type": "code",
-      "metadata": {},
-      "source": [
-        "packages_txt = \"\"\"nodejs\n",
-        "npm\n",
-        "\"\"\"\n",
-        "\n",
-        "with open(\"packages.txt\", \"w\") as f:\n",
-        "    f.write(packages_txt)\n",
-        "\n",
-        "print(\"Wrote packages.txt:\")\n",
-        "print(packages_txt)"
-      ],
       "execution_count": 29,
+      "id": "d0d3edab",
+      "metadata": {},
       "outputs": [
         {
+          "name": "stdout",
           "output_type": "stream",
           "text": [
             "Wrote packages.txt:\n",
@@ -1310,10 +1305,21 @@
           ]
         }
       ],
-      "id": "d0d3edab"
+      "source": [
+        "packages_txt = \"\"\"nodejs\n",
+        "npm\n",
+        "\"\"\"\n",
+        "\n",
+        "with open(\"packages.txt\", \"w\") as f:\n",
+        "    f.write(packages_txt)\n",
+        "\n",
+        "print(\"Wrote packages.txt:\")\n",
+        "print(packages_txt)"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "14a3f503",
       "metadata": {},
       "source": [
         "### 4.7 — Keep secrets out of the repo\n",
@@ -1334,11 +1340,11 @@
         "The `gradio deploy` CLI respects `.gitignore`, so excluded files will not be uploaded. Double-check by running `git status --ignored` — your `.env` should appear under \"Ignored files\".\n",
         "\n",
         "> **Rule of thumb**: if the value would embarrass you on a billboard, it's a secret. API keys, endpoints, connection strings, tenant IDs — all secrets. These go into **Space secrets** (step 4.9), never into the repo."
-      ],
-      "id": "14a3f503"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "5c5b3dd5",
       "metadata": {},
       "source": [
         "### 4.8 — Run `gradio deploy`\n",
@@ -1371,11 +1377,11 @@
         "> The first build takes **3–10 minutes** — HF has to install Python packages *and* Node. Watch progress in the **Logs → Build** tab on the Space page. You'll see pip installs, then apt installs for `nodejs`, then your app starting up.\n",
         "\n",
         "If anything looks wrong mid-build, it's fine to let it finish and iterate — pushes are fast after the first time because layers are cached."
-      ],
-      "id": "5c5b3dd5"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "97cb1558",
       "metadata": {},
       "source": [
         "### 4.9 — Configure Space secrets\n",
@@ -1394,11 +1400,11 @@
         "After saving all four, click **Restart this Space** (or **Factory reboot** for a full rebuild). The Space re-reads env vars on every restart; without the restart, your app is still running with `None` values and Azure calls will fail with authentication errors.\n",
         "\n",
         "> **Good hygiene**: each deployment env gets its own Azure deployment / key. Don't reuse your laptop `.env` values for production — rotate to a fresh set."
-      ],
-      "id": "97cb1558"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "c560a9d9",
       "metadata": {},
       "source": [
         "### 4.10 — Verify and iterate\n",
@@ -1423,11 +1429,11 @@
         "HF auto-rebuilds the Space on every push — you'll see the build progress under the **Logs → Build** tab.\n",
         "\n",
         "You do **not** need to re-run `uv run gradio deploy` on subsequent updates. It's only for the initial create. Editing files in the HF web UI also works and triggers a rebuild."
-      ],
-      "id": "c560a9d9"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "473c6e08",
       "metadata": {},
       "source": [
         "### 4.11 — Troubleshooting\n",
@@ -1445,11 +1451,11 @@
         "| Want to pause the Space to stop accruing quota | Space is using CPU time you don't need right now | Settings → **Pause Space**. It won't serve traffic but your code + secrets are preserved. |\n",
         "\n",
         "**If you get truly stuck**, delete the Space (Settings → Delete this Space) and run `uv run gradio deploy` again from a clean directory. Spaces are cheap — starting over is often faster than debugging a bad state."
-      ],
-      "id": "473c6e08"
+      ]
     },
     {
       "cell_type": "markdown",
+      "id": "88d623f2",
       "metadata": {},
       "source": [
         "---\n",
@@ -1472,8 +1478,7 @@
         "- **Observability** — pipe the same stream into Langfuse (Part 2's monitoring section) for latency + token breakdowns\n",
         "\n",
         "With these you've closed the loop: a LangGraph workflow → a KB-grounded tool-using agent → a live web UI, all streaming."
-      ],
-      "id": "88d623f2"
+      ]
     }
   ],
   "metadata": {
@@ -1497,4 +1502,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 5
-}
+}

pyproject.toml

@@ -15,7 +15,7 @@ dependencies = [
   "langchain-community>=0.4.1",
   "PyMuPDF==1.26.3",
   "langchain-mcp-adapters==0.1.14",
-  "mcp==1.15.0",
+  "mcp>=1.21.0,<2.0.0",
   "openevals",
   "yfinance>=0.2.54,<0.3",
   "gradio>=5.0.0",

requirements.txt

@@ -4,6 +4,6 @@ langchain-openai==1.1.12
 langchain-community>=0.4.1
 langchain-mcp-adapters==0.1.14
 langgraph>=1.1.2
-mcp==1.15.0
+mcp>=1.21.0,<2.0.0
 pydantic==2.12.5
 python-dotenv>=1.2.1

uv.lock

@@ -463,6 +463,59 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/60/97/891a0971e1e4a8c5d2b20bbe0e524dc04548d2307fee33cdeba148fd4fc7/comm-0.2.3-py3-none-any.whl", hash = "sha256:c615d91d75f7f04f095b30d1c1711babd43bdc6419c1be9886a85f2f4e489417", size = 7294, upload-time = "2025-07-25T14:02:02.896Z" },
 ]
 
+[[package]]
+name = "cryptography"
+version = "46.0.7"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/47/93/ac8f3d5ff04d54bc814e961a43ae5b0b146154c89c61b47bb07557679b18/cryptography-46.0.7.tar.gz", hash = "sha256:e4cfd68c5f3e0bfdad0d38e023239b96a2fe84146481852dffbcca442c245aa5", size = 750652, upload-time = "2026-04-08T01:57:54.692Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0b/5d/4a8f770695d73be252331e60e526291e3df0c9b27556a90a6b47bccca4c2/cryptography-46.0.7-cp311-abi3-macosx_10_9_universal2.whl", hash = "sha256:ea42cbe97209df307fdc3b155f1b6fa2577c0defa8f1f7d3be7d31d189108ad4", size = 7179869, upload-time = "2026-04-08T01:56:17.157Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/45/6d80dc379b0bbc1f9d1e429f42e4cb9e1d319c7a8201beffd967c516ea01/cryptography-46.0.7-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:b36a4695e29fe69215d75960b22577197aca3f7a25b9cf9d165dcfe9d80bc325", size = 4275492, upload-time = "2026-04-08T01:56:19.36Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/9a/1765afe9f572e239c3469f2cb429f3ba7b31878c893b246b4b2994ffe2fe/cryptography-46.0.7-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:5ad9ef796328c5e3c4ceed237a183f5d41d21150f972455a9d926593a1dcb308", size = 4426670, upload-time = "2026-04-08T01:56:21.415Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/3e/af9246aaf23cd4ee060699adab1e47ced3f5f7e7a8ffdd339f817b446462/cryptography-46.0.7-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:73510b83623e080a2c35c62c15298096e2a5dc8d51c3b4e1740211839d0dea77", size = 4280275, upload-time = "2026-04-08T01:56:23.539Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/54/6bbbfc5efe86f9d71041827b793c24811a017c6ac0fd12883e4caa86b8ed/cryptography-46.0.7-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:cbd5fb06b62bd0721e1170273d3f4d5a277044c47ca27ee257025146c34cbdd1", size = 4928402, upload-time = "2026-04-08T01:56:25.624Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/cf/054b9d8220f81509939599c8bdbc0c408dbd2bdd41688616a20731371fe0/cryptography-46.0.7-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:420b1e4109cc95f0e5700eed79908cef9268265c773d3a66f7af1eef53d409ef", size = 4459985, upload-time = "2026-04-08T01:56:27.309Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/46/4e4e9c6040fb01c7467d47217d2f882daddeb8828f7df800cb806d8a2288/cryptography-46.0.7-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:24402210aa54baae71d99441d15bb5a1919c195398a87b563df84468160a65de", size = 3990652, upload-time = "2026-04-08T01:56:29.095Z" },
+    { url = "https://files.pythonhosted.org/packages/36/5f/313586c3be5a2fbe87e4c9a254207b860155a8e1f3cca99f9910008e7d08/cryptography-46.0.7-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:8a469028a86f12eb7d2fe97162d0634026d92a21f3ae0ac87ed1c4a447886c83", size = 4279805, upload-time = "2026-04-08T01:56:30.928Z" },
+    { url = "https://files.pythonhosted.org/packages/69/33/60dfc4595f334a2082749673386a4d05e4f0cf4df8248e63b2c3437585f2/cryptography-46.0.7-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:9694078c5d44c157ef3162e3bf3946510b857df5a3955458381d1c7cfc143ddb", size = 4892883, upload-time = "2026-04-08T01:56:32.614Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/0b/333ddab4270c4f5b972f980adef4faa66951a4aaf646ca067af597f15563/cryptography-46.0.7-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:42a1e5f98abb6391717978baf9f90dc28a743b7d9be7f0751a6f56a75d14065b", size = 4459756, upload-time = "2026-04-08T01:56:34.306Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/14/633913398b43b75f1234834170947957c6b623d1701ffc7a9600da907e89/cryptography-46.0.7-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:91bbcb08347344f810cbe49065914fe048949648f6bd5c2519f34619142bbe85", size = 4410244, upload-time = "2026-04-08T01:56:35.977Z" },
+    { url = "https://files.pythonhosted.org/packages/10/f2/19ceb3b3dc14009373432af0c13f46aa08e3ce334ec6eff13492e1812ccd/cryptography-46.0.7-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:5d1c02a14ceb9148cc7816249f64f623fbfee39e8c03b3650d842ad3f34d637e", size = 4674868, upload-time = "2026-04-08T01:56:38.034Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/bb/a5c213c19ee94b15dfccc48f363738633a493812687f5567addbcbba9f6f/cryptography-46.0.7-cp311-abi3-win32.whl", hash = "sha256:d23c8ca48e44ee015cd0a54aeccdf9f09004eba9fc96f38c911011d9ff1bd457", size = 3026504, upload-time = "2026-04-08T01:56:39.666Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/02/7788f9fefa1d060ca68717c3901ae7fffa21ee087a90b7f23c7a603c32ae/cryptography-46.0.7-cp311-abi3-win_amd64.whl", hash = "sha256:397655da831414d165029da9bc483bed2fe0e75dde6a1523ec2fe63f3c46046b", size = 3488363, upload-time = "2026-04-08T01:56:41.893Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/56/15619b210e689c5403bb0540e4cb7dbf11a6bf42e483b7644e471a2812b3/cryptography-46.0.7-cp314-cp314t-macosx_10_9_universal2.whl", hash = "sha256:d151173275e1728cf7839aaa80c34fe550c04ddb27b34f48c232193df8db5842", size = 7119671, upload-time = "2026-04-08T01:56:44Z" },
+    { url = "https://files.pythonhosted.org/packages/74/66/e3ce040721b0b5599e175ba91ab08884c75928fbeb74597dd10ef13505d2/cryptography-46.0.7-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:db0f493b9181c7820c8134437eb8b0b4792085d37dbb24da050476ccb664e59c", size = 4268551, upload-time = "2026-04-08T01:56:46.071Z" },
+    { url = "https://files.pythonhosted.org/packages/03/11/5e395f961d6868269835dee1bafec6a1ac176505a167f68b7d8818431068/cryptography-46.0.7-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:ebd6daf519b9f189f85c479427bbd6e9c9037862cf8fe89ee35503bd209ed902", size = 4408887, upload-time = "2026-04-08T01:56:47.718Z" },
+    { url = "https://files.pythonhosted.org/packages/40/53/8ed1cf4c3b9c8e611e7122fb56f1c32d09e1fff0f1d77e78d9ff7c82653e/cryptography-46.0.7-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:b7b412817be92117ec5ed95f880defe9cf18a832e8cafacf0a22337dc1981b4d", size = 4271354, upload-time = "2026-04-08T01:56:49.312Z" },
+    { url = "https://files.pythonhosted.org/packages/50/46/cf71e26025c2e767c5609162c866a78e8a2915bbcfa408b7ca495c6140c4/cryptography-46.0.7-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:fbfd0e5f273877695cb93baf14b185f4878128b250cc9f8e617ea0c025dfb022", size = 4905845, upload-time = "2026-04-08T01:56:50.916Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/ea/01276740375bac6249d0a971ebdf6b4dc9ead0ee0a34ef3b5a88c1a9b0d4/cryptography-46.0.7-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:ffca7aa1d00cf7d6469b988c581598f2259e46215e0140af408966a24cf086ce", size = 4444641, upload-time = "2026-04-08T01:56:52.882Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/4c/7d258f169ae71230f25d9f3d06caabcff8c3baf0978e2b7d65e0acac3827/cryptography-46.0.7-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:60627cf07e0d9274338521205899337c5d18249db56865f943cbe753aa96f40f", size = 3967749, upload-time = "2026-04-08T01:56:54.597Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/2a/2ea0767cad19e71b3530e4cad9605d0b5e338b6a1e72c37c9c1ceb86c333/cryptography-46.0.7-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:80406c3065e2c55d7f49a9550fe0c49b3f12e5bfff5dedb727e319e1afb9bf99", size = 4270942, upload-time = "2026-04-08T01:56:56.416Z" },
+    { url = "https://files.pythonhosted.org/packages/41/3d/fe14df95a83319af25717677e956567a105bb6ab25641acaa093db79975d/cryptography-46.0.7-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:c5b1ccd1239f48b7151a65bc6dd54bcfcc15e028c8ac126d3fada09db0e07ef1", size = 4871079, upload-time = "2026-04-08T01:56:58.31Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/59/4a479e0f36f8f378d397f4eab4c850b4ffb79a2f0d58704b8fa0703ddc11/cryptography-46.0.7-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:d5f7520159cd9c2154eb61eb67548ca05c5774d39e9c2c4339fd793fe7d097b2", size = 4443999, upload-time = "2026-04-08T01:57:00.508Z" },
+    { url = "https://files.pythonhosted.org/packages/28/17/b59a741645822ec6d04732b43c5d35e4ef58be7bfa84a81e5ae6f05a1d33/cryptography-46.0.7-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:fcd8eac50d9138c1d7fc53a653ba60a2bee81a505f9f8850b6b2888555a45d0e", size = 4399191, upload-time = "2026-04-08T01:57:02.654Z" },
+    { url = "https://files.pythonhosted.org/packages/59/6a/bb2e166d6d0e0955f1e9ff70f10ec4b2824c9cfcdb4da772c7dd69cc7d80/cryptography-46.0.7-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:65814c60f8cc400c63131584e3e1fad01235edba2614b61fbfbfa954082db0ee", size = 4655782, upload-time = "2026-04-08T01:57:04.592Z" },
+    { url = "https://files.pythonhosted.org/packages/95/b6/3da51d48415bcb63b00dc17c2eff3a651b7c4fed484308d0f19b30e8cb2c/cryptography-46.0.7-cp314-cp314t-win32.whl", hash = "sha256:fdd1736fed309b4300346f88f74cd120c27c56852c3838cab416e7a166f67298", size = 3002227, upload-time = "2026-04-08T01:57:06.91Z" },
+    { url = "https://files.pythonhosted.org/packages/32/a8/9f0e4ed57ec9cebe506e58db11ae472972ecb0c659e4d52bbaee80ca340a/cryptography-46.0.7-cp314-cp314t-win_amd64.whl", hash = "sha256:e06acf3c99be55aa3b516397fe42f5855597f430add9c17fa46bf2e0fb34c9bb", size = 3475332, upload-time = "2026-04-08T01:57:08.807Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/7f/cd42fc3614386bc0c12f0cb3c4ae1fc2bbca5c9662dfed031514911d513d/cryptography-46.0.7-cp38-abi3-macosx_10_9_universal2.whl", hash = "sha256:462ad5cb1c148a22b2e3bcc5ad52504dff325d17daf5df8d88c17dda1f75f2a4", size = 7165618, upload-time = "2026-04-08T01:57:10.645Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/d0/36a49f0262d2319139d2829f773f1b97ef8aef7f97e6e5bd21455e5a8fb5/cryptography-46.0.7-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:84d4cced91f0f159a7ddacad249cc077e63195c36aac40b4150e7a57e84fffe7", size = 4270628, upload-time = "2026-04-08T01:57:12.885Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/6c/1a42450f464dda6ffbe578a911f773e54dd48c10f9895a23a7e88b3e7db5/cryptography-46.0.7-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:128c5edfe5e5938b86b03941e94fac9ee793a94452ad1365c9fc3f4f62216832", size = 4415405, upload-time = "2026-04-08T01:57:14.923Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/92/4ed714dbe93a066dc1f4b4581a464d2d7dbec9046f7c8b7016f5286329e2/cryptography-46.0.7-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:5e51be372b26ef4ba3de3c167cd3d1022934bc838ae9eaad7e644986d2a3d163", size = 4272715, upload-time = "2026-04-08T01:57:16.638Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/e6/a26b84096eddd51494bba19111f8fffe976f6a09f132706f8f1bf03f51f7/cryptography-46.0.7-cp38-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:cdf1a610ef82abb396451862739e3fc93b071c844399e15b90726ef7470eeaf2", size = 4918400, upload-time = "2026-04-08T01:57:19.021Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/08/ffd537b605568a148543ac3c2b239708ae0bd635064bab41359252ef88ed/cryptography-46.0.7-cp38-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:1d25aee46d0c6f1a501adcddb2d2fee4b979381346a78558ed13e50aa8a59067", size = 4450634, upload-time = "2026-04-08T01:57:21.185Z" },
+    { url = "https://files.pythonhosted.org/packages/16/01/0cd51dd86ab5b9befe0d031e276510491976c3a80e9f6e31810cce46c4ad/cryptography-46.0.7-cp38-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:cdfbe22376065ffcf8be74dc9a909f032df19bc58a699456a21712d6e5eabfd0", size = 3985233, upload-time = "2026-04-08T01:57:22.862Z" },
+    { url = "https://files.pythonhosted.org/packages/92/49/819d6ed3a7d9349c2939f81b500a738cb733ab62fbecdbc1e38e83d45e12/cryptography-46.0.7-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:abad9dac36cbf55de6eb49badd4016806b3165d396f64925bf2999bcb67837ba", size = 4271955, upload-time = "2026-04-08T01:57:24.814Z" },
+    { url = "https://files.pythonhosted.org/packages/80/07/ad9b3c56ebb95ed2473d46df0847357e01583f4c52a85754d1a55e29e4d0/cryptography-46.0.7-cp38-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:935ce7e3cfdb53e3536119a542b839bb94ec1ad081013e9ab9b7cfd478b05006", size = 4879888, upload-time = "2026-04-08T01:57:26.88Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/c7/201d3d58f30c4c2bdbe9b03844c291feb77c20511cc3586daf7edc12a47b/cryptography-46.0.7-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:35719dc79d4730d30f1c2b6474bd6acda36ae2dfae1e3c16f2051f215df33ce0", size = 4449961, upload-time = "2026-04-08T01:57:29.068Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/ef/649750cbf96f3033c3c976e112265c33906f8e462291a33d77f90356548c/cryptography-46.0.7-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:7bbc6ccf49d05ac8f7d7b5e2e2c33830d4fe2061def88210a126d130d7f71a85", size = 4401696, upload-time = "2026-04-08T01:57:31.029Z" },
+    { url = "https://files.pythonhosted.org/packages/41/52/a8908dcb1a389a459a29008c29966c1d552588d4ae6d43f3a1a4512e0ebe/cryptography-46.0.7-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:a1529d614f44b863a7b480c6d000fe93b59acee9c82ffa027cfadc77521a9f5e", size = 4664256, upload-time = "2026-04-08T01:57:33.144Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/fa/f0ab06238e899cc3fb332623f337a7364f36f4bb3f2534c2bb95a35b132c/cryptography-46.0.7-cp38-abi3-win32.whl", hash = "sha256:f247c8c1a1fb45e12586afbb436ef21ff1e80670b2861a90353d9b025583d246", size = 3013001, upload-time = "2026-04-08T01:57:34.933Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/f1/00ce3bde3ca542d1acd8f8cfa38e446840945aa6363f9b74746394b14127/cryptography-46.0.7-cp38-abi3-win_amd64.whl", hash = "sha256:506c4ff91eff4f82bdac7633318a526b1d1309fc07ca76a3ad182cb5b686d6d3", size = 3472985, upload-time = "2026-04-08T01:57:36.714Z" },
+]
+
 [[package]]
 name = "curl-cffi"
 version = "0.15.0"
@@ -1216,7 +1269,7 @@ requires-dist = [
     { name = "langchain-openai", specifier = "==1.1.12" },
     { name = "langfuse", specifier = "==4.0.4" },
     { name = "langgraph", specifier = ">=1.1.2" },
-    { name = "mcp", specifier = "==1.15.0" },
+    { name = "mcp", specifier = ">=1.21.0,<2.0.0" },
     { name = "openevals" },
     { name = "pydantic", specifier = "==2.12.5" },
     { name = "pymupdf", specifier = "==1.26.3" },
@@ -1537,7 +1590,7 @@ wheels = [
 
 [[package]]
 name = "mcp"
-version = "1.15.0"
+version = "1.27.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
@@ -1546,15 +1599,18 @@ dependencies = [
     { name = "jsonschema" },
     { name = "pydantic" },
     { name = "pydantic-settings" },
+    { name = "pyjwt", extra = ["crypto"] },
     { name = "python-multipart" },
     { name = "pywin32", marker = "sys_platform == 'win32'" },
     { name = "sse-starlette" },
     { name = "starlette" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
     { name = "uvicorn", marker = "sys_platform != 'emscripten'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/0c/9e/e65114795f359f314d7061f4fcb50dfe60026b01b52ad0b986b4631bf8bb/mcp-1.15.0.tar.gz", hash = "sha256:5bda1f4d383cf539d3c035b3505a3de94b20dbd7e4e8b4bd071e14634eeb2d72", size = 469622, upload-time = "2025-09-25T15:39:51.995Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/8b/eb/c0cfc62075dc6e1ec1c64d352ae09ac051d9334311ed226f1f425312848a/mcp-1.27.0.tar.gz", hash = "sha256:d3dc35a7eec0d458c1da4976a48f982097ddaab87e278c5511d5a4a56e852b83", size = 607509, upload-time = "2026-04-02T14:48:08.88Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/c9/82/4d0df23d5ff5bb982a59ad597bc7cb9920f2650278ccefb8e0d85c5ce3d4/mcp-1.15.0-py3-none-any.whl", hash = "sha256:314614c8addc67b663d6c3e4054db0a5c3dedc416c24ef8ce954e203fdc2333d", size = 166963, upload-time = "2025-09-25T15:39:50.538Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/46/f6b4ad632c67ef35209a66127e4bddc95759649dd595f71f13fba11bdf9a/mcp-1.27.0-py3-none-any.whl", hash = "sha256:5ce1fa81614958e267b21fb2aa34e0aea8e2c6ede60d52aba45fd47246b4d741", size = 215967, upload-time = "2026-04-02T14:48:07.24Z" },
 ]
 
 [[package]]
@@ -2411,6 +2467,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" },
 ]
 
+[[package]]
+name = "pyjwt"
+version = "2.12.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c2/27/a3b6e5bf6ff856d2509292e95c8f57f0df7017cf5394921fc4e4ef40308a/pyjwt-2.12.1.tar.gz", hash = "sha256:c74a7a2adf861c04d002db713dd85f84beb242228e671280bf709d765b03672b", size = 102564, upload-time = "2026-03-13T19:27:37.25Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/7a/8dd906bd22e79e47397a61742927f6747fe93242ef86645ee9092e610244/pyjwt-2.12.1-py3-none-any.whl", hash = "sha256:28ca37c070cad8ba8cd9790cd940535d40274d22f80ab87f3ac6a713e6e8454c", size = 29726, upload-time = "2026-03-13T19:27:35.677Z" },
+]
+
+[package.optional-dependencies]
+crypto = [
+    { name = "cryptography" },
+]
+
 [[package]]
 name = "pymupdf"
 version = "1.26.3"