AiChat.h header

#include <ew/app/AiChat.h>

Namespace ew::app

AiMessage struct

struct ew::app::AiMessage

One message in a chat conversation with a language model. role is "system", "user", "assistant", or "tool" (the OpenAI-compatible convention). This is provider-agnostic: any endpoint speaking the OpenAI chat-completions shape – hosted (Anthropic/OpenAI/Azure/OpenRouter) or a local server (llama.cpp/Ollama) – consumes it.

Members

QString ew::app::AiMessage::role

"system", "user", "assistant", or "tool".

QString ew::app::AiMessage::content

The message text.

QString ew::app::AiMessage::toolCallId {}

For a role "tool" message: the id of the tool call this answers (empty otherwise).

std::vector<AiToolCall> ew::app::AiMessage::toolCalls {}

For a role "assistant" message: the tool calls it requested (empty otherwise). Carried so the assistant turn can be replayed in the history before its tool results.

bool operator==(const AiMessage &, const AiMessage &)=default

Messages compare equal when every field matches.

AiRequest struct

struct ew::app::AiRequest

A request to a chat model: the conversation, the model name, and sampling controls. The model name is supplied from settings, never hard-coded.

Members

std::vector<AiMessage> ew::app::AiRequest::messages

The conversation so far, oldest first (typically a system prompt then user/assistant turns).

QString ew::app::AiRequest::model

The model name to request (e.g. "gpt-4o-mini", "claude-3-5-sonnet", a local model id).

double ew::app::AiRequest::temperature = 0.7

Sampling temperature (0 = deterministic, higher = more varied).

int ew::app::AiRequest::maxTokens = 0

The maximum number of tokens to generate; 0 leaves it to the provider's default.

std::vector<AiToolSpec> ew::app::AiRequest::tools

Tools the model may call (empty for a plain chat request). When set, the model may reply with tool calls instead of, or before, a final answer.

AiResponse struct

struct ew::app::AiResponse

A model's reply, or an error. Exactly one of text (on success) or error (on failure) is meaningful; ok distinguishes them. On a successful reply the model may instead request tool calls (see toolCalls) rather than answering directly.

Members

bool ew::app::AiResponse::ok = false

True when the model returned a completion; false when the request errored.

QString ew::app::AiResponse::text

The assistant's reply text (when ok; empty when it only requested tool calls).

QString ew::app::AiResponse::error

A human-readable error message (when not ok).

std::vector<AiToolCall> ew::app::AiResponse::toolCalls {}

Tool calls the model requested (when ok and it chose to use tools). The host executes them and appends the results (see buildToolResultMessage) before the next request.

TokenUsage ew::app::AiResponse::usage {}

The token usage the provider reported for this call (all zero when none was reported).

AiToolCall struct

struct ew::app::AiToolCall

A tool call the model requested: the provider's call id, the function name, and its arguments as a JSON string for the host to parse and execute.

Members

QString ew::app::AiToolCall::id

The provider-assigned id, echoed back with the tool result.

QString ew::app::AiToolCall::name

The function to call.

QString ew::app::AiToolCall::argumentsJson

The call arguments as a JSON string.

bool operator==(const AiToolCall &, const AiToolCall &)=default

Calls compare equal when every field matches.

AiToolSpec struct

struct ew::app::AiToolSpec

A tool (function) the model may call: its name, a description the model uses to decide when to call it, and a JSON-schema object (as a string) describing its parameters. Provider-agnostic – the OpenAI function-calling shape. Backs agentic tool use.

Members

QString ew::app::AiToolSpec::name

The function name the model calls.

QString ew::app::AiToolSpec::description

What the tool does, so the model knows when to use it.

QString ew::app::AiToolSpec::parametersJson

A JSON object (schema) describing the tool's parameters; empty for a no-argument tool.

bool operator==(const AiToolSpec &, const AiToolSpec &)=default

Specs compare equal when every field matches.

TokenUsage struct

struct ew::app::TokenUsage

The token counts an OpenAI-compatible endpoint reports for a request in its "usage" object. Used to track spend against a budget (see AiUsage). All zero when the provider reports no usage.

Members

int ew::app::TokenUsage::promptTokens = 0

Tokens in the prompt/input.

int ew::app::TokenUsage::completionTokens = 0

Tokens the model generated (0 for an embeddings response, which has no completion).

int ew::app::TokenUsage::totalTokens = 0

Total tokens billed (prompt + completion).

bool operator==(const TokenUsage &, const TokenUsage &)=default

Usages compare equal when every field matches.

TokenUsage & ew::app::TokenUsage::operator+=(const TokenUsage &other)

Accumulates other into this usage, saturating each field at INT_MAX. Token counts are non-negative, so a long agent loop (summing several calls) or a provider reporting an absurd count can never overflow to a negative total that would silently defeat a session budget.

Functions

QString ew::app::buildChatCompletionRequestJson(const AiRequest &request)

Serializes request to an OpenAI-compatible chat-completions request body (JSON). This is a pure transformation, so it is unit-testable without any network or key.

AiMessage ew::app::buildToolResultMessage(const QString &toolCallId, const QString &content)

Builds a role "tool" message carrying content as the result of the tool call toolCallId, to append to the conversation before the next request (the OpenAI tool-result convention).

AiResponse ew::app::parseChatCompletionResponseJson(const QString &json)

Parses an OpenAI-compatible chat-completions response body json into an AiResponse: on success the first choice's message content and any tool calls it requested; on an API error the error message; and a clear error when the body is malformed or empty. Pure and unit-testable.

TokenUsage ew::app::parseTokenUsageJson(const QString &json)

Extracts the token counts from the top-level "usage" object of any OpenAI-compatible response body json (chat or embeddings), returning all-zero when the body is malformed or reports none. Pure and unit-testable.