Skip to content

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++20 or -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):

yaml
gen:
  cpp:
    file: include/gen/prompts.h

Generate the C++ code:

bash
npx @typeprompt/cli gen

Quick start ​

Include the generated header and call Render<Template> with designated initializers for typed input:

cpp
#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:

FieldTypeDescription
prompt.system_messagestd::stringResolved system prompt text.
prompt.user_messagestd::stringResolved user prompt text.
prompt.metaschema::meta::MetaTyped metadata defined in the template (e.g., model, temperature).
prompt.examplesstd::vector<FewShotExample>List of few-shot examples (FewShotExample), if defined.
prompt.toolsstd::map<std::string, Tool>Available tool definitions and their input JSON schemas.
prompt.output_formatOutputFormatFormat descriptor (OutputFormat::kJson or OutputFormat::kText).
prompt.output_json_schemastd::optional<JsonNode>JSON Schema for structured output validation when format is JSON.
prompt.template_idstd::stringTemplate 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>:

cpp
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:

cpp
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:

cpp
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::string directly.

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:

cpp
#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>():

cpp
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:

cpp
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:

cpp
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: An std::optional<std::string> containing the plain error message if a tool execution failed, or std::nullopt on success (useful for Anthropic's is_error flag).

Integration guidelines:

  • OpenAI / Gemini APIs: Send response.stringified_output directly as the tool message content.
  • Anthropic API: Check if response.error.has_value(). If present, set is_error: true and pass *response.error as content; otherwise pass response.stringified_output.

Type definitions and schema ​

All types declared in your TypePrompt schemas are generated in the schema namespace:

cpp
// 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:

cpp
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 ::whole forces you to set all the fields (including optional fields like std::optional<T>, e.g. .optional_field = std::nullopt or .optional_field = value). Omitting any field in ::whole results in a compile-time error.
  • Nested initializer lists: Because fields inside ::whole are wrapped in must_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>({ ... }) accepts Template::input_type::whole by default, so passing a designated initializer directly to Render automatically 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:

cpp
// 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:

cpp
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>:

cpp
// 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:

cpp
// 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:

cpp
#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;
}

Made with 🩷 in New York and outer space