nimgent/conversation

This page is generated from the module’s exported API and ## documentation comments.

Event-backed conversation state for reusable agents.

A Conversation owns the transcript and usage for one interaction. Agent remains immutable configuration; a conversation can be used for independent runs and is not safe for concurrent mutation from multiple callers.

Constants

conversationSchemaVersion

Current serialized conversation format version.

conversationSchemaVersion = 1

View source

Types

ConversationEventKind

Kind of event stored in a conversation transcript.

ConversationEventKind = enum
  cekUser = "user", cekAssistant = "assistant", cekToolResult = "tool_result",
  cekTurnStarted = "turn_started", cekTurnFinished = "turn_finished", cekTurnFailed = "turn_failed" ## Provider-neutral append-only conversation event. Lifecycle events make an
                                                                                                    ## interrupted turn observable without putting incomplete messages into the
                                                                                                    ## model-facing transcript.

View source

ConversationEvent

One durable event in a conversation transcript.

ConversationEvent = object
  turnId*: string
  case kind*: ConversationEventKind
  of cekUser, cekAssistant:
    message*: Message
    model*: string
    requestId*: string
    usage*: Usage
    finishReason*: FinishReason
  of cekToolResult:
    toolResults*: seq[ContentBlock]
  of cekTurnStarted:
    prompt*: string
  of cekTurnFinished:
    response*: ProviderResponse
  of cekTurnFailed:
    error*: string
    aborted*: bool

View source

Conversation

Stable identity passed through to providers that support server sessions.

Conversation = ref object
  id*: string                ## Agent configuration used for each turn.
  agent*: Agent ## Most recent messages sent to the model per turn; 0 sends the whole
                ## transcript. Counted in messages, not turns: a turn with tool calls uses
                ## several. The event log always keeps every turn.
  historyLimit*: int         ## Canonical append-only transcript.
  events*: seq[ConversationEvent]
  turns*: int
  totalUsage*: Usage
  lastResponse*: ProviderResponse ## Highest turn number issued. Kept monotonic so turn ids stay unique when
                                  ## a caller replaces the transcript.

View source

Procedures

messages (overload 1)

Convert completed message events into the provider-neutral request shape. Pass any slice of Conversation.events to read the part a caller wants to summarize, drop, or rewrite.

proc messages(events: openArray[ConversationEvent]): seq[Message] {.raises: [],
    tags: [], forbids: [].}

Returns: seq[Message].

Arguments

Name	Type	Default
events	openArray[ConversationEvent]

View source

newConversation

Create an empty conversation, or continue from an existing transcript.

proc newConversation(agent: Agent; messages: seq[Message] = @[]; id = "";
                     historyLimit = 0): Conversation {.raises: [ProviderError],
    tags: [TimeEffect], forbids: [].}

Returns: Conversation.

Arguments

Name	Type	Default
agent	Agent
messages	seq[Message]	@[]
id	inferred	""
historyLimit	inferred	0

View source

messages (overload 2)

Model-facing view of the transcript currently in the conversation.

proc messages(conversation: Conversation): seq[Message] {.raises: [], tags: [],
    forbids: [].}

Returns: seq[Message].

Arguments

Name	Type	Default
conversation	Conversation

View source

replaceEvents

Replace the transcript, for example after compacting older turns, and rebuild turns, totalUsage, and lastResponse from it.

The caller owns the new transcript: keep it provider-valid by starting at a user turn and keeping each tool call with its results. Use userEventIndices to find safe cut points.

proc replaceEvents(conversation: Conversation;
                   events: openArray[ConversationEvent]) {.
    raises: [ProviderError], tags: [], forbids: [].}

Arguments

Name	Type	Default
conversation	Conversation
events	openArray[ConversationEvent]

View source

userEventIndices

Indices of user events, the boundaries a caller can safely cut at when compacting a transcript.

proc userEventIndices(conversation: Conversation): seq[int] {.
    raises: [ProviderError], tags: [], forbids: [].}

Returns: seq[int].

Arguments

Name	Type	Default
conversation	Conversation

View source

runAsync

Run one user turn and append its complete model/tool transcript.

proc runAsync(conversation: Conversation; prompt: string;
              abort: AbortCheck = nil; callbacks = RunCallbacks()): Future[
    ProviderResponse] {.stackTrace: false, raises: [Exception, ValueError,
    ProviderError, CatchableError], tags: [RootEffect, TimeEffect], forbids: [].}

Returns: Future[ProviderResponse].

Arguments

Name	Type	Default
conversation	Conversation
prompt	string
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()

View source

run

Blocking convenience wrapper around runAsync.

proc run(conversation: Conversation; prompt: string; abort: AbortCheck = nil;
         callbacks = RunCallbacks()): ProviderResponse {.
    raises: [ValueError, Exception, OSError, ProviderError, CatchableError],
    tags: [TimeEffect, RootEffect], forbids: [].}

Returns: ProviderResponse.

Arguments

Name	Type	Default
conversation	Conversation
prompt	string
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()

View source

streamAsync (overload 1)

Stream one user turn and append its transcript after successful completion.

proc streamAsync(conversation: Conversation; prompt: string;
                 onEvent: StreamCallback; abort: AbortCheck = nil;
                 callbacks = RunCallbacks()): Future[ProviderResponse] {.
    stackTrace: false,
    raises: [Exception, ValueError, ProviderError, CatchableError],
    tags: [RootEffect, TimeEffect], forbids: [].}

Returns: Future[ProviderResponse].

Arguments

Name	Type	Default
conversation	Conversation
prompt	string
onEvent	StreamCallback
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()

View source

stream (overload 1)

Blocking convenience wrapper around streamAsync.

proc stream(conversation: Conversation; prompt: string; onEvent: StreamCallback;
            abort: AbortCheck = nil; callbacks = RunCallbacks()): ProviderResponse {.
    raises: [ValueError, Exception, OSError, ProviderError, CatchableError],
    tags: [TimeEffect, RootEffect], forbids: [].}

Returns: ProviderResponse.

Arguments

Name	Type	Default
conversation	Conversation
prompt	string
onEvent	StreamCallback
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()

View source

runEventsAsync

Run one conversation turn while receiving lifecycle events.

proc runEventsAsync(conversation: Conversation; prompt: string;
                    abort: AbortCheck = nil; callbacks = RunCallbacks();
                    onEvent: AgentEventCallback = nil): Future[ProviderResponse] {.
    stackTrace: false,
    raises: [Exception, ValueError, ProviderError, CatchableError],
    tags: [RootEffect, TimeEffect], forbids: [].}

Returns: Future[ProviderResponse].

Arguments

Name	Type	Default
conversation	Conversation
prompt	string
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()
onEvent	AgentEventCallback	nil

View source

streamAsync (overload 2)

Stream one conversation turn while receiving lifecycle events.

proc streamAsync(conversation: Conversation; prompt: string;
                 onEvent: AgentEventCallback; abort: AbortCheck = nil;
                 callbacks = RunCallbacks()): Future[ProviderResponse] {.
    stackTrace: false,
    raises: [Exception, ValueError, ProviderError, CatchableError],
    tags: [RootEffect, TimeEffect], forbids: [].}

Returns: Future[ProviderResponse].

Arguments

Name	Type	Default
conversation	Conversation
prompt	string
onEvent	AgentEventCallback
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()

View source

stream (overload 2)

Synchronously stream one conversation turn with lifecycle events.

proc stream(conversation: Conversation; prompt: string;
            onEvent: AgentEventCallback; abort: AbortCheck = nil;
            callbacks = RunCallbacks()): ProviderResponse {.
    raises: [ValueError, Exception, OSError, ProviderError, CatchableError],
    tags: [TimeEffect, RootEffect], forbids: [].}

Returns: ProviderResponse.

Arguments

Name	Type	Default
conversation	Conversation
prompt	string
onEvent	AgentEventCallback
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()

View source

events

Persist the transcript independently of the consumer’s event-draining loop, while keeping the stream’s result Future authoritative.

proc events(conversation: Conversation; prompt: string; abort: AbortCheck = nil;
            callbacks = RunCallbacks()): AgentEventStream {.
    raises: [ProviderError, Exception, ValueError], tags: [RootEffect],
    forbids: [].}

Returns: AgentEventStream.

Arguments

Name	Type	Default
conversation	Conversation
prompt	string
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()

View source

conversationJson

Serialize the event log. Agent configuration is intentionally excluded.

proc conversationJson(conversation: Conversation): JsonNode {.
    raises: [ProviderError, KeyError], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
conversation	Conversation

View source

conversationJsonString

Serialize a conversation transcript as a JSON string.

proc conversationJsonString(conversation: Conversation): string {.
    raises: [ProviderError, KeyError], tags: [], forbids: [].}

Returns: string.

Arguments

Name	Type	Default
conversation	Conversation

View source

conversationFromJson (overload 1)

Rehydrate a conversation with a caller-supplied Agent configuration.

proc conversationFromJson(agent: Agent; node: JsonNode): Conversation {.
    raises: [ProviderError, ValueError, KeyError], tags: [TimeEffect],
    forbids: [].}

Returns: Conversation.

Arguments

Name	Type	Default
agent	Agent
node	JsonNode

View source

conversationFromJson (overload 2)

Rehydrate a conversation from a JSON string and agent configuration.

proc conversationFromJson(agent: Agent; raw: string): Conversation {.raises: [
    ProviderError, ValueError, KeyError, IOError, OSError, JsonParsingError],
    tags: [TimeEffect, ReadIOEffect, WriteIOEffect], forbids: [].}

Returns: Conversation.

Arguments

Name	Type	Default
agent	Agent
raw	string

View source

reset

Clear the transcript, counters, and last response while retaining the agent configuration and history window.

proc reset(conversation: Conversation) {.raises: [ProviderError], tags: [],
    forbids: [].}

Arguments

Name	Type	Default
conversation	Conversation

View source