ClientSessionFacet

A Session facet over the Completion facet of an LLMClient: one completion per turn, with the history (trove-parts §TPN-9b).

Declared in src/libs/libllm/llm/ClientSessionFacet.hpp.

Detailed description

The OPAL chat runs its turns on a Session facet (§TPN-9). Most clients have only a Completion facet: they answer one request and keep nothing. This class gives such a client the Session facet, so the chat has one code path for every provider (LLMClient::createSession()). Claude Code does not use this class: the chat runs it on the stream transport of libllmsession, one live process per session (§TPN-4).

Each turn is one completion. Its request is the system prompt, an acknowledgement of it, the history and the prompt of the turn. The system prompt has the role user, because a role travels into the JSON of the provider. The reply goes into the history. A failed or interrupted turn leaves no trace in the history, so a caller can send the same prompt again.

A client that is shared between conversations

LLMManager caches one client per model, and gives the same client to each conversation of that model. A completion is stateless: the client keeps no conversation, and the request of each turn carries all of it. So the history of a conversation is in its session, one session per conversation, and the client serves them all. The session has no provider session: providerSession() is empty, and adoptSession() takes the history only.

What the turn carries

The images of the prompt go in the Message of the turn, with their path, size and label. The client carries them, or fails the turn with a reason (LLMClient::refuseImagesIfPresent()). The PromptResult carries the tokens and the transport figures of the Response. The activity of the provider becomes activityObserved().

The other facets of a client are ClientCompletionFacet and OnlineSessionFacet.

See also LLMClient.