Documentation
¶
Overview ¶
Package convo is a conversation's record: an append-only file of one JSON entry a line, and the messages a model request is built from, which are a pure function of that file.
Nothing is ever rewritten. A tool call is recorded before it runs and its result after, so a process that died in between leaves a call with no result; such a call is shown to the model as failed and is never run again.
What the model is sent can still change: a cut-off reply gives way to a stub, old tool results to placeholders, and the whole conversation to a summary of it. Each such change is an entry of its own, an edit, that says what the messages show from then on. The entries it covers stay in the file, and the same file always gives the same messages.
A model's reasoning is sent back only while the conversation before it is the one it was written in: a server may bind a reasoning block to what came before it, the system prompt and the tools included, and refuse the block once that has changed. So the replies recorded before a clear, a compaction or a change of frame go back without their reasoning.
Index ¶
Constants ¶
const ( // KindHeader opens the file. KindHeader = "header" // KindUser is a message from the runner: a prompt. KindUser = "user" // KindAssistant is a whole reply of the model. KindAssistant = "assistant" // KindCall says a call is about to run. KindCall = "call" // KindResult is a call's result. KindResult = "result" // KindUsage is a model request's token count. KindUsage = "usage" // KindStub replaces the assistant message before it with its text: a // reply the output limit cut off, taken out of what the model is sent. KindStub = "stub" // KindClear replaces the results of the calls it lists with short // placeholders. KindClear = "clear" // KindCompaction replaces everything before it with its text, a summary // of the conversation, but for the entries from KeepFrom on. KindCompaction = "compaction" // KindFrame says what the conversation is sent with from here on: Frame // is a digest of the model, the system prompt and the tools. A process // that opens the conversation with another writes a new one. KindFrame = "frame" )
Kinds of entry.
const ( // NoteNudge is the runtime's message after a repeated call. NoteNudge = "nudge" // NoteCut is the runtime's message after a cut-off reply. NoteCut = "cut" // NoteContinue is the runner's answer to a turn that was about to end. NoteContinue = "continue" // NoteSteer is a message the runner sent while a turn was under way. NoteSteer = "steer" // NoteStopped is the runtime's message after a turn the runner stopped. NoteStopped = "stopped" )
Who wrote a user entry that is not the runner's prompt.
const ( // Interrupted is the result of a call that was started and whose // result was never recorded. Interrupted = "This call was interrupted before its result was recorded. It may have run in part. It was not run again." // NotRun is the result of a call that was never started. NotRun = "This call was not run." )
Texts the model is shown for a call that has no recorded result.
const Version = 1
Version is the format of the file, written in its first entry.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Cleared ¶
Cleared is one result a clear entry replaces: the call, and the text the model is sent in the result's place.
type Entry ¶
type Entry struct {
Kind string `json:"kind"`
// At is when the entry was written.
At string `json:"at,omitempty"`
// Version and Conversation are set on the header.
Version int `json:"version,omitempty"`
Conversation string `json:"conversation,omitempty"`
// Text is a user message's text, a stub's, or a compaction's summary as
// the model is sent it.
Text string `json:"text,omitempty"`
// Note says a user entry is not the runner's prompt and who wrote it,
// one of the Note constants. A prompt has none.
Note string `json:"note,omitempty"`
// Parts is an assistant message.
Parts []llm.Part `json:"parts,omitempty"`
// Finish is why the assistant's reply ended.
Finish string `json:"finish,omitempty"`
// CallID names the call of a call or result entry, and Result is the
// result of a result entry.
CallID string `json:"callId,omitempty"`
Result *llm.Part `json:"result,omitempty"`
// Usage is set on a usage entry.
Usage *llm.Usage `json:"usage,omitempty"`
// Cleared is set on a clear entry: each result it replaces.
Cleared []Cleared `json:"cleared,omitempty"`
// KeepFrom, on a compaction entry, is the index in the file of the first
// entry the summary does not replace. Zero keeps none.
KeepFrom int `json:"keepFrom,omitempty"`
// Reason says why a compaction or a clear was made, what a stub stands
// for, and, on a usage entry, what a request was that was not one of
// the conversation's own.
Reason string `json:"reason,omitempty"`
// Window, on a compaction entry, is the model's window in tokens as the
// harness had learned it from the server by then, zero when it had not.
Window int `json:"window,omitempty"`
// Frame is set on a frame entry.
Frame string `json:"frame,omitempty"`
}
Entry is one line of the file. Kind says which fields are set.
type Log ¶
type Log struct {
// contains filtered or unexported fields
}
Log is an open conversation.
func Open ¶
Open opens the conversation id in dir, creating it when there is none. It reports whether the conversation already held a message.