Turn

Turn(
    role,
    contents,
    *,
    tokens=None,
    finish_reason=None,
    completion=None,
    **kwargs,
)

A user or assistant turn

Every conversation with a chatbot consists of pairs of user and assistant turns, corresponding to an HTTP request and response. These turns are represented by the Turn object, which contains a list of Contents representing the individual messages within the turn. These might be text, images, tool requests (assistant only), or tool responses (user only).

Note that a call to .chat() and related functions may result in multiple user-assistant turn cycles. For example, if you have registered tools, chatlas will automatically handle the tool calling loop, which may result in any number of additional cycles.

Examples

from chatlas import Turn, ChatOpenAI, ChatAnthropic

chat = ChatOpenAI()
str(chat.chat("What is the capital of France?"))
turns = chat.get_turns()
assert len(turns) == 2
assert isinstance(turns[0], Turn)
assert turns[0].role == "user"
assert turns[1].role == "assistant"

# Load context into a new chat instance
chat2 = ChatAnthropic()
chat2.set_turns(turns)
turns2 = chat2.get_turns()
assert turns == turns2

Parameters

Name	Type	Description	Default
role	Literal['user', 'assistant', 'system']	Either “user”, “assistant”, or “system”.	required
contents	str | Sequence[Content | str]	A list of Content objects.	required
tokens	Optional[tuple[int, int, int]]	A numeric vector of length 3 representing the number of input, output, and cached tokens (respectively) used in this turn. Currently only recorded for assistant turns.	None
finish_reason	Optional[str]	A string indicating the reason why the conversation ended. This is only relevant for assistant turns.	None
completion	Optional[CompletionT]	The completion object returned by the provider. This is useful if there’s information returned by the provider that chatlas doesn’t otherwise expose. This is only relevant for assistant turns.	None

Methods

Name	Description
to_inspect_messages	Transform this turn into a list of Inspect AI ChatMessage objects.

to_inspect_messages

Turn.to_inspect_messages(model=None)

Transform this turn into a list of Inspect AI ChatMessage objects.

Most users will not need to call this method directly. See the .export_eval() method on Chat for a higher level interface to exporting chat history for evaluation purposes.