This structure is used to describe a single message in a
conversation with a language model. Messages are typically assigned a
role using one of the constants, such as LLM_ROLE_USER
for user input, LLM_ROLE_ASSISTANT for a model response,
or LLM_ROLE_SYSTEM for an instruction message that
defines the behavior of the session. In most applications, those
roles are required. Other roles are used for advanced scenarios
such as tool integration or legacy compatibility.
The LLM_MESSAGE structure is used for both input and output
operations. When passed to functions such as LlmSendMessageEx, it
defines a message that will be submitted to the language model. In this
case, the application typically initializes only the required members,
such as dwSize, dwRoleId, and the content or media fields.
When used with functions such as LlmGetFirstMessage and
LlmGetNextMessage, this structure is populated by the library to
return messages from the current session history. In this case,
additional members such as the message identifier, timestamp, and token
counts may contain values assigned by the library. Applications should
treat values returned by the library as read-only unless otherwise
documented.
The lpszContent member specifies the text associated
with the message. For the ANSI version of this structure, this string
must be UTF-8 encoded. In the Unicode version, the string is specified
as UTF-16 using a wide character pointer.
The nContentLength member specifies the content
length in characters rather than bytes. If this value is zero, the
library may determine the length from the null-terminated string.
Applications should not assume that token counts are identical to
character counts. The nInputTokens member, when available,
reflects the tokenized size of the message content as determined by the
model or provider.
The dwReasoningLevel member controls the reasoning effort
requested for the message. Higher reasoning levels may improve the quality,
accuracy, or depth of responses, particularly when using reasoning-capable
models, but they can also increase response time and token usage costs.
Lower reasoning levels generally favor faster responses and reduced usage
costs. Not all providers or models support configurable reasoning levels,
and unsupported values may be ignored by the provider. If this member is
set to LLM_REASONING_DEFAULT, the library will use the default
reasoning behavior for the current provider or model.
The tTimestamp member is a standard 64-bit Unix time
value and can be used interchangeably with functions in the C standard
library such as gmtime or localtime. Because
it is a 64-bit integer, it is not impacted by the Year 2038 problem.
Timestamps can be converted into a local date and time using the
LlmConvertTimestamp function.
Unless otherwise noted, any reserved members should be set
to zero before calling a function which accepts this structure.
Applications should also avoid modifying structure members that are
returned by the library unless the documentation for a specific function
indicates that doing so is supported.
The lpszContent member of this structure is managed by the
library. Applications should treat this value as read-only and
must not attempt to modify the contents of the string. If the application
needs to retain or modify this data, it should create its own copy.