Optimization

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

Java 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 -- java src/examples/java/optimization/AxgenOptimizationExample.java
Source: src/examples/java/optimization/AxgenOptimizationExample.java

Java

import dev.axllm.ax.*;
import java.nio.file.*;
import java.util.*;

public final class AxgenOptimizationExample {
  static String apiKey() {
    String apiKey = System.getenv("OPENAI_API_KEY");
    if (apiKey == null || apiKey.isBlank()) apiKey = System.getenv("OPENAI_APIKEY");
    if (apiKey == null || apiKey.isBlank()) {
      throw new IllegalStateException("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.");
    }
    return apiKey;
  }

  static OpenAICompatibleClient client() {
    return new OpenAICompatibleClient(
        Map.of("api_key", apiKey(), "model", System.getenv().getOrDefault("AX_OPENAI_MODEL", "gpt-5.4-mini"), "model_config", Map.of("temperature", 0.0)));
  }

  static final class ExampleOptimizer implements OptimizerEngine {
    public String name() { return "example"; }
    public String version() { return "1"; }
    public Map<String, Object> optimize(Map<String, Object> request) {
      return Map.of("componentMap", Map.of("priority::instruction", "Classify operational risk. Use high for production-impacting urgency."), "metadata", Map.of("source", "axgen"));
    }
  }

  public static void main(String[] args) throws Exception {
    AxGen program = new AxGen(Ax.s("emailText:string -> priority:class \"high, normal, low\", rationale:string"), Map.of("id", "priority", "instruction", "Classify the email priority."));
    Map<String, Object> baseline = program.forward(client(), Map.of("emailText", "Production checkout is failing for enterprise customers."));
    Map<String, Object> artifact = program.optimizeWith(new ExampleOptimizer(), List.of(Map.of("emailText", "URGENT: checkout is down", "priority", "high")), Map.of("apply", false));
    program.applyOptimization(Json.stringify(artifact));
    Map<String, Object> after = program.forward(client(), Map.of("emailText", "Production checkout is failing for enterprise customers."));
    System.out.println(Json.stringify(Map.of("baseline", baseline, "after", after)));
  }
}

Java 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 -- java src/examples/java/optimization/GepaOptimizationExample.java
Source: src/examples/java/optimization/GepaOptimizationExample.java

Java

import dev.axllm.ax.*;
import java.nio.file.*;
import java.util.*;

public final class GepaOptimizationExample {
  static String apiKey() {
    String apiKey = System.getenv("OPENAI_API_KEY");
    if (apiKey == null || apiKey.isBlank()) apiKey = System.getenv("OPENAI_APIKEY");
    if (apiKey == null || apiKey.isBlank()) {
      throw new IllegalStateException("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.");
    }
    return apiKey;
  }

  static OpenAICompatibleClient client() {
    return new OpenAICompatibleClient(
        Map.of("api_key", apiKey(), "model", System.getenv().getOrDefault("AX_OPENAI_MODEL", "gpt-5.4-mini"), "model_config", Map.of("temperature", 0.0)));
  }

  static final class LocalEvaluator implements OptimizerEvaluator {
    public Map<String, Object> evaluate(Map<String, Object> candidateMap, Map<String, Object> options) {
      return Map.of("rows", List.of(Map.of("prediction", Map.of("answer", "Ax composes typed LLM programs."), "scores", Map.of("quality", 0.9), "scalar", 0.9)), "avg", 0.9, "count", 1);
    }
  }

  public static void main(String[] args) throws Exception {
    AxGen program = new AxGen(Ax.s("emailText:string -> priority:class \"high, normal, low\", rationale:string"), Map.of("id", "priority", "instruction", "Classify the email priority."));
    Map<String, Object> baseline = program.forward(client(), Map.of("emailText", "Production checkout is failing for enterprise customers."));
    Map<String, Object> request = Map.of("programKind", "axgen", "components", List.of(Map.of("id", "priority::instruction", "owner", "priority", "kind", "instruction", "current", "Classify priority clearly.")), "dataset", Map.of("train", List.of(Map.of("emailText", "URGENT: checkout is down"))), "options", Map.of("numTrials", 0, "maxMetricCalls", 4, "seed", 7));
    Map<String, Object> artifact = new AxGEPA(null, Map.of("seed", 7)).optimize(request, new LocalEvaluator());
    System.out.println(Json.stringify(Map.of("baseline", baseline, "artifact", artifact)));
  }
}

Java 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 -- java src/examples/java/optimization/ArtifactOptimizationExample.java
Source: src/examples/java/optimization/ArtifactOptimizationExample.java

Java

import dev.axllm.ax.*;
import java.nio.file.*;
import java.util.*;

public final class ArtifactOptimizationExample {
  static String apiKey() {
    String apiKey = System.getenv("OPENAI_API_KEY");
    if (apiKey == null || apiKey.isBlank()) apiKey = System.getenv("OPENAI_APIKEY");
    if (apiKey == null || apiKey.isBlank()) {
      throw new IllegalStateException("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.");
    }
    return apiKey;
  }

  static OpenAICompatibleClient client() {
    return new OpenAICompatibleClient(
        Map.of("api_key", apiKey(), "model", System.getenv().getOrDefault("AX_OPENAI_MODEL", "gpt-5.4-mini"), "model_config", Map.of("temperature", 0.0)));
  }

  static final class ExampleOptimizer implements OptimizerEngine {
    public String name() { return "example"; }
    public String version() { return "1"; }
    public Map<String, Object> optimize(Map<String, Object> request) {
      return Map.of("componentMap", Map.of("priority::instruction", "Classify operational risk. Use high for production-impacting urgency."), "metadata", Map.of("source", "artifact"));
    }
  }

  public static void main(String[] args) throws Exception {
    AxGen program = new AxGen(Ax.s("emailText:string -> priority:class \"high, normal, low\", rationale:string"), Map.of("id", "priority", "instruction", "Classify the email priority."));
    Map<String, Object> baseline = program.forward(client(), Map.of("emailText", "Production checkout is failing for enterprise customers."));
    Map<String, Object> artifact = program.optimizeWith(new ExampleOptimizer(), List.of(Map.of("emailText", "URGENT: checkout is down", "priority", "high")), Map.of("apply", false));
    program.applyOptimization(Json.stringify(artifact));
    Map<String, Object> after = program.forward(client(), Map.of("emailText", "Production checkout is failing for enterprise customers."));
    System.out.println(Json.stringify(Map.of("baseline", baseline, "after", after)));
  }
}

Java 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 -- java src/examples/java/optimization/AgentPlaybookEvolveExample.java
Source: src/examples/java/optimization/AgentPlaybookEvolveExample.java

Java

import dev.axllm.ax.*;
import dev.axllm.ax.runtime.quickjs.*;
import java.util.*;
import java.util.function.Consumer;

public final class AgentPlaybookEvolveExample {
  static String apiKey() {
    String value = System.getenv("OPENAI_API_KEY");
    if (value == null || value.isBlank()) value = System.getenv("OPENAI_APIKEY");
    if (value == null || value.isBlank()) {
      throw new IllegalStateException("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.");
    }
    return value;
  }

  public static void main(String[] args) throws Exception {
    OpenAICompatibleClient client = new OpenAICompatibleClient(Map.of(
        "api_key", apiKey(),
        "model", System.getenv().getOrDefault("AX_OPENAI_MODEL", "gpt-5.4-mini")));

    Map<String, Object> bullet = Map.of(
        "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");
    Map<String, Object> seed = Map.of(
        "playbook", Map.of(
            "version", 1,
            "sections", Map.of("failures_to_avoid", List.of(bullet)),
            "updatedAt", "2026-07-15T00:00:00.000Z"),
        "artifact", Map.of("feedback", List.of(), "history", List.of()));

    List<Object> observedCitations = new ArrayList<>();
    List<Object> playbookUpdates = new ArrayList<>();
    Consumer<List<Object>> citationObserver = observedCitations::add;
    Consumer<Map<String, Object>> playbookObserver = playbookUpdates::add;
    AxAgent assistant = Ax.agent(
        "question:string -> answer:string",
        Map.of(
            "ai", client,
            "contextFields", List.of(),
            "runtime", Map.of("language", "JavaScript"),
            "playbook", Map.of("seed", seed, "onUpdate", playbookObserver),
            "citations", Map.of("surface", "hidden", "onCitations", citationObserver)));
    assistant
        .setInstruction("Answer from evidence and state uncertainty plainly.")
        .addActorInstruction("Before finishing, verify the answer against the collected evidence.");

    try (AxQuickJsCodeRuntime runtime = new AxQuickJsCodeRuntime()) {
      Map<String, Object> answer = assistant.forward(
          client,
          Map.of("question", "What should a support agent verify before answering?"),
          Map.of("runtime", runtime, "max_actor_steps", 8));

      Map<String, Object> dataset = Map.of(
          "train", List.of(Map.of(
              "input", Map.of("question", "Give a concise evidence-first answer."),
              "score", 0)));
      Map<String, Object> evolution = assistant.playbook(null).evolve(
          dataset,
          Map.of("verify", true, "maxProposals", 1, "runtime", runtime));

      System.out.println(Json.pretty(answer));
      System.out.println("citations: " + (observedCitations.isEmpty() ? List.of() : observedCitations.get(observedCitations.size() - 1)));
      System.out.println("run-end updates: " + playbookUpdates.size());
      System.out.println("outcomes: " + evolution.get("outcomes"));
      System.out.println(assistant.getPlaybook().render());
    }
  }
}