Skip to content

turns

Typed inputs and outcomes for a server turn.

PersistWorkflow dataclass

Save still-open workflow progress without sending a browser event.

Source code in chatkit/turns.py
19
20
21
22
23
24
@dataclass(frozen=True, slots=True)
class PersistWorkflow:
    """Save still-open workflow progress without sending a browser event."""

    item: WorkflowItem
    replace: bool

ClientToolLocalContinuation

Bases: BaseModel

Native model input to replay after a browser tool returns.

Source code in chatkit/turns.py
27
28
29
30
31
class ClientToolLocalContinuation(BaseModel):
    """Native model input to replay after a browser tool returns."""

    type: Literal["local"] = "local"
    items: list[dict[str, JsonValue]]

ClientToolResponsesContinuation

Bases: BaseModel

New function outputs and their predecessor in OpenAI-managed context.

Source code in chatkit/turns.py
34
35
36
37
38
39
class ClientToolResponsesContinuation(BaseModel):
    """New function outputs and their predecessor in OpenAI-managed context."""

    type: Literal["responses"] = "responses"
    response_id: str = Field(min_length=1)
    items: list[dict[str, JsonValue]]

ClientToolInvocation

Bases: BaseModel

Private execution record stored separately from the browser item.

Source code in chatkit/turns.py
48
49
50
51
52
53
54
55
56
57
58
59
60
class ClientToolInvocation(BaseModel):
    """Private execution record stored separately from the browser item."""

    model_config = ConfigDict(frozen=True, extra="forbid")

    item_id: str
    thread_id: str
    turn_id: str
    call_id: str = Field(min_length=1)
    model_continuation: ClientToolModelContinuation | None = Field(
        default=None, repr=False
    )
    continuation_turn_id: str | None = None

ClientToolRequest dataclass

Ask the server to register a browser item and its private invocation.

Source code in chatkit/turns.py
63
64
65
66
67
68
69
70
71
@dataclass(frozen=True, slots=True)
class ClientToolRequest:
    """Ask the server to register a browser item and its private invocation."""

    item: ClientToolCallItem
    call_id: str
    model_continuation: ClientToolModelContinuation | None = field(
        default=None, repr=False
    )

ApprovalRequired dataclass

Private run checkpoint awaiting application review.

Source code in chatkit/turns.py
74
75
76
77
78
@dataclass(frozen=True, slots=True)
class ApprovalRequired:
    """Private run checkpoint awaiting application review."""

    checkpoint: str = field(repr=False)

UserMessageTurn dataclass

A user message saved to a new or existing thread.

Source code in chatkit/turns.py
86
87
88
89
90
@dataclass(frozen=True, slots=True)
class UserMessageTurn:
    """A user message saved to a new or existing thread."""

    message: UserMessageItem

ClientToolTurn dataclass

A continuation after a client tool result was saved.

Source code in chatkit/turns.py
93
94
95
96
97
98
@dataclass(frozen=True, slots=True)
class ClientToolTurn:
    """A continuation after a client tool result was saved."""

    tool_call: ClientToolCallItem
    invocation: ClientToolInvocation

StructuredInputTurn dataclass

A continuation after a structured input was answered or skipped.

Source code in chatkit/turns.py
101
102
103
104
105
@dataclass(frozen=True, slots=True)
class StructuredInputTurn:
    """A continuation after a structured input was answered or skipped."""

    item: StructuredInputItem

RetryTurn dataclass

A retry from an existing user message after removing later items.

Source code in chatkit/turns.py
108
109
110
111
112
@dataclass(frozen=True, slots=True)
class RetryTurn:
    """A retry from an existing user message after removing later items."""

    message: UserMessageItem

Turn dataclass

A durable turn ID, thread snapshot, trigger, and request context.

Persist thread changes with an explicit patch.

Source code in chatkit/turns.py
118
119
120
121
122
123
124
125
126
127
128
@dataclass(frozen=True, slots=True)
class Turn[TContext]:
    """A durable turn ID, thread snapshot, trigger, and request context.

    Persist thread changes with an explicit patch.
    """

    thread: ThreadMetadata
    input: TurnInput
    context: TContext
    id: str

TurnOutcome

Bases: StrEnum

The result of processing a turn on the server.

Source code in chatkit/turns.py
131
132
133
134
135
136
137
138
class TurnOutcome(StrEnum):
    """The result of processing a turn on the server."""

    COMPLETED = "completed"
    WAITING = "waiting"
    CANCELLED = "cancelled"
    FAILED = "failed"
    SUPERSEDED = "superseded"

TurnState

Bases: StrEnum

Durable server milestones for one thread's turn.

Source code in chatkit/turns.py
141
142
143
144
145
146
147
148
149
150
151
class TurnState(StrEnum):
    """Durable server milestones for one thread's turn."""

    ACCEPTED = "accepted"
    RUNNING = "running"
    WAITING = "waiting"
    COMPLETED = "completed"
    CANCELLED = "cancelled"
    FAILED = "failed"
    ABANDONED = "abandoned"
    SUPERSEDED = "superseded"