Generation

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 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 -- java src/examples/java/generation/BasicGenerationExample.java
Source: src/examples/java/generation/BasicGenerationExample.java

Java

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

public final class BasicGenerationExample {
  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.6-luna"), "model_config", Map.of("temperature", 0.0)));
  }

  public static void main(String[] args) throws Exception {
    AxGen program = Ax.ax("question:string -> answer:string");
    Map<String, Object> output = program.forward(
        client(),
        Map.of("question", "In one sentence, explain Ax as a language-agnostic LLM programming library."),
        Map.of("promptCacheKey", "ax-openai-example", "contextCache", Map.of()));
    System.out.println(Json.stringify(output));
  }
}

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

Java

import dev.axllm.ax.Ax;
import java.util.*;

public final class ModelCatalogExample {
  private static Map<?, ?> provider(List<Object> catalog, String name) {
    return catalog.stream()
        .map(entry -> (Map<?, ?>) entry)
        .filter(entry -> name.equals(entry.get("name")))
        .findFirst()
        .orElseThrow();
  }

  public static void main(String[] args) {
    List<Object> catalog = Ax.getSupportedAIModels();
    Map<?, ?> azure = provider(catalog, "azure-openai");
    Map<?, ?> openrouter = provider(catalog, "openrouter");
    Map<?, ?> azureCapabilities = (Map<?, ?>) azure.get("capabilities");
    Map<?, ?> openrouterCapabilities = (Map<?, ?>) openrouter.get("capabilities");

    assert Boolean.TRUE.equals(azure.get("isDynamic"));
    assert ((List<?>) azure.get("models")).isEmpty();
    assert ((List<?>) azureCapabilities.get("thinkingLevels")).contains("high");
    assert ((List<?>) azureCapabilities.get("serviceTiers")).contains("priority");
    assert ((List<?>) openrouterCapabilities.get("serviceTiers")).contains("flex");

    System.out.println(catalog.size() + " providers; Azure and OpenRouter named profiles are available");
  }
}

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

Java

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

public final class StructuredGenerationExample {
  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)));
  }

  public static void main(String[] args) throws Exception {
    AxGen program = Ax.ax("ticket:string -> priority:class \"high, normal, low\", summary:string, labels:string[]");
    Map<String, Object> output = program.forward(client(), Map.of("ticket", "Checkout has failed for enterprise customers since 09:00. Support wants a concise summary and tags."));
    System.out.println(Json.stringify(output));
  }
}

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

Java

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

public final class VertexGeminiExample {
  private static String required(String name) {
    String value = System.getenv(name);
    if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name + " to run this example.");
    return value;
  }

  public static void main(String[] args) throws Exception {
    GoogleGeminiClient client = new GoogleGeminiClient(Map.of(
        "api_key", required("GOOGLE_VERTEX_ACCESS_TOKEN"),
        "project_id", required("GOOGLE_PROJECT_ID"),
        "region", required("GOOGLE_REGION"),
        "model", System.getenv().getOrDefault("AX_VERTEX_MODEL", "gemini-3.5-flash")));
    Map<String, Object> out = client.chat(Map.of(
        "chat_prompt", List.of(Map.of("role", "user", "content", "Reply with the word ready."))));
    System.out.println(Json.stringify(out));
  }
}

Java Signature Constraints

Builds a constrained signature fluently and runs it with OpenAI.

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

Java

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

public final class SignatureConstraintsExample {
  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)));
  }

  public static void main(String[] args) throws Exception {
    AxSignature signature =
        Ax.f()
            .call()
            .input("requestText", Ax.f().string("Booking request").min(10).max(500))
            .input("contactEmail", Ax.f().string("Contact email").email())
            .output("partySize", Ax.f().number("Guests").min(1).max(12))
            .output(
                "bookingCode",
                Ax.f()
                    .string("Three letters, a dash, and four digits")
                    .regex("^[A-Z]{3}-\\d{4}$", "Must look like ABC-1234"))
            .output(
                "guestProfile",
                Ax.f()
                    .object(
                        Map.of(
                            "fullName", Ax.f().string("Primary guest").min(2),
                            "dietaryNotes",
                                Ax.f().string("Dietary requirements").optional())))
            .build();
    Map<String, Object> output =
        Ax.ax(signature)
            .forward(
                client(),
                Map.of(
                    "requestText",
                    "Book dinner for four people under the name Ada Lovelace.",
                    "contactEmail",
                    "ada@example.com"));
    System.out.println(Json.stringify(output));
  }
}

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 -- java src/examples/java/generation/UsageObserverExample.java
Source: src/examples/java/generation/UsageObserverExample.java

Java

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

public final class UsageObserverExample {
  public static void main(String[] args) throws Exception {
    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.");
    }

    List<AxUsageEvent> events = new ArrayList<>();
    AxGlobals.setUsageObserver(events::add);
    OpenAICompatibleClient client =
        new OpenAICompatibleClient(
            Map.of(
                "api_key", apiKey,
                "model", System.getenv().getOrDefault("AX_OPENAI_MODEL", "gpt-5.4-mini"),
                "usageContext",
                    Map.of(
                        "tenantId", "tenant-42",
                        "feature", "support-chat",
                        "attributes", Map.of("environment", "example"))));
    try {
      client.chat(
          Map.of(
              "chat_prompt",
              List.of(Map.of("role", "user", "content", "Reply with one short greeting."))),
          Map.of(
              "usageContext",
              Map.of("userId", "user-7", "requestId", UUID.randomUUID().toString())));
      System.out.println(Json.stringify(events.stream().map(AxUsageEvent::value).toList()));
    } finally {
      AxGlobals.setUsageObserver(null);
    }
  }
}

Java Incremental Provider Stream

Consumes a lazy, closeable OpenAI SSE stream event by event.

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

Java

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

public final class ProviderStreamExample {
  public static void main(String[] args) throws Exception {
    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.");
    AxAIService client = Ax.ai("openai", Map.of(
      "api_key", apiKey,
      "model", System.getenv().getOrDefault("AX_OPENAI_MODEL", "gpt-5.6-luna")
    ));
    long started = System.nanoTime();
    try (AxChatStream stream = client.openStream(Map.of(
      "chat_prompt", List.of(Map.of("role", "user", "content", "Reply with exactly: streaming works")),
      "model_config", Map.of("temperature", 1)
    ))) {
      for (Map<String, Object> event : stream) {
        List<?> results = (List<?>) event.get("results");
        Object content = results.isEmpty() ? null : ((Map<?, ?>) results.get(0)).get("content");
        if (content != null && !content.toString().isEmpty()) {
          System.out.printf("[%d ms] %s", (System.nanoTime() - started) / 1_000_000, content);
        }
      }
    }
    System.out.println();
  }
}

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

Java

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

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

  public static void main(String[] args) throws Exception {
    GoogleGeminiClient client = new GoogleGeminiClient(Map.of(
        "api_key", apiKey(),
        "model", System.getenv().getOrDefault("AX_GEMINI_MODEL", "gemini-3.7-flash")));
    Map<String, Object> out = client.chat(Map.of(
        "chat_prompt", List.of(Map.of(
            "role", "user",
            "content", "Explain in one sentence why batch evaluations save time."))),
        Map.of("service_tier", "flex"));
    System.out.println(Json.stringify(out));
  }
}

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

Java

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

public final class ContextGenerationExample {
  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)));
  }

  public static void main(String[] args) throws Exception {
    AxGen program = Ax.ax("context:string, question:string -> answer:string, citations:string[]");
    Map<String, Object> output = program.forward(client(), Map.of("context", "Ax uses signatures, ai(), ax(), agent(), flow(), and optimize().", "question", "How should a new developer think about Ax?"));
    System.out.println(Json.stringify(output));
  }
}

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

Java

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

public final class AdaptiveBalancerExample {
  static String requiredKey() {
    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 {
    String key = requiredKey();
    String model = System.getenv().getOrDefault("AX_OPENAI_MODEL", "gpt-5.4-mini");
    List<AxAIService> services = List.of(
        new OpenAICompatibleClient(Map.of("api_key", key, "model", model, "base_url", System.getenv().getOrDefault("OPENAI_PRIMARY_BASE_URL", "https://api.openai.com/v1"))),
        new OpenAICompatibleClient(Map.of("api_key", System.getenv().getOrDefault("OPENAI_BACKUP_API_KEY", key), "model", model, "base_url", System.getenv().getOrDefault("OPENAI_BACKUP_BASE_URL", "https://api.openai.com/v1"))));

    var store = new AxInMemoryBalancerStatsStore();
    List<String> routeKeys = List.of("openai-primary", "openai-backup");
    List<String> events = new ArrayList<>();
    var strategy = new AxBalancerAdaptiveStrategy(6_000, 0.02)
        .expectedTokens(1_200, 300)
        .namespace("support-summary-v1")
        .routeKey((service, index) -> routeKeys.get(index))
        .slice(context -> context.get("options") instanceof Map<?, ?> options && Boolean.TRUE.equals(options.get("stream")) ? "streaming" : "interactive")
        .statsStore(store)
        .onRoutingEvent(event -> events.add(event.type()));
    AxBalancer balancer = new AxBalancer(services, new AxBalancerOptions().strategy(strategy));
    Map<String, Object> response = balancer.chat(Map.of("model", model, "chat_prompt", List.of(Map.of("role", "user", "content", "Summarize why shared routing state matters."))));
    System.out.println(Json.stringify(response));
    System.out.println(events);
  }
}

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 -- java src/examples/java/generation/RuntimeHooksExample.java
Source: src/examples/java/generation/RuntimeHooksExample.java

Java

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

public final class RuntimeHooksExample {
  static final class LogSpan implements AxSpan {
    private final String name;
    LogSpan(String name) { this.name = name; System.out.println("[span:start] " + name); }
    public void setAttributes(Map<String, Object> attributes) {}
    public void addEvent(String event, Map<String, Object> attributes) { System.out.println("[span:event] " + name + " " + event); }
    public void recordException(Throwable error) { System.out.println("[span:error] " + name + " " + error); }
    public void setStatus(String status, String description) {}
    public void end() { System.out.println("[span:end] " + name); }
  }

  static final class LogMeter implements AxMeter {
    public AxCounter createCounter(String name, AxMetricInstrumentOptions options) {
      return (value, attributes) -> System.out.println("[metric] " + name + " += " + value);
    }
    public AxHistogram createHistogram(String name, AxMetricInstrumentOptions options) {
      return (value, attributes) -> System.out.println("[metric] " + name + " = " + value);
    }
    public AxGauge createGauge(String name, AxMetricInstrumentOptions options) {
      return (value, attributes) -> System.out.println("[metric] " + name + " = " + value);
    }
  }

  static AxRateLimiter limiter(String label) {
    return (next, info) -> {
      System.out.printf("[limit:%s] %s %s/%s stream=%s%n", label, info.operation(), info.provider(), info.model(), info.streaming());
      return next.execute();
    };
  }

  public static void main(String[] args) throws Exception {
    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.");
    OpenAICompatibleClient client = 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)));
    AxTracer tracer = start -> new LogSpan(start.name());
    AxMeter meter = new LogMeter();
    AxRuntimeHooks overrideHooks = new AxRuntimeHooks(limiter("forward"), tracer, meter);

    AxGlobals.setRateLimiter(limiter("global"));
    AxGlobals.setTracer(tracer);
    AxGlobals.setMeter(meter);
    try {
      System.out.println(Ax.ax("topic:string -> summary:string").forward(client, Map.of("topic", "portable Ax runtime hooks")));
      AxAgent helper = Ax.agent("question:string -> answer:string", Map.of());
      try (AxQuickJsCodeRuntime runtime = new AxQuickJsCodeRuntime()) {
        System.out.println(helper.forward(client, Map.of("question", "What does a rate limiter wrap?"), Map.of("runtime", runtime, "max_actor_steps", 12), overrideHooks));
      }
      AxFlow workflow = Ax.flow(Map.of("id", "examples.runtimeHooks"))
          .execute("outline", Ax.ax("topic:string -> outline:string"))
          .execute("polish", Ax.ax("outline:string -> answer:string"))
          .returns(Map.of("answer", "polish"));
      System.out.println(workflow.forward(client, Map.of("topic", "Ax runtime hooks"), Map.of(), overrideHooks));
    } finally {
      AxGlobals.setRateLimiter(null);
      AxGlobals.setTracer(null);
      AxGlobals.setMeter(null);
    }
  }
}