Lab 09 · Guarded refunds

langchain==1.4.2
langchain-core==1.6.4
langchain-openai==1.6.2
python-dotenv==1.2.3
langgraph==1.2.11

# Azure OpenAI settings. Your instructor gives you these three values.
AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/openai/v1
AZURE_OPENAI_API_KEY=<paste-your-key-here>
AZURE_OPENAI_DEPLOYMENT=<your-chat-deployment-name>

# Only used when your endpoint does NOT end in /openai/v1.
OPENAI_API_VERSION=2025-04-01-preview

"""Azure OpenAI model setup shared by every lab.

Import it in lab code as:  from model_setup import get_model, get_embeddings
"""

import asyncio
import os
import sys

from dotenv import load_dotenv
from langchain_core.embeddings import Embeddings
from langchain_core.language_models import BaseChatModel

# Read AZURE_OPENAI_* values from the .env file next to your lab code.
load_dotenv()

# Windows consoles default to cp1252 and crash on the curly quotes models love to print.
for _stream in (sys.stdout, sys.stderr):
    if hasattr(_stream, "reconfigure"):
        _stream.reconfigure(encoding="utf-8", errors="replace")

def _setting(name: str) -> str:
    """Return a required setting from .env, or stop with a readable message."""
    value = os.getenv(name, "").strip()
    if not value:
        sys.exit(f"Missing {name} in your .env file. Open .env and fill it in.")
    return value


def _uses_v1_api(endpoint: str) -> bool:
    """True for the OpenAI-compatible Azure endpoint that ends in /openai/v1."""
    return endpoint.rstrip("/").endswith("/openai/v1")

def get_model(deployment: str | None = None, **kwargs) -> BaseChatModel:
    """Return a chat model for your Azure OpenAI deployment."""
    endpoint = _setting("AZURE_OPENAI_ENDPOINT")
    api_key = _setting("AZURE_OPENAI_API_KEY")
    name = deployment or _setting("AZURE_OPENAI_DEPLOYMENT")

    if _uses_v1_api(endpoint):
        from langchain_openai import ChatOpenAI

        return ChatOpenAI(model=name, base_url=endpoint, api_key=api_key, **kwargs)

    from langchain_openai import AzureChatOpenAI

    return AzureChatOpenAI(
        azure_deployment=name,
        azure_endpoint=endpoint,
        api_key=api_key,
        api_version=os.getenv("OPENAI_API_VERSION", "2025-04-01-preview"),
        **kwargs,
    )

def get_embeddings(deployment: str | None = None) -> Embeddings:
    """Return an embeddings model for your Azure OpenAI embeddings deployment."""
    endpoint = _setting("AZURE_OPENAI_ENDPOINT")
    api_key = _setting("AZURE_OPENAI_API_KEY")
    name = deployment or _setting("AZURE_OPENAI_EMBEDDING_DEPLOYMENT")

    if _uses_v1_api(endpoint):
        from langchain_openai import OpenAIEmbeddings

        return OpenAIEmbeddings(model=name, base_url=endpoint, api_key=api_key)

    from langchain_openai import AzureOpenAIEmbeddings

    return AzureOpenAIEmbeddings(
        azure_deployment=name,
        azure_endpoint=endpoint,
        api_key=api_key,
        api_version=os.getenv("OPENAI_API_VERSION", "2025-04-01-preview"),
    )

def use_stable_event_loop() -> None:
    """On Windows, use the Selector event loop so async MCP code exits cleanly."""
    if sys.platform == "win32":
        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

"""Lab 09: the Northwind refund agent behind four layers of defence.

An off-topic filter, PII redaction, an approval gate over 100 USD, and a hard cap in
`wrap_tool_call`. The last layer trusts neither the model nor the human reviewer.

Run:  python guarded_refunds.py
"""

from typing import Any, Callable

from langchain.agents import AgentState, create_agent
from langchain.agents.middleware import (
    HumanInTheLoopMiddleware,
    PIIMiddleware,
    ToolCallLimitMiddleware,
    ToolCallRequest,
    before_agent,
    wrap_tool_call,
)
from langchain.messages import AIMessage, ToolMessage
from langchain.tools import tool
from langchain_core.language_models import BaseChatModel
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.runtime import Runtime
from langgraph.types import Command

from model_setup import get_model

APPROVAL_THRESHOLD_USD = 100.0  # above this, a human decides
HARD_REFUND_CAP_USD = 500.0  # nobody exceeds this, not even an approving human
BLOCKED_TOPICS = {"medical advice", "legal advice", "stock tips", "crypto"}
REFUSAL = "I can only help with Northwind orders, billing and refunds."
ORDERS = {"A-100": 249.00, "A-101": 1299.50, "A-102": 42.00}
REFUND_LEDGER: list[dict[str, Any]] = []  # the side effect we protect; in production, a payments API

@tool
def get_order(order_id: str) -> str:
    """Look up an order's total. Use before discussing or refunding an order."""
    total = ORDERS.get(order_id.upper())
    if total is None:
        return f"No order found with id {order_id}."
    return f"Order {order_id.upper()} total: {total:.2f} USD."


@tool
def issue_refund(order_id: str, amount: float) -> str:
    """Refund money to the customer for an order. Destructive, irreversible, real money."""
    REFUND_LEDGER.append({"order_id": order_id.upper(), "amount": amount})
    return f"Refunded {amount:.2f} USD on order {order_id.upper()}."

@before_agent(can_jump_to=["end"])
def block_off_topic(state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
    """Layer 1: refuse out-of-scope requests before a single token is spent."""
    if any(topic in state["messages"][-1].text.lower() for topic in BLOCKED_TOPICS):
        return {"messages": [AIMessage(REFUSAL)], "jump_to": "end"}
    return None

def needs_approval(request: Any) -> bool:
    """Layer 3: interrupt only above the auto-approve limit, so reviewers stay awake."""
    return request.tool_call["args"]["amount"] > APPROVAL_THRESHOLD_USD

@wrap_tool_call
def refund_policy(request: ToolCallRequest, handler: Callable[[ToolCallRequest], Any]) -> Any:
    """Layer 4: the hard floor. It validates the arguments that execute, whoever chose them."""
    if request.tool_call["name"] != "issue_refund":
        return handler(request)
    amount = request.tool_call["args"]["amount"]
    if amount <= HARD_REFUND_CAP_USD:
        return handler(request)
    return ToolMessage(
        content=f"Refused by refund policy: {amount:.2f} USD is above the "
        f"{HARD_REFUND_CAP_USD:.0f} USD hard cap. Tell the customer a specialist will review it.",
        tool_call_id=request.tool_call["id"],
        status="error",  # an error result lets the model apologise instead of crashing
    )

SYSTEM_PROMPT = (
    "You are the Northwind support assistant. Look an order up with get_order before you "
    "refund it, and refund only what the customer actually paid."
)

def build_agent(model: BaseChatModel | None = None):
    """Build the guarded agent. Pass a model to override the Azure OpenAI default."""
    return create_agent(
        model=model or get_model(),
        tools=[get_order, issue_refund],
        system_prompt=SYSTEM_PROMPT,
        middleware=[
            block_off_topic,  # 1. cheapest and most certain first
            PIIMiddleware("email", strategy="redact"),  # 2. keep PII out of model and checkpoint
            PIIMiddleware("credit_card", strategy="mask", apply_to_output=True),
            HumanInTheLoopMiddleware(  # 3. a human decides the expensive ones
                interrupt_on={
                    "issue_refund": {
                        "allowed_decisions": ["approve", "edit", "reject"],
                        "when": needs_approval,
                    },
                    "get_order": False,  # explicit: reads are auto-approved
                },
                description_prefix="Northwind refund approval",
            ),
            refund_policy,  # 4. policy code has the last word, over the model AND the human
            # A safety net, not a guardrail: one refund per conversation, whatever happens.
            ToolCallLimitMiddleware(tool_name="issue_refund", thread_limit=1),
        ],
        checkpointer=InMemorySaver(),  # an interrupt has nowhere to live without one
    )

def show(messages: list[Any]) -> None:
    """Print each message type with its text or its tool calls."""
    for message in messages:
        print(f"  {type(message).__name__:14} {message.text or message.tool_calls}")


if __name__ == "__main__":
    agent = build_agent()

    print("== Layer 1: an off-topic request never reaches the model")
    blocked = agent.invoke(
        {"messages": [{"role": "user", "content": "Any crypto tips for me?"}]},
        {"configurable": {"thread_id": "lab09-blocked"}},
    )
    show(blocked["messages"])

    print("\n== Layers 2-4: a refund request with an email address in it")
    config = {"configurable": {"thread_id": "lab09"}}
    question = "Order A-100 arrived broken, refund it in full. I'm ada@northwind.example."
    paused = agent.invoke({"messages": [{"role": "user", "content": question}]}, config)

    interrupts = paused.get("__interrupt__")
    if not interrupts:
        print("The model did not call issue_refund, so there is nothing to approve. It said:")
        show(paused["messages"])
    else:
        print("awaiting approval:", interrupts[0].value["action_requests"][0]["args"])

        # A real approval UI collects this from a reviewer. This one edits the amount up to
        # 5,000 USD, and layer 4 refuses it anyway, because approval is not authorisation.
        decision = {
            "type": "edit",
            "edited_action": {"name": "issue_refund", "args": {"order_id": "A-100", "amount": 5000.0}},
        }
        result = agent.invoke(Command(resume={"decisions": [decision]}), config)
        show(result["messages"])

    print("ledger:", REFUND_LEDGER)

== Layer 1: an off-topic request never reaches the model
  HumanMessage   Any crypto tips for me?
  AIMessage      I can only help with Northwind orders, billing and refunds.

== Layers 2-4: a refund request with an email address in it
awaiting approval: {'order_id': 'A-100', 'amount': 249}
  HumanMessage   Order A-100 arrived broken, refund it in full. I'm [REDACTED_EMAIL].
  AIMessage      [{'name': 'get_order', 'args': {'order_id': 'A-100'}, 'id': 'call_1YmBklWZxEOGhbrZ909X3vlM', 'type': 'tool_call'}]
  ToolMessage    Order A-100 total: 249.00 USD.
  AIMessage      [{'name': 'issue_refund', 'args': {'order_id': 'A-100', 'amount': 249}, 'id': 'call_NhWiHKagUs7YzMe2sxZVnmzZ', 'type': 'tool_call'}]
  ToolMessage    Note: a human reviewer replaced this tool call before it ran. The call recorded in your message is the one you produced, not the one that executed. This was intentional and authorized. Do not re-issue your original call. Executed instead: issue_refund with arguments {"order_id": "A-100", "amount": 5000.0}.

Tool response:
Refused by refund policy: 5000.00 USD is above the 500 USD hard cap. Tell the customer a specialist will review it.
  AIMessage      [{'name': 'issue_refund', 'args': {'order_id': 'A-100', 'amount': 249}, 'id': 'call_4KzBNaHO7Ni8sHA0iub9GWlj', 'type': 'tool_call'}]
  ToolMessage    Tool call limit exceeded. Do not call 'issue_refund' again.
ledger: []