Jev Python Tutorial: Classify and Score Text

from typesafe_sdk import Choice

category = Choice(
    instructions="Which category best describes this customer message?",
    criteria={
        "billing": "Charges, invoices, refunds, payment methods, subscription costs",
        "account": "Login, password, profile, permissions, closing or changing an account",
        "technical": "Bugs, errors, outages, integrations, something not working",
        "sales": "Pricing questions, plan comparisons, upgrades, purchasing for a team",
        "other": "Anything that does not fit the departments above",
    },
)

from typesafe_sdk import Score

urgency = Score(
    instructions="How urgently does this message need a response from support?",
    criteria=[
        "Routine. A general question, comment, or minor request with no deadline or breakage implied.",
        "Time-sensitive. Something is blocked or inconvenient, but there is a reasonable window to respond.",
        "Urgent. Active harm, an outage, a security exposure, or a deadline that has already arrived.",
    ],
)

from typesafe_sdk import Noul, NoulCriteria

wants_refund = Noul(
    instructions="Does the customer explicitly request a refund?",
    criteria=NoulCriteria(
        true="The message explicitly asks for money back or a refund",
        false="The message does not ask for money back",
    ),
)

from typesafe_sdk import TypeSafeClient

# category, urgency, and wants_refund are the three Question objects built above.
# All three are asked over the same message in a single round trip; none of them
# depends on another's answer.
with TypeSafeClient() as client:
    response = client.system_one(
        state=message,
        model="jev-latest",
        questions={
            "category": category,
            "urgency": urgency,
            "wants_refund": wants_refund,
        },
    )

"""Classify a support message with Jev: category, urgency, and refund intent.

Requires Python 3.10+ and TYPESAFE_API_KEY in the environment.
    pip install typesafe-sdk
Walkthrough: https://jevguide.ai/guides/jev-python
Not installed, executed, or type-checked here; its syntax is checked by this
repo's test suite (tests/classify-message-example.test.ts) and its category
and urgency criteria are checked against src/lib/classification.ts and
src/lib/recipes.ts so this file can't silently drift from the rest of the site.
"""

import os
import sys

from typesafe_sdk import (
    Choice,
    Noul,
    NoulCriteria,
    Score,
    TypeSafeAPIConnectionError,
    TypeSafeAPIError,
    TypeSafeClient,
    TypeSafeError,
)

if not os.environ.get("TYPESAFE_API_KEY"):
    print("Set TYPESAFE_API_KEY first, e.g.: export TYPESAFE_API_KEY=your-key-here", file=sys.stderr)
    raise SystemExit(1)

message = (
    "Hi, I was charged twice for my subscription this month. The two charges show up "
    "on my card statement on the 3rd and the 4th. Can you refund one of them?"
)

try:
    with TypeSafeClient() as client:
        response = client.system_one(
            state=message,
            model="jev-latest",
            questions={
                # Choice: a small, closed set of categories with no order between them.
                # "other" is required so a message that fits none of them still gets a clean answer.
                "category": Choice(
                    instructions="Which category best describes this customer message?",
                    criteria={
                        "billing": "Charges, invoices, refunds, payment methods, subscription costs",
                        "account": "Login, password, profile, permissions, closing or changing an account",
                        "technical": "Bugs, errors, outages, integrations, something not working",
                        "sales": "Pricing questions, plan comparisons, upgrades, purchasing for a team",
                        "other": "Anything that does not fit the departments above",
                    },
                ),
                # Score: urgency sits on a spectrum, so an ordered rubric fits better than a
                # yes/no split. This asks how urgently the message needs a reply, not how
                # frustrated the customer sounds; a calm message can still be urgent, and an
                # angry one can still be routine.
                "urgency": Score(
                    instructions="How urgently does this message need a response from support?",
                    criteria=[
                        "Routine. A general question, comment, or minor request with no deadline or breakage implied.",
                        "Time-sensitive. Something is blocked or inconvenient, but there is a reasonable window to respond.",
                        "Urgent. Active harm, an outage, a security exposure, or a deadline that has already arrived.",
                    ],
                ),
                # Noul: a single yes/no probability is the useful signal here, not a label.
                "wants_refund": Noul(
                    instructions="Does the customer explicitly request a refund?",
                    criteria=NoulCriteria(
                        true="The message explicitly asks for money back or a refund",
                        false="The message does not ask for money back",
                    ),
                ),
            },
        )
except TypeSafeAPIConnectionError as err:
    print(f"Could not reach TypeSafe: {err}", file=sys.stderr)
    raise SystemExit(1)
except TypeSafeAPIError as err:
    print(f"TypeSafe rejected the request: {err}", file=sys.stderr)
    raise SystemExit(1)
except TypeSafeError as err:
    # Covers local validation errors, e.g. an empty questions dict or an
    # empty Score criteria list. Raised before any request is sent.
    print(f"Bad request to TypeSafe: {err}", file=sys.stderr)
    raise SystemExit(1)

# The three questions share the same `message` as context but do not depend on
# each other's answers: this is one round trip, not three, and the request
# would return the same category, urgency, and refund answers if only one of
# the three questions were asked.
category = response.answers["category"]
urgency = response.answers["urgency"]
refund = response.answers["wants_refund"]

print(f"Category:  {category.choice}  (confidence {category.confidence:.2f})")
print(f"           {category.probabilities}")

level = round(urgency.score)
print(f"Urgency:   level {level}: {urgency.legend[level]}")
print(f"           (score {urgency.score:.2f}, confidence {urgency.confidence:.2f})")

if refund.noul >= 0.7:
    refund_read = "likely yes"
elif refund.noul <= 0.3:
    refund_read = "likely no"
else:
    refund_read = "unclear"
print(f"Refund ask: {refund.noul:.2f}  ({refund_read})")

# Your code decides what to do with these answers; Jev only classifies.
# A confidence floor like this is a starting point, not a number TypeSafe
# recommends universally; evaluate it against your own data before trusting it.
if category.confidence < 0.5:
    print("Category is uncertain enough to route to a person instead of automating.")

# Illustrative: 0.5 is a starting point, not a value TypeSafe recommends
# universally. Tune it against your own data before trusting it.
if category.confidence < 0.5:
    send_to_review_queue(message)  # your own queue, not part of the SDK
else:
    route_to(category.choice)

from typesafe_sdk import (
    TypeSafeAPIConnectionError,
    TypeSafeAuthenticationError,
    TypeSafeRateLimitError,
    TypeSafeAPIError,
    TypeSafeError,
)

try:
    response = client.system_one(state=message, model="jev-latest", questions=questions)
except TypeSafeAuthenticationError:
    print("Invalid or missing TYPESAFE_API_KEY.")
except TypeSafeRateLimitError as err:
    # The SDK already retried this internally before raising; it only
    # reaches here once the default retry budget is exhausted.
    print(f"Still rate limited after retries; server asked for {err.retry_after_ms}ms.")
except TypeSafeAPIConnectionError:
    print("Could not reach TypeSafe, or the request timed out.")
except TypeSafeAPIError as err:
    print(f"TypeSafe rejected the request: {err.status} {err}")
except TypeSafeError as err:
    print(f"Bad question definition: {err}")