Lab 01 · Ticket classifier

langchain==1.4.2
langchain-core==1.6.4
langchain-openai==1.6.2
python-dotenv==1.2.3
pydantic==2.13.5

# 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 01: classify a batch of Northwind support tickets into typed records.

Run:  python ticket_classifier.py
"""

from enum import Enum

from langchain.messages import HumanMessage, SystemMessage
from langchain_core.language_models import BaseChatModel
from langchain_core.runnables import Runnable
from pydantic import BaseModel, Field, ValidationError, field_validator

from model_setup import get_model

class Category(str, Enum):
    """Northwind support taxonomy. Keep it small: models pick badly from thirty labels."""

    BILLING = "billing"
    SHIPPING = "shipping"
    TECHNICAL = "technical"
    ACCOUNT = "account"
    RETURNS = "returns"
    OTHER = "other"

class Sentiment(str, Enum):
    """How the customer sounds. It decides whether a human reads the reply first."""

    ANGRY = "angry"
    FRUSTRATED = "frustrated"
    NEUTRAL = "neutral"
    POSITIVE = "positive"

class TicketClassification(BaseModel):
    """One support ticket as a typed record. Every description is a per-field prompt."""

    category: Category = Field(description="The single best-fitting support category.")
    urgency: int = Field(ge=1, le=5, description="1 = can wait a week, 5 = outage or money lost.")
    sentiment: Sentiment = Field(description="The emotional tone of the customer.")
    order_id: str | None = Field(
        default=None, description="Order id like 'A-100', not an invoice number. Null if absent."
    )
    summary: str = Field(max_length=200, description="One sentence on what the customer needs.")

    @field_validator("order_id", mode="before")
    @classmethod
    def blank_to_none(cls, value: str | None) -> str | None:
        """Models answer 'none' or 'N/A' far more often than a real JSON null."""
        if value is None or value.strip().upper() in {"", "NONE", "NULL", "N/A"}:
            return None
        return value.strip().upper()

SYSTEM_PROMPT = (
    "You are the triage engine for Northwind support. Classify exactly one ticket into the "
    "schema. Use only facts present in the ticket: never invent an order id. Urgency 5 is "
    "reserved for outages, security issues and money already lost."
)

TICKETS = [
    "My card was charged twice for invoice INV-9912. Fix this today!",
    "Where is order A-100? It was supposed to arrive on Tuesday.",
    "The export API returns 500 for every request since this morning.",
    "Thanks for the quick replacement on A-118, works perfectly now.",
    "I would like to return order A-205, the size is wrong.",
    "Cannot log in, the password reset email never arrives.",
]

def check_schema() -> None:
    """Show the schema rules working locally, without calling the model."""
    print("Schema checks (no model call):")
    record = TicketClassification(
        category="shipping", urgency=2, sentiment="neutral", order_id="  a-100 ", summary="Test."
    )
    print(f"  order_id '  a-100 ' -> {record.order_id!r}")
    record = TicketClassification(
        category="shipping", urgency=2, sentiment="neutral", order_id="N/A", summary="Test."
    )
    print(f"  order_id 'N/A'      -> {record.order_id!r}")
    try:
        TicketClassification(category="billing", urgency=9, sentiment="angry", summary="Test.")
    except ValidationError as error:
        print(f"  urgency=9           -> ValidationError: {error.errors()[0]['msg']}")
    print()

def build_classifier(model: BaseChatModel | None = None) -> Runnable:
    """Wrap the chat model so every answer comes back as a TicketClassification."""
    model = model or get_model()
    return model.with_structured_output(TicketClassification)

if __name__ == "__main__":
    check_schema()

    classifier = build_classifier()
    prompts = [[SystemMessage(SYSTEM_PROMPT), HumanMessage(ticket)] for ticket in TICKETS]

    # One call per ticket, at most three in flight, results in input order.
    print("Classified tickets:")
    for facts in classifier.batch(prompts, config={"max_concurrency": 3}):
        print(
            f"{facts.category.value:10} u{facts.urgency} {facts.sentiment.value:10} "
            f"order={facts.order_id or '-':6} {facts.summary}"
        )

Schema checks (no model call):
  order_id '  a-100 ' -> 'A-100'
  order_id 'N/A'      -> None
  urgency=9           -> ValidationError: Input should be less than or equal to 5

Classified tickets:
billing    u5 angry      order=-      Customer reports their card was charged twice for invoice INV-9912 and requests it be fixed today.
shipping   u3 frustrated order=A-100  Customer asks for the location/status of order A-100, which was supposed to arrive on Tuesday but has not.
technical  u5 neutral    order=-      The export API returns HTTP 500 for every request since this morning; please investigate and restore the service.
returns    u1 positive   order=A-118  Customer confirms the replacement for order A-118 works perfectly and thanks support.
returns    u2 neutral    order=A-205  Customer wants to return order A-205 because the item is the wrong size.
account    u3 frustrated order=-      User cannot log in because the password reset email never arrives; they need assistance to receive the reset email or regain account access.