feat: high-level pydantic API for classification #3

Proposal: High-level pydantic API for TypeSafe classification

Problem

The current SDK requires constructing question objects manually and using a context manager, which is verbose for common classification tasks:

with TypeSafeClient() as client:
    response = client.system_one(
        state="I was charged twice",
        questions={
            "billing": Noul(instructions="Is this billing?"),
            "tone": Choice(instructions="Tone?", criteria={"calm": None, "angry": None}),
        },
    )
print(response.choices["tone"].choice)

Proposed solution

A pydantic-based schema layer with three API shapes:

1. Simple function (single call):

from typesafe_sdk import typesafe

result = typesafe("I was charged twice", billing="Is this billing?", tone="calm|angry")
result["billing"]  # 0.98
result["tone"]     # "calm"

2. Typed schema (structured results):

from typesafe_sdk import typesafe, TypeSafeSchema
from typing import Literal

class Classification(TypeSafeSchema):
    billing: bool
    tone: Literal["calm", "angry"]

result = typesafe("I was charged twice", model=Classification)
result.billing  # True
result.tone     # "calm"

3. Decorator (function signature as schema):

from typesafe_sdk import typesafe

@typesafe
def classify(ticket: str, *, billing: bool, tone: Literal["calm", "angry"]):
    pass

result = classify("I was charged twice")
result.billing  # True
result.tone     # "calm"

Design decisions

• msgspec stays for wire serialization. It handles tagged unions, Raw deferred parsing, and key coercion in ways pydantic cannot. The two libraries serve different layers: msgspec for the wire, pydantic for the user-facing schema.
• _core/ untouched. New code sits on top, reusing TypeSafeClient internally.
• Backwards compatible. Existing TypeSafeClient API works unchanged.

Type mapping

Implementation

A working implementation is available at https://github.com/emiliano-go/typesafe-sdk-python with two PRs:

• PR Doc fix: output #2: Schema layer + simple API (+1939 lines, 106 tests)
• PR feat: high-level pydantic API for classification #3: Decorator API (+783 lines, 35 tests)

All 656 existing tests pass. _core/ is completely unaffected.

Questions for maintainers

1. Is pydantic an acceptable new dependency, or should it be an optional extra?
2. Any preference on naming (e.g. typesafe() vs classify())?
3. Should this target main or a feature branch?