Generation

These C++ examples are real runnable files. Edit the source file first; this page is rebuilt from the checked-in example and its metadata header.

C++ Prompt-Cached Generation

Runs GPT-5.6 structured generation with stable OpenAI prompt-cache affinity.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: beginner
Run: npm run example -- cpp src/examples/cpp/generation/basic_generation.cpp
Source: src/examples/cpp/generation/basic_generation.cpp

C++

#include "axllm/axllm.hpp"
#include <cstdlib>
#include <fstream>
#include <iostream>
#include <sstream>


int main() {
  const char* key = std::getenv("OPENAI_API_KEY");
  if (key == nullptr || std::string(key).empty()) key = std::getenv("OPENAI_APIKEY");
  if (key == nullptr || std::string(key).empty()) {
    std::cerr << "Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.\n";
    return 2;
  }
  const char* model = std::getenv("AX_OPENAI_MODEL");
  axllm::OpenAICompatibleClient client(axllm::object({
      {"api_key", key},
      {"model", model == nullptr || std::string(model).empty() ? "gpt-5.6-luna" : model},
      {"model_config", axllm::object({{"temperature", 0}})},
  }));
  axllm::AxGen program = axllm::ax("question:string -> answer:string");
  axllm::Value output = program.forward(
      client,
      axllm::object({{"question", "In one sentence, explain Ax as a language-agnostic LLM programming library."}}),
      axllm::object({{"promptCacheKey", "ax-openai-example"}, {"contextCache", axllm::object({})}}));
  std::cout << axllm::stringify(output) << "\n";
}

C++ Astra Generation

Runs Astra through the standard generator with automatic Responses routing and prompt caching.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: beginner
Run: npm run example -- cpp src/examples/cpp/generation/astra.cpp
Source: src/examples/cpp/generation/astra.cpp

C++

#include "axllm/axllm.hpp"
#include <cstdlib>
#include <fstream>
#include <iostream>
#include <sstream>


int main() {
  const char* key = std::getenv("OPENAI_API_KEY");
  if (key == nullptr || std::string(key).empty()) key = std::getenv("OPENAI_APIKEY");
  if (key == nullptr || std::string(key).empty()) {
    std::cerr << "Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.\n";
    return 2;
  }
  const char* model = std::getenv("AX_OPENAI_MODEL");
  auto client = axllm::ai("openai", axllm::object({
      {"api_key", key},
      {"model", model == nullptr || std::string(model).empty() ? "gpt-6-astra" : model},
      {"model_config", axllm::object({{"thinkingTokenBudget", "low"}, {"max_tokens", 2048}})},
  }));
  axllm::AxGen program = axllm::ax("question:string -> answer:string");
  axllm::Value output = program.forward(
      *client,
      axllm::object({{"question", "In one sentence, explain Ax as a language-agnostic LLM programming library."}}),
      axllm::object({{"serviceTier", "standard"}, {"promptCacheKey", "ax-openai-example"}, {"contextCache", axllm::object({})}}));
  std::cout << axllm::stringify(output) << "\n";
}

C++ Model Catalog

Lists static models and named OpenAI-compatible profiles with portable thinking levels and service tiers.

Provider: openai-compatible
Env: none
Level: beginner
Run: npm run example -- cpp src/examples/cpp/generation/model_catalog.cpp
Source: src/examples/cpp/generation/model_catalog.cpp

C++

#include "axllm/axllm.hpp"
#include <iostream>
#include <stdexcept>
#include <string>

axllm::Value provider(const axllm::Value& catalog, const std::string& name) {
  for (const auto& entry : axllm::Core::iter(catalog)) {
    if (axllm::display(axllm::Core::get(entry, "name")) == name) return entry;
  }
  throw std::runtime_error("missing provider " + name);
}

int main() {
  const auto catalog = axllm::get_supported_ai_models();
  const auto azure = provider(catalog, "azure-openai");
  const auto openrouter = provider(catalog, "openrouter");
  const auto azure_capabilities = axllm::Core::get(azure, "capabilities");
  const auto openrouter_capabilities = axllm::Core::get(openrouter, "capabilities");

  if (!axllm::equal(axllm::Core::get(azure, "isDynamic"), true)) return 2;
  if (!axllm::Core::iter(axllm::Core::get(azure, "models")).empty()) return 3;
  if (axllm::Core::iter(axllm::Core::get(azure_capabilities, "thinkingLevels")).empty()) return 4;
  if (axllm::Core::iter(axllm::Core::get(openrouter_capabilities, "serviceTiers")).size() != 3) return 5;

  std::cout << axllm::Core::iter(catalog).size()
            << " providers; Azure and OpenRouter named profiles are available\n";
}

Cpp Jev Signature Decisions

Converts Jev probabilities into boolean and class outputs with a provider threshold.

Provider: typesafe
Env: TYPESAFE_APIKEY
Level: beginner
Run: npm run example -- cpp src/examples/cpp/generation/typesafe.cpp
Source: src/examples/cpp/generation/typesafe.cpp

C++

#include "axllm/axllm.hpp"
#include <cstdlib>
#include <iostream>
#include <stdexcept>
using namespace axllm;

static std::string key(const char* name) { const char* value = std::getenv(name); if (!value || !*value) throw std::runtime_error(std::string("Set ") + name); return value; }
int main() {
  auto model = ai("typesafe", object({{"api_key", key("TYPESAFE_APIKEY")}, {"trueThreshold", 0.9}}));
  auto triage = ax("ticket:string -> urgent:boolean(true \"Customers cannot complete a core task\", false \"Routine request\") \"Needs immediate attention?\", team:class \"support, billing, engineering\"");
  auto decision = triage.forward(*model, object({{"ticket", "Checkout is unavailable for all customers after the latest deployment."}}));
  if (!Core::get(decision, "urgent").is_bool()) throw std::runtime_error("Invalid boolean");
  std::cout << stringify(decision) << "\n";
}

C++ Meta Muse Spark

Selects any of Meta’s three protocols through the existing chat API.

Provider: meta
Env: MODEL_API_KEY
Level: beginner
Run: npm run example -- cpp src/examples/cpp/generation/meta_muse.cpp
Source: src/examples/cpp/generation/meta_muse.cpp

C++

#include "axllm/axllm.hpp"
#include <cstdlib>
#include <iostream>

int main() {
  const char* key = std::getenv("MODEL_API_KEY");
  if (key == nullptr || std::string(key).empty()) {
    std::cerr << "Set MODEL_API_KEY to run this example.\n";
    return 2;
  }
  for (const auto* profile : {"meta", "meta-chat", "meta-messages"}) {
    auto client = axllm::ai(profile, axllm::object({{"api_key", key}, {"model", "muse-spark-1.3"}}));
    auto response = client->chat(axllm::parse_json(R"({"chat_prompt":[{"role":"user","content":"Name a solar-powered sailboat."}],"model_config":{"thinking_token_budget":"highest"}})"));
    std::cout << profile << " " << axllm::stringify(response) << "\n";
  }
}

C++ Structured Extraction

Extracts structured fields and labels from support text with OpenAI.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: intermediate
Run: npm run example -- cpp src/examples/cpp/generation/structured_generation.cpp
Source: src/examples/cpp/generation/structured_generation.cpp

C++

#include "axllm/axllm.hpp"
#include <cstdlib>
#include <fstream>
#include <iostream>
#include <sstream>


int main() {
  const char* key = std::getenv("OPENAI_API_KEY");
  if (key == nullptr || std::string(key).empty()) key = std::getenv("OPENAI_APIKEY");
  if (key == nullptr || std::string(key).empty()) {
    std::cerr << "Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.\n";
    return 2;
  }
  const char* model = std::getenv("AX_OPENAI_MODEL");
  axllm::OpenAICompatibleClient client(axllm::object({
      {"api_key", key},
      {"model", model == nullptr || std::string(model).empty() ? "gpt-5.4-mini" : model},
      {"model_config", axllm::object({{"temperature", 0}})},
  }));
  axllm::AxGen program = axllm::ax("ticket:string -> priority:class \"high, normal, low\", summary:string, labels:string[]");
  axllm::Value output = program.forward(client, axllm::object({{"ticket", "Checkout has failed for enterprise customers since 09:00. Support wants a concise summary and tags."}}));
  std::cout << axllm::stringify(output) << "\n";
}

C++ Vertex Gemini Routing

Calls Gemini through Vertex with project and multi-region routing.

Provider: google-gemini
Env: GOOGLE_VERTEX_ACCESS_TOKEN, GOOGLE_PROJECT_ID, GOOGLE_REGION
Level: intermediate
Run: npm run example -- cpp src/examples/cpp/generation/vertex_gemini.cpp
Source: src/examples/cpp/generation/vertex_gemini.cpp

C++

#include "axllm/axllm.hpp"

#include <cstdlib>
#include <iostream>
#include <string>

const char* required(const char* name) {
  const char* value = std::getenv(name);
  if (value == nullptr || std::string(value).empty()) {
    std::cerr << "Set " << name << " to run this example.\n";
    std::exit(2);
  }
  return value;
}

int main() {
  const char* model = std::getenv("AX_VERTEX_MODEL");
  axllm::GoogleGeminiClient client(axllm::object({
      {"api_key", required("GOOGLE_VERTEX_ACCESS_TOKEN")},
      {"project_id", required("GOOGLE_PROJECT_ID")},
      {"region", required("GOOGLE_REGION")},
      {"model", model == nullptr || std::string(model).empty() ? "gemini-3.5-flash" : model},
  }));
  auto out = client.chat(axllm::object({
      {"chat_prompt", axllm::array({axllm::object({{"role", "user"}, {"content", "Reply with the word ready."}})})},
  }));
  std::cout << axllm::stringify(out) << "\n";
}

Cpp Jev Hybrid Reply

Passes Jev decisions to a second Ax program to generate a customer reply.

Provider: typesafe, openai
Env: TYPESAFE_APIKEY, OPENAI_APIKEY, OPENAI_API_KEY
Level: intermediate
Run: npm run example -- cpp src/examples/cpp/generation/typesafe-hybrid.cpp
Source: src/examples/cpp/generation/typesafe-hybrid.cpp

C++

#include "axllm/axllm.hpp"
#include <cstdlib>
#include <iostream>
#include <stdexcept>
using namespace axllm;

static std::string key(const char* name) { const char* value = std::getenv(name); if (!value || !*value) throw std::runtime_error(std::string("Set ") + name); return value; }
int main() {
  auto model = ai("typesafe", object({{"api_key", key("TYPESAFE_APIKEY")}, {"trueThreshold", 0.9}}));
  auto triage = ax("ticket:string -> urgent:boolean(true \"Customers cannot complete a core task\", false \"Routine request\") \"Needs immediate attention?\", team:class \"support, billing, engineering\"");
  auto decision = triage.forward(*model, object({{"ticket", "Checkout is unavailable for all customers after the latest deployment."}}));
  if (!Core::get(decision, "urgent").is_bool()) throw std::runtime_error("Invalid boolean");
  const char* openai_key = std::getenv("OPENAI_API_KEY");
  auto writer = ai("openai", object({{"api_key", openai_key ? std::string(openai_key) : key("OPENAI_APIKEY")}, {"model", "gpt-5.6-luna"}, {"model_config", object({{"temperature", 1}})}}));
  auto inputs = object({{"ticket", "Checkout is unavailable for all customers after the latest deployment."}, {"urgent", Core::get(decision, "urgent")}, {"team", Core::get(decision, "team")}});
  auto reply = ax("ticket:string, urgent:boolean, team:string -> reply:string").forward(*writer, inputs);
  if (display(Core::get(reply, "reply")).empty()) throw std::runtime_error("Empty reply");
  std::cout << stringify(object({{"decision", decision}, {"reply", reply}})) << "\n";
}

C++ Signature Constraints

Builds native constrained fields and runs the signature with OpenAI.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: intermediate
Run: npm run example -- cpp src/examples/cpp/generation/signature-constraints.cpp
Source: src/examples/cpp/generation/signature-constraints.cpp

C++

#include "axllm/axllm.hpp"
#include <cstdlib>
#include <iostream>

axllm::Value field(const char* name, const char* title, axllm::Value type) {
  return axllm::Core::record_new(
      "Field", axllm::object({{"name", name}, {"title", title}, {"type", type}}));
}

int main() {
  const char* key = std::getenv("OPENAI_API_KEY");
  if (key == nullptr || std::string(key).empty()) key = std::getenv("OPENAI_APIKEY");
  if (key == nullptr || std::string(key).empty()) {
    std::cerr << "Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.\n";
    return 2;
  }
  const char* model = std::getenv("AX_OPENAI_MODEL");
  axllm::OpenAICompatibleClient client(axllm::object({
      {"api_key", key},
      {"model", model == nullptr || std::string(model).empty() ? "gpt-5.4-mini" : model},
      {"model_config", axllm::object({{"temperature", 0}})},
  }));

  axllm::Value signature = axllm::Core::record_new(
      "AxSignature",
      axllm::object({
          {"description", "Extract a constrained restaurant booking"},
          {"inputs",
           axllm::array({
               field("requestText", "Request Text",
                     axllm::Core::record_new(
                         "FieldType",
                         axllm::object({{"name", "string"}, {"minLength", 10}, {"maxLength", 500}}))),
               field("contactEmail", "Contact Email",
                     axllm::Core::record_new(
                         "FieldType", axllm::object({{"name", "string"}, {"format", "email"}}))),
           })},
          {"outputs",
           axllm::array({
               field("partySize", "Party Size",
                     axllm::Core::record_new(
                         "FieldType",
                         axllm::object({{"name", "number"}, {"minimum", 1}, {"maximum", 12}}))),
               field("bookingCode", "Booking Code",
                     axllm::Core::record_new(
                         "FieldType",
                         axllm::object({
                             {"name", "string"},
                             {"pattern", "^[A-Z]{3}-\\d{4}$"},
                             {"patternDescription", "Must look like ABC-1234"},
                         }))),
           })},
      }));
  axllm::Core::validate_signature(signature);
  axllm::AxGen program = axllm::ax(signature);
  axllm::Value output = program.forward(
      client,
      axllm::object({
          {"requestText", "Book dinner for four people under the name Ada Lovelace."},
          {"contactEmail", "ada@example.com"},
      }));
  std::cout << axllm::stringify(output) << "\n";
}

C++ Incremental Provider Stream

Handles OpenAI SSE chunks incrementally and can cancel by returning false.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: intermediate
Run: npm run example -- cpp src/examples/cpp/generation/provider_stream.cpp
Source: src/examples/cpp/generation/provider_stream.cpp

C++

#include "axllm/axllm.hpp"
#include <chrono>
#include <cstdlib>
#include <iostream>

int main() {
  const char* api_key = std::getenv("OPENAI_API_KEY");
  if (api_key == nullptr || std::string(api_key).empty()) api_key = std::getenv("OPENAI_APIKEY");
  if (api_key == nullptr || std::string(api_key).empty()) {
    std::cerr << "Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.\n";
    return 2;
  }
  const char* selected = std::getenv("AX_OPENAI_MODEL");
  std::string model = selected == nullptr || std::string(selected).empty() ? "gpt-5.6-luna" : selected;
  auto client = axllm::ai("openai", axllm::object({{"api_key", api_key}, {"model", model}}));
  const auto started = std::chrono::steady_clock::now();
  client->stream_each(
      axllm::object({{"chat_prompt", axllm::array({axllm::object({
          {"role", "user"}, {"content", "Reply with exactly: streaming works"}})})},
          {"model_config", axllm::object({{"temperature", 1}})}}),
      [&](const axllm::Value& event) {
        std::string content = axllm::display(axllm::Core::get(
            axllm::Core::get(axllm::Core::get(event, "results"), 0), "content", ""));
        if (!content.empty()) {
          auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
              std::chrono::steady_clock::now() - started).count();
          std::cout << "[" << elapsed << " ms] " << content << std::flush;
        }
        return true;
      });
  std::cout << "\n";
}

Centralized Usage Observer

Attributes every completed model call to a tenant, user, and request from one global observer.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: intermediate
Run: npm run example -- cpp src/examples/cpp/generation/usage_observer.cpp
Source: src/examples/cpp/generation/usage_observer.cpp

C++

#include "axllm/axllm.hpp"

#include <chrono>
#include <cstdlib>
#include <iostream>
#include <string>
#include <vector>

int main() {
  const char* api_key = std::getenv("OPENAI_API_KEY");
  if (api_key == nullptr || std::string(api_key).empty()) api_key = std::getenv("OPENAI_APIKEY");
  if (api_key == nullptr || std::string(api_key).empty()) {
    std::cerr << "Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.\n";
    return 2;
  }
  const char* configured_model = std::getenv("AX_OPENAI_MODEL");
  std::string model =
      configured_model == nullptr || std::string(configured_model).empty()
          ? "gpt-5.4-mini"
          : configured_model;

  std::vector<axllm::AxUsageEvent> events;
  axllm::set_usage_observer(
      [&events](axllm::AxUsageEvent event) { events.push_back(std::move(event)); });
  axllm::OpenAICompatibleClient client(axllm::object({
      {"api_key", api_key},
      {"model", model},
      {"usageContext",
       axllm::object({
           {"tenantId", "tenant-42"},
           {"feature", "support-chat"},
           {"attributes", axllm::object({{"environment", "example"}})},
       })},
  }));
  client.chat(
      axllm::object({
          {"chat_prompt",
           axllm::array({
               axllm::object({{"role", "user"}, {"content", "Reply with one short greeting."}}),
           })},
      }),
      axllm::object({
          {"usageContext",
           axllm::object({
               {"userId", "user-7"},
               {"requestId",
                "request-" +
                    std::to_string(
                        std::chrono::steady_clock::now().time_since_epoch().count())},
           })},
      }));
  axllm::set_usage_observer({});
  std::cout << axllm::stringify(axllm::Value(axllm::Array(events.begin(), events.end())))
            << "\n";
}

C++ Portable Cancellation

Cancels a provider request before transport and preserves the first cancellation reason.

Provider: openai-compatible
Env: none
Level: intermediate
Run: npm run example -- cpp src/examples/cpp/generation/cancellation.cpp
Source: src/examples/cpp/generation/cancellation.cpp

C++

#include "axllm/axllm.hpp"

#include <iostream>
#include <string>

class CountingTransport final : public axllm::Transport {
 public:
  axllm::Value call(axllm::Value) override {
    ++calls;
    return axllm::object({{"status", 200}, {"json", axllm::Value::object()}});
  }
  int calls = 0;
};

int main() {
  CountingTransport transport;
  axllm::OpenAICompatibleClient client(
      axllm::object({{"api_key", "test-key"}, {"model", "gpt-5.6-luna"}}), &transport);
  axllm::AxCancellationToken token;
  if (!token.cancel("user stopped") || token.cancel("later reason")) return 2;

  try {
    client.chat(
        axllm::object({{"chat_prompt", axllm::array({axllm::object({
            {"role", "user"}, {"content", "This must not be sent."}})})}}),
        axllm::Value::object(), &token);
    return 3;
  } catch (const axllm::AxAIServiceAbortedError& error) {
    if (error.retryable || std::string(error.what()).find("user stopped") == std::string::npos) return 4;
  }

  if (transport.calls != 0) return 5;
  std::cout << "cancelled before transport: user stopped\n";
}

C++ Gemini Flex Inference

Sends latency-tolerant work through Gemini Flex and reports the applied tier.

Provider: google-gemini
Env: GOOGLE_API_KEY, GOOGLE_APIKEY
Level: intermediate
Run: npm run example -- cpp src/examples/cpp/generation/gemini_service_tier.cpp
Source: src/examples/cpp/generation/gemini_service_tier.cpp

C++

#include "axllm/axllm.hpp"

#include <cstdlib>
#include <iostream>
#include <string>

int main() {
  const char* key = std::getenv("GOOGLE_API_KEY");
  if (key == nullptr || std::string(key).empty()) key = std::getenv("GOOGLE_APIKEY");
  if (key == nullptr || std::string(key).empty()) {
    std::cerr << "Set GOOGLE_API_KEY or GOOGLE_APIKEY to run this example.\n";
    return 2;
  }
  const char* model = std::getenv("AX_GEMINI_MODEL");
  axllm::GoogleGeminiClient client(axllm::object({
      {"api_key", key},
      {"model", model == nullptr || std::string(model).empty() ? "gemini-3.8-flash" : model},
  }));
  axllm::Value out = client.chat(axllm::object({
      {"chat_prompt", axllm::array({axllm::object({
          {"role", "user"},
          {"content", "Explain in one sentence why batch evaluations save time."},
      })})},
  }), axllm::object({{"service_tier", "flex"}}));
  std::cout << axllm::stringify(out) << "\n";
}

C++ Native File Routing

Summarizes a PDF through a provider router without replacing the native file with extracted text.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY, AX_PDF_BASE64
Level: intermediate
Run: npm run example -- cpp src/examples/cpp/generation/native_file_routing.cpp
Source: src/examples/cpp/generation/native_file_routing.cpp

C++

#include "axllm/axllm.hpp"
#include <cstdlib>
#include <iostream>
int main() {
 using namespace axllm;
 const char* key=std::getenv("OPENAI_API_KEY");if(!key)key=std::getenv("OPENAI_APIKEY");const char* pdf=std::getenv("AX_PDF_BASE64");
 if(!key||!pdf){std::cerr<<"Set OPENAI_API_KEY and AX_PDF_BASE64.\n";return 2;}
 auto client=ai("openai",object({{"api_key",key},{"model","gpt-6-astra"},{"model_config",object({{"thinkingTokenBudget","low"}})}}));
 ProviderRouter router(std::vector<std::shared_ptr<AxAIService>>{client});
 auto program=ax("document:file -> summary:string");
 auto result=program.forward(router,object({{"document",object({{"filename","report.pdf"},{"mimeType","application/pdf"},{"data",pdf}})}}),object({{"serviceTier","standard"}}));
 std::cout<<stringify(result)<<"\n";
}

C++ Automatic Background Tools

Uses ordinary generation with background tools, steering, and a reasoning update.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: advanced
Run: npm run example -- cpp src/examples/cpp/generation/astra_async.cpp
Source: src/examples/cpp/generation/astra_async.cpp

C++

#include "axllm/axllm.hpp"
#include <iostream>
using namespace axllm;

struct RunState { std::atomic<bool> pending{false},finished{false},overlap{false},steered{false};std::atomic<int> applied{0};AxRunControl control; };

int main(){
  const char* key=std::getenv("OPENAI_API_KEY");if(!key||!*key)key=std::getenv("OPENAI_APIKEY");if(!key||!*key)throw std::runtime_error("Set OPENAI_API_KEY or OPENAI_APIKEY.");
  auto client=ai("openai",object({{"api_key",key},{"model","gpt-6-astra"},{"model_config",object({{"thinkingTokenBudget","low"},{"max_tokens",4096}})}}));
  auto state=std::make_shared<RunState>();auto control=state->control;std::weak_ptr<RunState> weak=state;
  control.on_event([weak](Value event){if(auto state=weak.lock();state&&stringify(Core::get(event,"type"))=="\"applied\"")++state->applied;});
  Value schema=object({{"type","object"},{"properties",Value::object()},{"additionalProperties",false}});
  Tool slow("slow_reference","Look up a reference; takes a few seconds.",schema,[state](Value){state->pending.store(true);if(!state->steered.exchange(true)){state->control.steer("Include the word VERIFIED in the final answer.");state->control.set_thinking_token_budget("medium");}std::this_thread::sleep_for(std::chrono::seconds(6));state->finished.store(true);return Value("REF-42");});slow.execution("background");
  Tool label("local_label","Read an independent local label immediately.",schema,[state](Value){for(int i=0;i<300&&!state->pending.load();++i)std::this_thread::sleep_for(std::chrono::milliseconds(10));if(state->pending.load()&&!state->finished.load())state->overlap.store(true);return Value("LAUNCH");});
  auto program=ax("question -> answer");program.add_tool(slow).add_tool(label);
  Value result=program.forward(*client,object({{"question","First call slow_reference. While it is pending, call local_label. Call each tool only once; do not call a tool again while its result is pending. If a required tool result is still pending, end this response with a brief progress message. The application will continue with the result when it arrives; do not spend reasoning tokens waiting for it. Once both results arrive, return them in one sentence."}}),object({{"control",control.value()},{"serviceTier","standard"},{"maxSteps",6}}));
  std::string answer=stringify(result);for(const std::string& word:{"REF-42","LAUNCH","VERIFIED"})if(answer.find(word)==std::string::npos)throw std::runtime_error("Missing final result: "+answer);
  if(!state->overlap.load())throw std::runtime_error("No independent work while background tool was pending");if(state->applied.load()!=2)throw std::runtime_error("Control updates were not applied");
  std::cout<<answer<<"\nBackground overlap verified; steering and reasoning applied at the next response.\n";
}

C++ Cancel Background Work

Cancels a live Astra run through the high-level controller and observes cooperative tool cancellation.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: advanced
Run: npm run example -- cpp src/examples/cpp/generation/astra_cancellation.cpp
Source: src/examples/cpp/generation/astra_cancellation.cpp

C++

#include "axllm/axllm.hpp"
#include <iostream>
using namespace axllm;
struct CancellationState {AxRunControl control;std::atomic<bool> settled{false};std::atomic<long long> started{0};};
int main(){
 const char* key=std::getenv("OPENAI_API_KEY");if(!key||!*key)key=std::getenv("OPENAI_APIKEY");if(!key||!*key)throw std::runtime_error("Set OPENAI_API_KEY or OPENAI_APIKEY.");
 auto state=std::make_shared<CancellationState>();
 Tool lookup("lookup","Look up the reference.");lookup.execution("background").context_handler([state](Value,const AxToolContext& context){state->started.store(std::chrono::steady_clock::now().time_since_epoch().count());state->control.abort();auto deadline=std::chrono::steady_clock::now()+std::chrono::seconds(2);while(!context.is_cancelled()&&std::chrono::steady_clock::now()<deadline)std::this_thread::sleep_for(std::chrono::milliseconds(1));if(!context.is_cancelled())throw std::runtime_error("Tool missed cancellation");state->settled.store(true);return Value("LATE: discard this result");});
 auto program=ax("question -> answer");program.add_tool(lookup);
 auto client=ai("openai",object({{"api_key",key},{"model","gpt-6-astra"},{"model_config",object({{"thinkingTokenBudget","low"},{"max_tokens",2048}})}}));
 try{program.forward(*client,object({{"question","Call lookup once and return its result."}}),object({{"control",state->control.value()},{"serviceTier","standard"}}));throw std::runtime_error("Cancelled run returned success");}
 catch(const AxError& error){auto started=std::chrono::steady_clock::time_point(std::chrono::steady_clock::duration(state->started.load()));auto elapsed=std::chrono::steady_clock::now()-started;if(!state->started.load()||std::string(error.what()).find("unresolved calls")==std::string::npos||elapsed>std::chrono::seconds(2))throw;auto deadline=std::chrono::steady_clock::now()+std::chrono::seconds(2);while(!state->settled.load()&&std::chrono::steady_clock::now()<deadline)std::this_thread::sleep_for(std::chrono::milliseconds(1));if(!state->settled.load())throw std::runtime_error("Tool missed cancellation");std::cout<<"Cancelled in "<<std::chrono::duration_cast<std::chrono::milliseconds>(elapsed).count()<<"ms; "<<error.what()<<"\n";}
}

C++ Contextual Generation

Answers from supplied context and returns compact citations with OpenAI.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: advanced
Run: npm run example -- cpp src/examples/cpp/generation/context_generation.cpp
Source: src/examples/cpp/generation/context_generation.cpp

C++

#include "axllm/axllm.hpp"
#include <cstdlib>
#include <fstream>
#include <iostream>
#include <sstream>


int main() {
  const char* key = std::getenv("OPENAI_API_KEY");
  if (key == nullptr || std::string(key).empty()) key = std::getenv("OPENAI_APIKEY");
  if (key == nullptr || std::string(key).empty()) {
    std::cerr << "Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.\n";
    return 2;
  }
  const char* model = std::getenv("AX_OPENAI_MODEL");
  axllm::OpenAICompatibleClient client(axllm::object({
      {"api_key", key},
      {"model", model == nullptr || std::string(model).empty() ? "gpt-5.4-mini" : model},
      {"model_config", axllm::object({{"temperature", 0}})},
  }));
  axllm::AxGen program = axllm::ax("context:string, question:string -> answer:string, citations:string[]");
  axllm::Value output = program.forward(client, axllm::object({{"context", "Ax uses signatures, ai(), ax(), agent(), flow(), and optimize()."}, {"question", "How should a new developer think about Ax?"}}));
  std::cout << axllm::stringify(output) << "\n";
}

Cpp Jev Native Questions

Uses structured criteria, native scoring, model discovery, and probability-based decisions.

Provider: typesafe
Env: TYPESAFE_APIKEY
Level: advanced
Run: npm run example -- cpp src/examples/cpp/generation/typesafe-native.cpp
Source: src/examples/cpp/generation/typesafe-native.cpp

C++

#include "axllm/axllm.hpp"
#include <cstdlib>
#include <iostream>
#include <stdexcept>
using namespace axllm;

static std::string key(const char* name) { const char* value = std::getenv(name); if (!value || !*value) throw std::runtime_error(std::string("Set ") + name); return value; }
int main() {
  auto client = typesafe(object({{"api_key", key("TYPESAFE_APIKEY")}}));
  if (client.list_models().empty()) throw std::runtime_error("Empty catalog");
  TypesafeRequest request;
  request.state = object({
    {"ticket", "Checkout is unavailable for all customers after the latest deployment."},
    {"account", object({{"tier", "enterprise"}, {"notes", Value()}})}
  });
  request.questions = {
    {"urgent", {"noul", object({{"question", "Does this need immediate attention?"}}),
      object({{"true", "Customers cannot complete a core task"}, {"false", "Routine request"}})}},
    {"team", {"choice", "Who should handle the ticket?",
      object({{"support", "Usage guidance"}, {"billing", object({{"scope", "Invoices and payments"}})},
              {"engineering", "Product failures"}})}},
    {"severity", {"score", "Rate customer impact",
      array({"Minor inconvenience", "One task blocked", "Core task unavailable", "Widespread outage"})}}
  };
  auto response = client.system_one(request);
  double probability = std::get<TypesafeNoul>(response.answers.at("urgent")).noul;
  double score = std::get<TypesafeScore>(response.answers.at("severity")).score;
  if (probability < 0 || probability > 1 || score < 0 || score > 3) throw std::runtime_error("Invalid bounds");
  // Apply thresholds and custom score scales in application code.
  std::cout << stringify(object({{"page_on_call", probability >= 0.9}, {"severity_1_to_5", 1 + 4 * score / 3}, {"response", response.to_value()}})) << "\n";
}

C++ Adaptive Provider Balancing

Routes equivalent chat traffic using shared reliability, latency, and cost statistics.

Provider: openai-compatible
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: advanced
Run: npm run example -- cpp src/examples/cpp/generation/adaptive_balancer.cpp
Source: src/examples/cpp/generation/adaptive_balancer.cpp

C++

#include "axllm/axllm.hpp"

#include <cstdlib>
#include <iostream>
#include <memory>
#include <vector>

int main() {
  const char* raw_key = std::getenv("OPENAI_API_KEY");
  if (raw_key == nullptr || std::string(raw_key).empty()) raw_key = std::getenv("OPENAI_APIKEY");
  if (raw_key == nullptr || std::string(raw_key).empty()) {
    std::cerr << "Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.\n";
    return 2;
  }
  const std::string model = std::getenv("AX_OPENAI_MODEL") == nullptr ? "gpt-5.4-mini" : std::getenv("AX_OPENAI_MODEL");
  auto primary = std::make_shared<axllm::OpenAICompatibleClient>(axllm::object({{"api_key", raw_key}, {"model", model}}));
  auto backup = std::make_shared<axllm::OpenAICompatibleClient>(axllm::object({{"api_key", raw_key}, {"model", model}}));

  auto store = std::make_shared<axllm::AxInMemoryBalancerStatsStore>();
  std::vector<std::string> route_keys{"openai-primary", "openai-backup"};
  std::vector<std::string> events;
  auto strategy = std::make_shared<axllm::AxBalancerAdaptiveStrategy>();
  strategy->deadline_ms = 6'000;
  strategy->bad_outcome_cost = 0.02;
  strategy->expected_tokens = axllm::object({{"promptTokens", 1'200}, {"completionTokens", 300}});
  strategy->name_space = "support-summary-v1";
  strategy->route_key = [route_keys](const std::shared_ptr<axllm::AxAIService>&, std::size_t index) { return route_keys.at(index); };
  strategy->slice = [](axllm::Value context) { return axllm::Core::truthy(axllm::Core::get(axllm::Core::get(context, "options"), "stream")) ? "streaming" : "interactive"; };
  strategy->stats_store = store;
  strategy->on_routing_event = [&events](axllm::Value event) { events.push_back(axllm::display(axllm::Core::get(event, "type"))); };

  axllm::AxBalancerOptions options;
  options.strategy = strategy;
  axllm::AxBalancer balancer({primary, backup}, options);
  auto response = balancer.chat(axllm::object({{"model", model}, {"chat_prompt", axllm::array({axllm::object({{"role", "user"}, {"content", "Summarize why shared routing state matters."}})})}}));
  std::cout << axllm::stringify(response) << "\n" << events.size() << " routing events\n";
}

Portable Runtime Hooks

Applies global and forward-scoped rate limiting, tracing, and metrics to AxGen, AxAgent, and AxFlow.

Provider: openai
Env: OPENAI_API_KEY, OPENAI_APIKEY
Level: advanced
Run: npm run example -- cpp src/examples/cpp/generation/runtime_hooks.cpp
Source: src/examples/cpp/generation/runtime_hooks.cpp

C++

#include "axllm/axllm.hpp"
#include "axllm/runtime/quickjs/quickjs_runtime.hpp"

#include <cstdlib>
#include <iostream>
#include <memory>

class LogSpan final : public axllm::AxSpan {
 public:
  explicit LogSpan(std::string name) : name_(std::move(name)) { std::cout << "[span:start] " << name_ << "\n"; }
  void set_attributes(axllm::Value) override {}
  void add_event(std::string event, axllm::Value) override { std::cout << "[span:event] " << name_ << " " << event << "\n"; }
  void record_exception(std::string error) override { std::cout << "[span:error] " << name_ << " " << error << "\n"; }
  void set_status(std::string, std::string) override {}
  void end() override { std::cout << "[span:end] " << name_ << "\n"; }
 private:
  std::string name_;
};

class LogTracer final : public axllm::AxTracer {
 public:
  std::shared_ptr<axllm::AxSpan> start_span(const axllm::AxSpanStart& start) override { return std::make_shared<LogSpan>(start.name); }
};

class LogInstrument final : public axllm::AxCounter, public axllm::AxHistogram, public axllm::AxGauge {
 public:
  explicit LogInstrument(std::string name) : name_(std::move(name)) {}
  void add(double value, axllm::Value) override { std::cout << "[metric] " << name_ << " += " << value << "\n"; }
  void record(double value, axllm::Value) override { std::cout << "[metric] " << name_ << " = " << value << "\n"; }
 private:
  std::string name_;
};

class LogMeter final : public axllm::AxMeter {
 public:
  std::shared_ptr<axllm::AxCounter> create_counter(std::string name, axllm::AxMetricInstrumentOptions) override { return std::make_shared<LogInstrument>(std::move(name)); }
  std::shared_ptr<axllm::AxHistogram> create_histogram(std::string name, axllm::AxMetricInstrumentOptions) override { return std::make_shared<LogInstrument>(std::move(name)); }
  std::shared_ptr<axllm::AxGauge> create_gauge(std::string name, axllm::AxMetricInstrumentOptions) override { return std::make_shared<LogInstrument>(std::move(name)); }
};

axllm::AxRateLimiter limiter(std::string label) {
  return [label = std::move(label)](axllm::AxRequestExecutor next, const axllm::AxRateLimitInfo& info) {
    std::cout << "[limit:" << label << "] " << info.operation << " " << info.provider << "/" << info.model << " stream=" << info.streaming << "\n";
    return next();
  };
}

int main() {
  const char* key = std::getenv("OPENAI_API_KEY");
  if (key == nullptr || std::string(key).empty()) key = std::getenv("OPENAI_APIKEY");
  if (key == nullptr || std::string(key).empty()) { std::cerr << "Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.\n"; return 2; }
  const char* configured_model = std::getenv("AX_OPENAI_MODEL");
  axllm::OpenAICompatibleClient client(axllm::object({
      {"api_key", key},
      {"model", configured_model == nullptr || std::string(configured_model).empty() ? "gpt-5.4-mini" : configured_model},
      {"model_config", axllm::object({{"temperature", 0}})},
  }));
  auto tracer = std::make_shared<LogTracer>();
  auto meter = std::make_shared<LogMeter>();
  axllm::AxRuntimeHooks override_hooks{limiter("forward"), tracer, meter};

  axllm::set_rate_limiter(limiter("global"));
  axllm::set_tracer(tracer);
  axllm::set_meter(meter);
  try {
    auto direct = axllm::ax("topic:string -> summary:string");
    std::cout << axllm::stringify(direct.forward(client, axllm::object({{"topic", "portable Ax runtime hooks"}}))) << "\n";

    auto helper = axllm::agent("question:string -> answer:string");
    axllm::runtime::quickjs::QuickJsCodeRuntime runtime;
    std::cout << axllm::stringify(helper.forward(
        client,
        axllm::object({{"question", "What does a rate limiter wrap?"}}),
        axllm::object({{"runtime", axllm::Core::code_runtime_ref(runtime)}, {"max_actor_steps", 12}}),
        override_hooks)) << "\n";

    auto outline = axllm::ax("topic:string -> outline:string");
    auto polish = axllm::ax("outline:string -> answer:string");
    auto workflow = axllm::flow(axllm::object({{"id", "examples.runtimeHooks"}}))
        .execute("outline", outline)
        .execute("polish", polish)
        .returns(axllm::object({{"answer", "polish"}}));
    std::cout << axllm::stringify(workflow.forward(client, axllm::object({{"topic", "Ax runtime hooks"}}), axllm::Value::object(), override_hooks)) << "\n";
  } catch (...) {
    axllm::set_rate_limiter({}); axllm::set_tracer({}); axllm::set_meter({});
    throw;
  }
  axllm::set_rate_limiter({}); axllm::set_tracer({}); axllm::set_meter({});
}