Skip to main content

Interface: TurnBuilder

Defined in: internal/turn-builder/TurnBuilder.ts:65

TurnBuilder -- the converter between what is stored and what the model reads

About​

One class knows both shapes: ITurn for the ThreadStore, IMessage for the LLMClient.

A model result becomes typed turns (text, tool calls, tool results, with usage and model id); stored turns become the messages of a request. No other class depends on both formats.

  • Pure transform: no I/O, no tenant, no state.
  • File pointers stay in the turns and never reach a message: the bytes are inlined per call by the ContextAssembler (IContextInput.inlineFiles); the inline bytes of a message never reach a turn.

Created by createGatewayDeps with no deps; sits between the ThreadStore and the LLMClient on every call.

Who needs it​

prepareCall (the user turn), AIGateway.executeAsk, settleRun, settleReview, settleReviewPause (the assistant turns), WorkingMemory (the window as messages, D122).

Usage​

When to use it​

Every conversion between a turn and a message.

When shouldn't use it​

A conversation as plain text for a helper call (the memory, the facts): toTranscript.

Implements​

Methods​

buildAssistantTurns()​

buildAssistantTurns(__namedParameters): ITurn[]

Defined in: internal/turn-builder/TurnBuilder.ts:127

buildAssistantTurns -- what the model produced, as the turns to store

About​

One turn per message of the answer, with the model id on the assistant turns and the usage on the last one.

Without runMessages (an ask): one assistant turn with the text and the unexecuted tool calls. With runMessages (a run): one turn per message the run produced, in order; the parts come from the messages, inline file bytes dropped (a turn keeps pointers only), a message left without parts dropped too. result gives the model id of every assistant turn and the usage of the last one.

Who needs it​

AIGateway.executeAsk, settleRun, settleReview (the reviewed answer), settleReviewPause (the tool turns only).

Pitfalls​

The callers decide what to store: a blocked answer passes the messages without the final text (withoutFinalAnswer).

Parameters​

__namedParameters​
result​

IModelResult

runMessages?​

IMessage[]

Messages produced during a run (tool calls and results); omit for complete().

Returns​

ITurn[]

Implementation of​

ITurnBuilder.buildAssistantTurns

buildUserTurn()​

buildUserTurn(__namedParameters): ITurn

Defined in: internal/turn-builder/TurnBuilder.ts:79

buildUserTurn -- the user's question as a turn

About​

One text part for the prompt, one file part per uploaded pointer.

An empty prompt gives no text part: a question can be files alone. The turn gets a new id and createdAt now.

Who needs it​

prepareCall, step 3, with the prompt as the input check returned it.

Parameters​

__namedParameters​
files​

IFileRef[]

prompt​

string

Returns​

ITurn

Implementation of​

ITurnBuilder.buildUserTurn

toMessages()​

toMessages(__namedParameters): IMessage[]

Defined in: internal/turn-builder/TurnBuilder.ts:188

toMessages -- stored turns as the messages of a request

About​

The reverse of buildAssistantTurns, minus the files.

File parts are always dropped (pointers, no bytes): the ContextAssembler inlines the current turn's files through IContextInput.inlineFiles. A turn left without parts is dropped too.

Who needs it​

WorkingMemory, for the window of a call under both strategies (D122).

Parameters​

__namedParameters​
turns​

ITurn[]

Returns​

IMessage[]

Implementation of​

ITurnBuilder.toMessages