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 a baseline OpenAI prediction and applies an optimizer artifact.

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");
  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("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++ GEPA Optimization

Pairs a real OpenAI baseline with a local GEPA optimization pass.

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 LocalEvaluator : axllm::OptimizerEvaluator {
  axllm::Value evaluate(axllm::Value, axllm::Value) override {
    return axllm::object({{"rows", axllm::array({axllm::object({{"prediction", axllm::object({{"answer", "Ax composes typed LLM programs."}})}, {"scores", axllm::object({{"quality", 0.9}})}, {"scalar", 0.9}})})}, {"avg", 0.9}, {"count", 1}});
  }
};

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("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."}}));
  axllm::Value request = axllm::object({{"programKind", "axgen"}, {"components", axllm::array({axllm::object({{"id", "priority::instruction"}, {"owner", "priority"}, {"kind", "instruction"}, {"current", "Classify priority clearly."}})})}, {"dataset", axllm::object({{"train", axllm::array({axllm::object({{"emailText", "URGENT: checkout is down"}})})}})}, {"options", axllm::object({{"numTrials", 0}, {"maxMetricCalls", 4}, {"seed", 7}})}});
  LocalEvaluator evaluator;
  axllm::AxGEPA gepa(axllm::object({{"seed", 7}}));
  axllm::Value artifact = gepa.optimize(request, &evaluator);
  std::cout << axllm::stringify(axllm::object({{"baseline", baseline}, {"artifact", artifact}})) << "\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");
  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("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");
  axllm::OpenAICompatibleClient client(axllm::object({
      {"api_key", key},
      {"model", model == nullptr || std::string(model).empty() ? "gpt-5.4-mini" : 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({
          {"contextFields", axllm::array({})},
          {"runtime", axllm::object({{"language", "JavaScript"}})},
          {"playbook", axllm::object({{"seed", seed}})},
          {"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)},
      }));

  std::cout << axllm::stringify(answer) << "\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";
}