Optimization

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++ AxGen Optimization

Runs an OpenAI prediction, applies an optimizer artifact, and scores novel rationale overlap.

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

C++

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

struct ExampleOptimizer : axllm::OptimizerEngine {
  std::string name() const override { return "example"; }
  std::string version() const override { return "1"; }
  axllm::Value optimize(axllm::Value request) override { return optimize(std::move(request), nullptr); }
  axllm::Value optimize(axllm::Value, axllm::OptimizerEvaluator*) override {
    return axllm::object({{"componentMap", axllm::object({{"priority::instruction", "Classify operational risk. Use high for production-impacting urgency."}})}, {"metadata", axllm::object({{"source", "axgen"}})}});
  }
};

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-luna" : model},
      {"model_config", axllm::object({{"temperature", 0}})},
  }));
  axllm::AxGen program = axllm::ax("emailText:string -> priority:class \"high, normal, low\", rationale:string", axllm::object({{"id", "priority"}, {"instruction", "Classify the email priority."}}));
  axllm::Value baseline = program.forward(*client, axllm::object({{"emailText", "Production checkout is failing for enterprise customers."}}));
  ExampleOptimizer optimizer;
  axllm::Value artifact = program.optimize_with(optimizer, axllm::array({axllm::object({{"emailText", "URGENT: checkout is down"}, {"priority", "high"}})}), axllm::object({{"apply", false}}));
  program.apply_optimization(artifact);
  axllm::Value after = program.forward(*client, axllm::object({{"emailText", "Production checkout is failing for enterprise customers."}}));
  double score = axllm::novel_f1_score("", axllm::display(axllm::Core::get(after,"rationale")), "Production checkout is failing for enterprise customers.");
  std::cout << axllm::stringify(axllm::object({{"baseline", baseline}, {"after", after}, {"rationaleNovelF1", score}})) << "\n";
}

C++ GEPA Optimization

Scores real OpenAI predictions before and after GEPA instruction search.

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

C++

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

struct PriorityEvaluator : axllm::OptimizerEvaluator {
  axllm::AxGen& program;
  axllm::AIClient& client;
  PriorityEvaluator(axllm::AxGen& p, axllm::AIClient& c) : program(p), client(c) {}
  axllm::Value evaluate(axllm::Value candidate, axllm::Value options) override {
    auto result = program.evaluate_optimization(client, axllm::Core::get(options, "dataset"), candidate, options);
    double sum = 0;
    auto rows = axllm::Core::get(result, "rows");
    for (auto row : axllm::Core::iter(rows)) {
      auto expected = axllm::Core::get(axllm::Core::get(row, "input"), "expectedOutput");
      auto output = axllm::Core::get(axllm::Core::get(row, "prediction"), "output");
      double score = axllm::Core::truthy(axllm::Core::eq(axllm::Core::get(output, "priority"), axllm::Core::get(expected, "priority"))) ? 1 : 0;
      axllm::Core::set(row, "scores", axllm::object({{"accuracy", score}}));
      axllm::Core::set(row, "scalar", score);
      sum += score;
    }
    axllm::Core::set(result, "avg", sum / axllm::Core::iter(rows).size());
    return result;
  }
};
static axllm::Value task(const char* text, const char* priority) {
  return axllm::object({{"input", axllm::object({{"emailText", text}})}, {"expectedOutput", axllm::object({{"priority", priority}})}});
}

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-luna" : model},
  }));
  axllm::AxGen program = axllm::ax("emailText:string -> priority:class \"high, normal, low\", rationale:string", axllm::object({{"id", "priority"}, {"instruction", "Classify the email priority."}}));
  axllm::Value baseline = program.forward(*client, axllm::object({{"emailText", "Production checkout is failing for enterprise customers."}}));
  auto request = axllm::object({
      {"programKind", "axgen"}, {"components", program.get_optimizable_components()},
      {"dataset", axllm::object({{"train", axllm::array({task("URGENT: checkout is down", "high"), task("Weekly product newsletter", "low")})},
          {"validation", axllm::array({task("Production payments are failing", "high"), task("Optional community meetup invite", "low")})}})},
      {"options", axllm::object({{"numTrials", 1}, {"minibatchSize", 2}, {"maxMetricCalls", 12}, {"bootstrap", false}, {"seed", 7}})},
  });
  PriorityEvaluator evaluator(program, *client);
  axllm::AxGEPA gepa(client.get(), axllm::object({{"seed", 7}}));
  auto artifact = gepa.optimize(request, &evaluator);
  auto original = axllm::Core::get(artifact, "baselineScore");
  auto best = axllm::Core::get(axllm::Core::get(artifact, "metadata"), "bestScore");
  std::cout << axllm::stringify(axllm::object({{"baselinePrediction", baseline}, {"baselineScore", original},
      {"baselineScores", axllm::Core::get(artifact, "baselineScores")}, {"optimizedScore", best}, {"delta", axllm::Core::number(best) - axllm::Core::number(original)}})) << "\n";
}

C++ Optimization Artifact Reuse

Saves and reapplies an optimizer artifact after a real OpenAI baseline.

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

C++

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

struct ExampleOptimizer : axllm::OptimizerEngine {
  std::string name() const override { return "example"; }
  std::string version() const override { return "1"; }
  axllm::Value optimize(axllm::Value request) override { return optimize(std::move(request), nullptr); }
  axllm::Value optimize(axllm::Value, axllm::OptimizerEvaluator*) override {
    return axllm::object({{"componentMap", axllm::object({{"priority::instruction", "Classify operational risk. Use high for production-impacting urgency."}})}, {"metadata", axllm::object({{"source", "artifact"}})}});
  }
};

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-5.4-mini" : model},
      {"model_config", axllm::object({{"temperature", 0}})},
  }));
  axllm::AxGen program = axllm::ax("emailText:string -> priority:class \"high, normal, low\", rationale:string", axllm::object({{"id", "priority"}, {"instruction", "Classify the email priority."}}));
  axllm::Value baseline = program.forward(*client, axllm::object({{"emailText", "Production checkout is failing for enterprise customers."}}));
  ExampleOptimizer optimizer;
  axllm::Value artifact = program.optimize_with(optimizer, axllm::array({axllm::object({{"emailText", "URGENT: checkout is down"}, {"priority", "high"}})}), axllm::object({{"apply", false}}));
  program.apply_optimization(artifact);
  axllm::Value after = program.forward(*client, axllm::object({{"emailText", "Production checkout is failing for enterprise customers."}}));
  std::cout << axllm::stringify(axllm::object({{"baseline", baseline}, {"after", after}})) << "\n";
}

C++ Agent Playbook — Learn And Verify

Attach a persistent playbook, add validated hidden citations and stage guidance, then mine a task set into playbook rules with a verification gate.

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

C++

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

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

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-luna" : model},
  }));

  axllm::Value bullet = axllm::object({
      {"id", "failures-to-avoid-00001"},
      {"section", "failures_to_avoid"},
      {"content", "Check the available evidence before answering."},
      {"helpfulCount", 0},
      {"harmfulCount", 0},
      {"createdAt", "2026-07-15T00:00:00.000Z"},
      {"updatedAt", "2026-07-15T00:00:00.000Z"},
  });
  axllm::Value seed = axllm::object({
      {"playbook", axllm::object({
          {"version", 1},
          {"sections", axllm::object({{"failures_to_avoid", axllm::array({bullet})}})},
          {"updatedAt", "2026-07-15T00:00:00.000Z"},
      })},
      {"artifact", axllm::object({{"feedback", axllm::array({})}, {"history", axllm::array({})}})},
  });

  auto assistant = axllm::agent(
      "question:string -> answer:string",
      axllm::object({
          // The playbook learns with the agent's own client.
          {"ai", axllm::Core::client_ref(*client)},
          {"contextFields", axllm::array({})},
          {"runtime", axllm::object({{"language", "JavaScript"}})},
          {"playbook", axllm::object({{"playbook", seed}, {"seed", 7}})},
          {"citations", axllm::object({{"surface", "hidden"}})},
      }));
  assistant
      .set_instruction("Answer from evidence and state uncertainty plainly.")
      .add_actor_instruction("Before finishing, verify the answer against the collected evidence.");

  axllm::Value observed_citations = axllm::array({});
  axllm::Value last_playbook_update;
  assistant.set_citations_observer([&observed_citations](axllm::Value value) {
    observed_citations = value;
  });
  assistant.set_playbook_observer([&last_playbook_update](axllm::Value value) {
    last_playbook_update = value;
  });

  axllm::runtime::quickjs::QuickJsCodeRuntime runtime;
  axllm::Value answer = assistant.forward(
      *client,
      axllm::object({{"question", "What should a support agent verify before answering?"}}),
      axllm::object({
          {"runtime", axllm::Core::code_runtime_ref(runtime)},
          {"max_actor_steps", 8},
      }));

  axllm::Value dataset = axllm::object({
      {"train", axllm::array({axllm::object({
          {"input", axllm::object({{"question", "Give a concise evidence-first answer."}})},
          {"score", 0},
      })})},
  });
  axllm::Value evolution = assistant.get_playbook()->evolve(
      dataset,
      axllm::object({
          {"verify", true},
          {"maxProposals", 1},
          {"runtime", axllm::Core::code_runtime_ref(runtime)},
      }));

  // Each train task replays on the runtime. A replay that fails scores 0 and
  // would be mined as the weakness, so stop instead.
  axllm::Value replays = axllm::array({});
  for (const auto& record : axllm::Core::iter(axllm::Core::get(evolution, "records", axllm::array({})))) {
    axllm::Value prediction = axllm::Core::get(record, "prediction", axllm::object({}));
    axllm::Value completion = axllm::Core::get(prediction, "completionType");
    if (!axllm::Core::get(record, "error").is_null() || axllm::display(completion) == "error") {
      std::cerr << "evolve replay failed: " << axllm::stringify(axllm::Core::get(record, "error"))
                << " " << axllm::stringify(axllm::Core::get(prediction, "error")) << "\n";
      return 1;
    }
    axllm::Core::append(replays, completion);
  }

  std::cout << axllm::stringify(answer) << "\n";
  std::cout << "replays: " << axllm::stringify(replays) << "\n";
  std::cout << "citations: " << axllm::stringify(observed_citations) << "\n";
  std::cout << "run-end update observed: " << (!last_playbook_update.is_null()) << "\n";
  std::cout << "outcomes: " << axllm::stringify(axllm::Core::get(evolution, "outcomes")) << "\n";
  std::cout << assistant.get_playbook()->render() << "\n";
}