OpenAI API Integration
Relevant source files
The following files were used as context for generating this wiki page:
The OpenAI API Integration provides a C++ interface for interacting with large language models compatible with the OpenAI API specification. It includes support for standard chat completions, multi-modal inputs (text and images), and Server-Sent Events (SSE) for streaming responses.
The module consists of high-level client wrappers, a comprehensive suite of data structures for request/response serialization, and integration with the HXLibs coroutine-based networking stack. This architecture allows developers to build responsive AI-driven applications using modern C++20 features.
Architecture and Client Implementation
The integration centers on the OpenAiClient template class. This class manages the connection to an OpenAI-compatible backend using a specified HTTP client and proxy configuration.
Client Components
OpenAiClient: The primary interface for API interactions. It handles SSL initialization, request serialization to JSON, and the execution of asynchronous HTTP POST requests.AiConfig: Encapsulates connectivity settings including thebaseUrl,apiKey, and underlying HTTP client options.coroutine::EventLoop: Coordinates the asynchronous execution of networking tasks, ensuring non-blocking operations during API calls.
Sources: include/HXLibs/ai/openai.hpp:135-144, examples/ai/ai.cpp:88-99
Request Flow
The client supports two primary interaction modes: synchronous chat completions and asynchronous streaming.
The diagram shows the asynchronous data flow for streaming chat completions using Server-Sent Events.
Sources: include/HXLibs/ai/openai.hpp:169-195, examples/ai/ai.cpp:109-122
Data Structures
The integration defines several structures to represent the OpenAI Chat API schema. These structures use std::variant and std::optional to handle the flexible nature of the JSON payloads.
Message and Content Models
Messages are represented by the Message struct, which supports standard roles and complex content types for multi-modal support.
| Field | Type | Description |
|---|---|---|
role | std::string | The role of the message author (system, user, assistant, or tool). |
content | MessageContent | Either a raw std::string or a vector of ContentPart (Text or Image). |
name | std::optional<std::string> | An optional name for the participant. |
tool_calls | std::optional<std::vector<ToolCall>> | Generated tool calls (for assistant messages). |
tool_call_id | std::optional<std::string> | ID of the tool call this message responds to. |
Sources: include/HXLibs/ai/openai.hpp:46-73, examples/ai/ai.cpp:13-50
Multi-modal Support
Multi-modal inputs allow sending images alongside text. The ContentPartImage structure supports base64-encoded data or external URLs with a specified detail level (auto, low, high).
Sources: include/HXLibs/ai/openai.hpp:52-60, examples/ai/openai.cpp:25-34
Tool Calling and Function Integration
The API integration supports "Tools," allowing the model to request the execution of specific functions. Tools are defined as JSON schemas within the ChatCompletionRequest.
Tool Definition Schema
Tools consist of a function name, description, and a JSON-encoded string describing the parameters.
struct Tool {
struct Function {
std::string name;
std::string description;
std::string parameters; // json schema
} function;
std::string type = "function";
};
Sources: include/HXLibs/ai/openai.hpp:75-82
Tool Choice
The tool_choice field controls how the model selects tools. It can be set to a fixed string (auto, none) or a specific ToolChoiceFunction object to force the model to use a specific tool.
Sources: include/HXLibs/ai/openai.hpp:84-95
Networking and Coroutine Integration
The module leverages the HXLibs networking layer to provide efficient, non-blocking I/O.
SSE Streaming
The coChat method uses coSseLoop to process Server-Sent Events. It automatically handles the [DONE] signal used by OpenAI to terminate a stream.
Flow of streaming response processing within the client.
Sources: include/HXLibs/ai/openai.hpp:178-195, examples/ai/ai.cpp:115-122
Configuration Options
The client initialization requires an AiConfig struct, which includes specific HttpClientOptions to manage proxies or socket settings.
| Parameter | Description |
|---|---|
baseUrl | The base URL for the API (e.g., https://api.openai.com/v1). |
apiKey | The authentication token used in the Authorization header. |
clineOptions | Network settings such as timeout, proxy type, and SSL configuration. |
Sources: include/HXLibs/ai/openai.hpp:39-44, examples/ai/ai.cpp:83-86
Coding Standards Compliance
Implementation follows the HXLibs C++ style guide, utilizing modern C++20 features:
- CamelCase for file and directory names.
- Header Guards: Use of
#pragma onceas the standard prevention for redefinition. - Namespaces: Logically organized under
HX::ai::openai. - Member Variables: Prefixed with an underscore (e.g.,
_cli,_cfg).
Sources: documents/CodingStandards/CppStyle.md:5-45, include/HXLibs/ai/openai.hpp:1-35
Summary
OpenAI API Integration in HXLibs provides a robust, type-safe C++ framework for accessing AI models. By mapping complex JSON structures to C++ variants and leveraging coroutines for asynchronous SSE streaming, it enables high-performance AI interactions within a modern C++ ecosystem. The inclusion of multi-modal support and tool-calling capabilities ensures compatibility with the latest features of the OpenAI API.