C++ integration guide
This guide explains how to use TypePrompt-generated C++ code in your application.
Installation & setup
TypePrompt generates a clean, standalone, header-only C++ library that relies exclusively on the standard library with zero third-party dependencies.
- Standard: C++20 or later (
-std=c++20or-std=c++23) - Dependencies: None (Standard Library only)
In your typeprompt.yaml configuration file, specify your C++ output file path and optional root namespace (defaults to typeprompt):
gen:
cpp:
file: include/gen/prompts.hGenerate the C++ code:
npx @typeprompt/cli genQuick start
Include the generated header and call Render<Template> with designated initializers for typed input:
#include "gen/prompts.h"
#include <iostream>
using namespace typeprompt;
int main() {
auto prompt = Render<templates::Translate>({
.target_language = "French",
.text = "Hello world",
});
std::cout << "System prompt:\n" << prompt.system_message << "\n\n";
std::cout << "User prompt:\n" << prompt.user_message << "\n";
return 0;
}The Prompt object
Calling Render<Template>() returns a Prompt struct containing everything needed to execute the LLM request:
| Field | Type | Description |
|---|---|---|
prompt.system_message | std::string | Resolved system prompt text. |
prompt.user_message | std::string | Resolved user prompt text. |
prompt.meta | schema::meta::Meta | Typed metadata defined in the template (e.g., model, temperature). |
prompt.examples | std::vector<FewShotExample> | List of few-shot examples (FewShotExample), if defined. |
prompt.tools | std::map<std::string, Tool> | Available tool definitions and their input JSON schemas. |
prompt.output_format | OutputFormat | Format descriptor (OutputFormat::kJson or OutputFormat::kText). |
prompt.output_json_schema | std::optional<JsonNode> | JSON Schema for structured output validation when format is JSON. |
prompt.template_id | std::string | Template identifier string (e.g. "Main:Translate"). |
Error handling with Result<T>
Code generated by TypePrompt does not throw exceptions. Fallible operations return a value-based Result<T>:
template <typename T>
class Result {
public:
bool ok() const; // true if operation succeeded
const T& operator*() const&; // access value (precondition: ok() == true)
const T* operator->() const; // member access (precondition: ok() == true)
const Error& error() const&; // access error (precondition: ok() == false)
};An Error provides a human-readable diagnostic message:
struct Error {
std::string message;
};Parsing LLM responses
Pass the LLM's response string to ParseResponse<Template>() to validate and parse it into your strongly-typed output:
using Template = templates::TriageTicket;
std::string_view raw_model_output = /* response from LLM */;
Result<typename Template::output_type> result =
ParseResponse<Template>(raw_model_output);
if (result.ok()) {
std::cout << "Category: " << result->summary << "\n";
if (result->suggested_reply.has_value()) {
std::cout << "Reply: " << *result->suggested_reply << "\n";
}
} else {
std::cerr << "Validation failed: " << result.error().message << "\n";
}- JSON Outputs: Automatically strips markdown code fences (
```json ... ```or``` ... ```) and parses the JSON into strongly-typed C++ structs, enums, variants, and vectors. - Text Outputs: Returns
std::stringdirectly.
Executing tools
When a template registers <tools>, implement a typed tool executor and construct a ToolExecutor using MakeToolExecutor<Template>().
1. Implement the typed tool executor
Define a functor struct with an overloaded operator() for each tool registered in the template:
#include "gen/prompts.h"
using namespace typeprompt;
struct ResearchExecutor {
// Define an operator() overload for each tool declared in the template:
Result<schema::web_search::Output> operator()(
tools::WebSearch,
const schema::web_search::Input& input) {
const std::string& query = input.query;
// Call your search service
auto search_results = RunWebSearch(query);
schema::web_search::Output output;
for (const auto& item : search_results) {
output.results.push_back({
.snippet = item.snippet,
.title = item.title,
.url = item.url,
});
}
return output;
}
};2. Dispatch tool calls
Bind your executor to the template with MakeToolExecutor<Template>():
using Template = templates::ResearchQuestion;
ResearchExecutor typed_executor;
std::unique_ptr<ToolExecutor> tool_executor =
MakeToolExecutor<Template>(&typed_executor);
// Incoming tool call from LLM response:
ToolCall call{
.call_id = "call_123",
.tool_name = "webSearch",
.stringified_input = R"({"query": "TypePrompt C++"})",
};
ToolCallResponse response = tool_executor->Execute(call);
std::cout << "Call ID: " << response.call_id << "\n";
std::cout << "Output: " << response.stringified_output << "\n";Smart pointer & lifetime support
MakeToolExecutor<Template>() accepts raw pointers (&executor), std::shared_ptr, and std::unique_ptr:
auto executor = MakeToolExecutor<Template>(std::make_unique<ResearchExecutor>());Templates without tools
For templates with no tools, you can call MakeToolExecutor<Template>() with no argument. The tool executor will reject all tool calls with a "Tool not found" error:
auto no_tools_executor = MakeToolExecutor<templates::Translate>();3. ToolCallResponse format & provider integration
The ToolCallResponse contains:
call_id: The matching call ID.stringified_output: Serialized JSON output on success, or{"error": "<message>"}on failure (ready to forward directly to OpenAI / Gemini).error: Anstd::optional<std::string>containing the plain error message if a tool execution failed, orstd::nullopton success (useful for Anthropic'sis_errorflag).
Integration guidelines:
- OpenAI / Gemini APIs: Send
response.stringified_outputdirectly as the tool message content. - Anthropic API: Check if
response.error.has_value(). If present, setis_error: trueand pass*response.erroras content; otherwise passresponse.stringified_output.
Type definitions and schema
All types declared in your TypePrompt schemas are generated in the schema namespace:
// Template inputs & outputs
using TriageInput = schema::triage_ticket::Input;
using TriageOutput = schema::triage_ticket::Output;
using TicketCategory = schema::triage_ticket::TicketCategory;
// Tool inputs & outputs
using SearchInput = schema::web_search::Input;
using SearchOutput = schema::web_search::Output;
// Metadata type
using Meta = schema::meta::Meta;Constructing structs & ::whole
TypePrompt generates an inner struct whole builder for every interface struct. Using ::whole forces you to set all the fields of the struct at construction:
using TriageInput = schema::triage_ticket::Input;
// 1. To construct a value (via implicit conversion):
TriageInput input = TriageInput::whole{
.body = "Crashes on startup",
.customer_tier = schema::triage_ticket::Input_CustomerTier::kPro,
.recent_tickets = {{}}, // Nested initializer list
.subject = "Bug report",
};
// 2. Or with 'auto' (via operator*):
auto input = *TriageInput::whole{
.body = "Crashes on startup",
.customer_tier = schema::triage_ticket::Input_CustomerTier::kPro,
.recent_tickets = {{}},
.subject = "Bug report",
};Rules & behavior
- Alphabetical order: When using designated initializer syntax in C++20, fields must always be specified in alphabetical order (the declaration order in TypePrompt-generated structs).
- All fields required: Using
::wholeforces you to set all the fields (including optional fields likestd::optional<T>, e.g..optional_field = std::nulloptor.optional_field = value). Omitting any field in::wholeresults in a compile-time error. - Nested initializer lists: Because fields inside
::wholeare wrapped inmust_init<T>, initializing a container or struct via initializer list syntax requires double braces (e.g.for an empty vector, or). - Direct initialization in
Render:Render<Template>({ ... })acceptsTemplate::input_type::wholeby default, so passing a designated initializer directly toRenderautomatically enforces that all template input fields are initialized in alphabetical order.
String unions (enums)
String unions generate C++ enum class types along with a to_string_view() helper function:
// Convert enum value directly to std::string_view:
std::string_view model_name = to_string_view(schema::meta::Meta_Model::kGpt4o); // "gpt-4o"Discriminated unions
Discriminated union types generate type-safe wrapper classes with an enum named after the discriminator property (e.g. kind or type), a getter method returning the enum value, and type-safe accessors for each variant:
using PageNode = schema::generate_page_tree::PageNode;
switch (node.kind()) {
case PageNode::kind::kSection: {
const auto& section = node.as_kind_section();
std::cout << "Section title: " << section.title.value_or("(none)") << "\n";
break;
}
case PageNode::kind::kHeading: {
const auto& heading = node.as_kind_heading();
std::cout << "Heading: " << heading.text << "\n";
break;
}
}JSON serialization & deserialization
While Render and ParseResponse handle JSON conversion automatically during prompt execution, you can also serialize or deserialize generated types directly (e.g. for logging, caching, or disk storage) using ToJson and ParseJson<T>:
// Serialize any generated struct, enum, union, or container to a JSON string:
std::string json = ToJson(my_value);
// Deserialize and validate a JSON string into a Result<T>:
Result<schema::triage_ticket::Output> output = ParseJson<schema::triage_ticket::Output>(json);
if (output.ok()) {
// Use *output
}Multi-namespace projects
When your project defines <namespace> blocks other than Main, templates and schemas are partitioned by namespace:
// Render templates from specific namespaces:
auto fin_prompt = Render<templates::Finance::SummarizeTransaction>({
.amount = {
.currency = schema::Finance::shared::Currency::kUsd,
.value = 150.0,
},
.category = schema::Finance::summarize_transaction::Input_Category::kExpense,
.date = "2026-08-01",
.description = "Cloud server bill",
});
auto legal_prompt = Render<templates::Legal::DraftNda>({
.disclosing_party = {
.jurisdiction = "CA",
.name = "Acme Corp",
.role = ...,
},
.duration_years = 3,
.purpose_of_disclosure = "M&A evaluation",
.receiving_party = {
.jurisdiction = "DE",
.name = "Beta LLC",
.role = ... ,
},
});End-to-end OpenAI example
Here is a complete, production-ready example defining a generic ExecutePrompt function integrating TypePrompt with the openai-cpp SDK and nlohmann::json:
#include "gen/prompts.h"
#include <openai/openai.hpp>
#include <iostream>
#include <string>
#include <vector>
using namespace typeprompt;
using json = nlohmann::json;
/**
* Generic helper to execute any TypePrompt prompt with OpenAI.
*/
template <typename Template>
Result<typename Template::output_type> ExecutePrompt(
openai::OpenAI& client,
const Prompt& prompt,
ToolExecutor& tool_executor) {
// 1. Prepare tools for OpenAI from prompt.tools
json tools = json::array();
for (const auto& [name, tool] : prompt.tools) {
tools.push_back({
{"type", "function"},
{"function", {
{"name", tool.name},
{"description", tool.description},
{"parameters", json::parse(tool.input_json_schema.ToJson())},
}},
});
}
// 2. Format initial message history
json messages = json::array();
messages.push_back({{"role", "system"}, {"content", prompt.system_message}});
for (const auto& example : prompt.examples) {
messages.push_back({{"role", "user"}, {"content", example.user_message}});
messages.push_back({{"role", "assistant"}, {"content", example.response}});
}
messages.push_back({{"role", "user"}, {"content", prompt.user_message}});
// 3. Conversation & tool execution loop
while (true) {
json request = {
{"model", to_string_view(prompt.meta.model)},
{"messages", messages},
};
if (prompt.meta.temperature.has_value()) {
request["temperature"] = *prompt.meta.temperature;
}
if (!tools.empty()) {
request["tools"] = tools;
}
if (prompt.output_json_schema.has_value()) {
request["response_format"] = {
{"type", "json_schema"},
{"json_schema", {
{"name", "output"},
{"strict", true},
{"schema", json::parse(prompt.output_json_schema->ToJson())},
}},
};
}
json response;
try {
response = client.chat.create(request);
} catch (const std::exception& ex) {
return Error(std::format("OpenAI API call failed: {}", ex.what()));
}
const auto& choice = response["choices"][0];
const auto& message = choice["message"];
messages.push_back(message);
// If the model requested tool calls, execute them with tool_executor
if (message.contains("tool_calls") && !message["tool_calls"].empty()) {
for (const auto& raw_call : message["tool_calls"]) {
ToolCall call{
.call_id = raw_call["id"].get<std::string>(),
.stringified_input = raw_call["function"]["arguments"].get<std::string>(),
.tool_name = raw_call["function"]["name"].get<std::string>(),
};
ToolCallResponse tool_resp = tool_executor.Execute(call);
messages.push_back({
{"role", "tool"},
{"content", tool_resp.stringified_output},
{"tool_call_id", tool_resp.call_id},
});
}
continue; // Send tool responses back to the LLM
}
// Final text response received: parse and validate into typed output
std::string content = message.value("content", "");
return ParseResponse<Template>(content);
}
}
// 2. Concrete application usage
int main() {
using Template = templates::ResearchQuestion;
// Initialize OpenAI client
openai::OpenAI client{std::getenv("OPENAI_API_KEY")};
// 1. Render prompt with strongly-typed input
auto prompt = Render<Template>({
.question = "What is TypePrompt?",
});
// 2. Create tool executor (ResearchExecutor defined in "Executing Tools" above)
ResearchExecutor research_executor;
auto tool_executor = MakeToolExecutor<Template>(&research_executor);
// 3. Execute prompt with OpenAI client
Result<Template::output_type> result =
ExecutePrompt<Template>(client, prompt, *tool_executor);
if (result.ok()) {
std::cout << "Answer: " << result->answer << "\n";
for (const auto& source : result->sources) {
std::cout << "Source: " << source << "\n";
}
} else {
std::cerr << "Error: " << result.error().message << "\n";
return 1;
}
return 0;
}