dottxt SDK

The dottxt Python SDK accepts a wide range of Python types as response_format on generate(...), for many shapes you don’t need to write or generate JSON Schema at all.

Install

pip install dottxt

Supported `response_format` types

DotTxt.generate(...) and AsyncDotTxt.generate(...) accept response_format as any of:

a Pydantic model class
a TypedDict type
a dataclass type
an Enum class
a typing.Literal[...] type
a typing.Union[...] type
a typing.Optional[...] type
typed containers such as list[...], dict[...], tuple[...]
a JSON string containing JSON Schema
a JSON object (dict)

The return type follows the input: a Pydantic model class returns a validated model instance, and other supported types return parsed JSON.

Pydantic model

Use a Pydantic model when you want runtime validation alongside generation. The result is a validated model instance.

Python

from typing import Literal

from pydantic import BaseModel, Field

from dottxt import DotTxt


class IncidentSummary(BaseModel):
    severity: Literal["low", "medium", "high"]
    team: str = Field(max_length=32)


client = DotTxt()
result = client.generate(
    model="openai/gpt-oss-20b",
    input=(
        "Summarize this incident: checkout errors are blocking purchases. "
        "Return a JSON object with keys severity and team."
    ),
    response_format=IncidentSummary,
)
print(result)
# severity='high' team='checkout'
print(result.model_dump())
# {'severity': 'high', 'team': 'checkout'}

See Pydantic for the full schema mapping.

TypedDict

Use a TypedDict for a lightweight class declaration without Pydantic as a dependency. The result is a plain dict.

Python

from __future__ import annotations

from typing import Literal, TypedDict

from dottxt import DotTxt


class IncidentPayload(TypedDict):
    severity: Literal["low", "medium", "high"]
    team: str


client = DotTxt()
result = client.generate(
    model="openai/gpt-oss-20b",
    input=(
        "Summarize this incident: checkout errors are blocking purchases. "
        "Return a JSON object with keys severity and team."
    ),
    response_format=IncidentPayload,
)
print(result)
# {'severity': 'high', 'team': 'checkout'}

Dataclass

Standard library @dataclass types are supported as well.

Python

from __future__ import annotations

from dataclasses import dataclass
from typing import Literal

from dottxt import DotTxt


@dataclass
class IncidentPayload:
    severity: Literal["low", "medium", "high"]
    team: str


client = DotTxt()
result = client.generate(
    model="openai/gpt-oss-20b",
    input=(
        "Summarize this incident: checkout errors are blocking purchases. "
        "Return a JSON object with keys severity and team."
    ),
    response_format=IncidentPayload,
)
print(result)
# {'severity': 'high', 'team': 'checkout'}

Enum and Literal

Pass an Enum class or a typing.Literal[...] when the entire output is a single value drawn from a fixed set.

Python

from enum import Enum
from typing import Literal

from dottxt import DotTxt


class Severity(str, Enum):
    low = "low"
    medium = "medium"
    high = "high"


client = DotTxt()

severity = client.generate(
    model="openai/gpt-oss-20b",
    input="Classify the severity of: checkout errors are blocking purchases.",
    response_format=Severity,
)
print(severity)
# 'high'

label = client.generate(
    model="openai/gpt-oss-20b",
    input="Classify the sentiment of: 'I love this product!'",
    response_format=Literal["positive", "negative", "neutral"],
)
print(label)
# 'positive'

Union and Optional

typing.Union[...] and typing.Optional[...] constrain the output to one of several types.

Python

from typing import Optional, Union

from dottxt import DotTxt


client = DotTxt()

value = client.generate(
    model="openai/gpt-oss-20b",
    input="How many incidents this week? Reply with a number, or null if unknown.",
    response_format=Optional[int],
)
print(value)

mixed = client.generate(
    model="openai/gpt-oss-20b",
    input="Reply with the user's age as an integer, or their name as a string.",
    response_format=Union[int, str],
)
print(mixed)

Typed containers

Typed containers like list[...], dict[...], and tuple[...] work directly.

Python

from dottxt import DotTxt


client = DotTxt()

teams = client.generate(
    model="openai/gpt-oss-20b",
    input="List three engineering teams that own checkout systems.",
    response_format=list[str],
)
print(teams)
# ['checkout', 'payments', 'orders']

scores = client.generate(
    model="openai/gpt-oss-20b",
    input="Score each team's incident impact on a scale of 0-10.",
    response_format=dict[str, int],
)
print(scores)
# {'checkout': 9, 'payments': 6, 'orders': 4}

JSON Schema (string or dict)

You can also pass JSON Schema directly as a Python dict or as a JSON string. This is useful when you have a schema authored elsewhere — by hand, by Quicktype, by Genson, or shared from another service.

Python

from dottxt import DotTxt


schema = {
    "type": "object",
    "properties": {
        "severity": {"type": "string", "enum": ["low", "medium", "high"]},
        "team": {"type": "string", "maxLength": 32},
    },
    "required": ["severity", "team"],
    "additionalProperties": False,
}

client = DotTxt()
result = client.generate(
    model="openai/gpt-oss-20b",
    input="Summarize this incident: checkout errors are blocking purchases.",
    response_format=schema,
)
print(result)
# {'severity': 'high', 'team': 'checkout'}

Fundamentals

Authoring

Patterns and Use Cases

Reference

Install

Supported `response_format` types

Pydantic model

TypedDict

Dataclass

Enum and Literal

Union and Optional

Typed containers

JSON Schema (string or dict)

​Install

​Supported response_format types

​Pydantic model

​TypedDict

​Dataclass

​Enum and Literal

​Union and Optional

​Typed containers

​JSON Schema (string or dict)

Install

Supported `response_format` types

Pydantic model

TypedDict

Dataclass

Enum and Literal

Union and Optional

Typed containers

JSON Schema (string or dict)