feat: add AICONF config types & LDAIClient retrieval methods (AIC-2663)

Implement the public AI Config types and the LDAIClient retrieval methods that
evaluate a flag, validate its mode, interpolate prompt templates, and return a
typed config.

Config types follow the .NET-style two-hierarchy design (AIConfig /
AIConfigDefault bases): AICompletionConfig(+messages), AIAgentConfig
(+instructions), AIJudgeConfig(+evaluationMetricKey) results plus parallel
*Default builder types (a generic base builder keeps the defaults DRY), and
AIAgentConfigRequest for batch agent retrieval.

LDAIClientImpl mirrors the JS reference the spec points to:
- serialize the caller default to a flag value (with the requested mode) and
  pass it through jsonValueVariation, so an absent flag yields the default and
  the eval event records the correct default;
- validate mode: a mismatch logs a single warning and returns a disabled config
  of the requested type (never a config that would NPE the caller);
- interpolate messages/instructions via the vendored-Mustache Interpolator,
  exposing the context as {{ldctx}};
- fire the spec'd usage events ($ld:ai:usage:completion-config, :agent-config,
  :agent-configs, :judge-config) and emit $ld:ai:sdk:info once at construction,
  guarded so an uninitialized client can't throw from the constructor.

Design decisions (documented in the PR):
- Synchronous API (no CompletableFuture): matches the core Java server SDK and
  avoids Android-API/threading concerns; variation is in-memory post-init so
  agentConfigs fan-out parallelism buys ~nothing.
- No per-field merge of missing fields from the default (matches JS).
- Tracking is deferred to Step 4 (AIC-2664): LDAIConfigTracker is a placeholder
  interface with an internal no-op; configs expose createTracker() so Step 4
  fills in behavior without reshaping the public types.

Adds LDValueConverter.fromJavaObject (inverse conversion for default
serialization). LDAIClientImplTest covers usage events, typed retrieval,
interpolation/ldctx, mode-mismatch, default semantics, and agentConfigs.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ctawiah

lib/sdk/server-ai/README.md

@@ -18,8 +18,33 @@ This library has a minimum Java version of 8.
 This module is part of the [`java-core`](https://github.com/launchdarkly/java-core) monorepo and is
 published to Maven Central as `com.launchdarkly:launchdarkly-java-server-sdk-ai`.
 
-Full usage documentation, including AI Config retrieval, tracking, and manual judge evaluation, will be
-added as the SDK is built out (see epic AIC-2629).
+Construct an `LDAIClient` from an initialized server-side `LDClient`, then retrieve a typed config:
+
+```java
+LDClient ldClient = new LDClient(sdkKey);
+LDAIClient aiClient = new LDAIClientImpl(ldClient);
+
+Map<String, Object> variables = new HashMap<>();
+variables.put("username", "Sandy");
+
+AICompletionConfig config = aiClient.completionConfig(
+    "my-ai-config-key",
+    context,
+    AICompletionConfigDefault.disabled(), // fallback when the flag is absent
+    variables);
+
+if (config.isEnabled()) {
+    // config.getModel(), config.getProvider(), and config.getMessages() (already interpolated)
+    // are ready to pass to your model provider.
+}
+```
+
+The companion `agentConfig`/`agentConfigs` and `judgeConfig` methods retrieve agent and judge
+configs respectively. Within a prompt message or agent instruction, the evaluation context is
+available as `{{ldctx}}` (for example `{{ldctx.key}}`).
+
+Metric tracking and manual judge evaluation will be added as the SDK is built out (see epic
+AIC-2629).
 
 ## Internal API convention
 

lib/sdk/server-ai/src/main/java/com/launchdarkly/sdk/server/ai/AIAgentConfig.java

@@ -0,0 +1,66 @@
+package com.launchdarkly.sdk.server.ai;
+
+import com.launchdarkly.sdk.server.ai.datamodel.AIConfigMode;
+import com.launchdarkly.sdk.server.ai.datamodel.JudgeConfiguration;
+import com.launchdarkly.sdk.server.ai.datamodel.ModelConfig;
+import com.launchdarkly.sdk.server.ai.datamodel.ProviderConfig;
+import com.launchdarkly.sdk.server.ai.datamodel.ToolConfig;
+
+import java.util.Collections;
+import java.util.Map;
+import java.util.function.Supplier;
+
+/**
+ * A retrieved agent AI Config. This is the result of {@link LDAIClient#agentConfig} (and each entry
+ * returned by {@link LDAIClient#agentConfigs}).
+ * <p>
+ * The {@link #getInstructions() instructions} have already had their template interpolated with the
+ * supplied variables and evaluation context. Instances are immutable.
+ */
+public final class AIAgentConfig extends AIConfig {
+  private final String instructions;
+  private final JudgeConfiguration judgeConfiguration;
+  private final Map<String, ToolConfig> tools;
+
+  AIAgentConfig(
+      String key,
+      boolean enabled,
+      ModelConfig model,
+      ProviderConfig provider,
+      String instructions,
+      JudgeConfiguration judgeConfiguration,
+      Map<String, ToolConfig> tools,
+      Supplier<LDAIConfigTracker> trackerFactory) {
+    super(key, enabled, AIConfigMode.AGENT, model, provider, trackerFactory);
+    this.instructions = instructions;
+    this.judgeConfiguration = judgeConfiguration;
+    this.tools = tools == null ? null : Collections.unmodifiableMap(tools);
+  }
+
+  /**
+   * Returns the interpolated agent instructions.
+   *
+   * @return the instructions, or {@code null} if none were specified
+   */
+  public String getInstructions() {
+    return instructions;
+  }
+
+  /**
+   * Returns the judge configuration referencing judges that may evaluate this config.
+   *
+   * @return the judge configuration, or {@code null} if none was specified
+   */
+  public JudgeConfiguration getJudgeConfiguration() {
+    return judgeConfiguration;
+  }
+
+  /**
+   * Returns the root-level tools map keyed by tool name.
+   *
+   * @return an unmodifiable map of tools, or {@code null} if none were specified
+   */
+  public Map<String, ToolConfig> getTools() {
+    return tools;
+  }
+}

lib/sdk/server-ai/src/main/java/com/launchdarkly/sdk/server/ai/AIAgentConfigDefault.java

@@ -0,0 +1,132 @@
+package com.launchdarkly.sdk.server.ai;
+
+import com.launchdarkly.sdk.server.ai.datamodel.JudgeConfiguration;
+import com.launchdarkly.sdk.server.ai.datamodel.ToolConfig;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * A caller-supplied default for {@link LDAIClient#agentConfig} (and {@link LDAIClient#agentConfigs}),
+ * returned (as an {@link AIAgentConfig}) when the flag is absent or cannot be evaluated.
+ * <p>
+ * Build instances with {@link #builder()}. Instances are immutable.
+ */
+public final class AIAgentConfigDefault extends AIConfigDefault {
+  private final String instructions;
+  private final JudgeConfiguration judgeConfiguration;
+  private final Map<String, ToolConfig> tools;
+
+  private AIAgentConfigDefault(Builder builder) {
+    super(builder);
+    this.instructions = builder.instructions;
+    this.judgeConfiguration = builder.judgeConfiguration;
+    this.tools = builder.tools == null
+        ? null : Collections.unmodifiableMap(new LinkedHashMap<>(builder.tools));
+  }
+
+  /**
+   * Returns the default agent instructions.
+   *
+   * @return the instructions, or {@code null} if none were specified
+   */
+  public String getInstructions() {
+    return instructions;
+  }
+
+  /**
+   * Returns the default judge configuration.
+   *
+   * @return the judge configuration, or {@code null} if none was specified
+   */
+  public JudgeConfiguration getJudgeConfiguration() {
+    return judgeConfiguration;
+  }
+
+  /**
+   * Returns the default root-level tools map.
+   *
+   * @return an unmodifiable map of tools, or {@code null} if none were specified
+   */
+  public Map<String, ToolConfig> getTools() {
+    return tools;
+  }
+
+  /**
+   * Creates a new builder.
+   *
+   * @return a new {@link Builder}
+   */
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  /**
+   * Returns a disabled default, suitable as a fallback that causes callers to skip the model.
+   *
+   * @return a disabled {@link AIAgentConfigDefault}
+   */
+  public static AIAgentConfigDefault disabled() {
+    return builder().enabled(false).build();
+  }
+
+  /**
+   * Builder for {@link AIAgentConfigDefault}.
+   */
+  public static final class Builder extends AbstractBuilder<Builder> {
+    private String instructions;
+    private JudgeConfiguration judgeConfiguration;
+    private Map<String, ToolConfig> tools;
+
+    private Builder() {
+    }
+
+    @Override
+    protected Builder self() {
+      return this;
+    }
+
+    /**
+     * Sets the default agent instructions.
+     *
+     * @param instructions the instructions; may be {@code null}
+     * @return this builder
+     */
+    public Builder instructions(String instructions) {
+      this.instructions = instructions;
+      return this;
+    }
+
+    /**
+     * Sets the default judge configuration.
+     *
+     * @param judgeConfiguration the judge configuration; may be {@code null}
+     * @return this builder
+     */
+    public Builder judgeConfiguration(JudgeConfiguration judgeConfiguration) {
+      this.judgeConfiguration = judgeConfiguration;
+      return this;
+    }
+
+    /**
+     * Sets the default root-level tools map. The map is copied defensively.
+     *
+     * @param tools the tools; may be {@code null}
+     * @return this builder
+     */
+    public Builder tools(Map<String, ToolConfig> tools) {
+      this.tools = tools;
+      return this;
+    }
+
+    /**
+     * Builds the immutable {@link AIAgentConfigDefault}.
+     *
+     * @return a new {@link AIAgentConfigDefault}
+     */
+    public AIAgentConfigDefault build() {
+      return new AIAgentConfigDefault(this);
+    }
+  }
+}

lib/sdk/server-ai/src/main/java/com/launchdarkly/sdk/server/ai/AIAgentConfigRequest.java

@@ -0,0 +1,107 @@
+package com.launchdarkly.sdk.server.ai;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * A single agent request passed to {@link LDAIClient#agentConfigs}, pairing an agent key with its
+ * own default and interpolation variables.
+ * <p>
+ * Build instances with {@link #builder(String)}. Instances are immutable.
+ */
+public final class AIAgentConfigRequest {
+  private final String key;
+  private final AIAgentConfigDefault defaultValue;
+  private final Map<String, Object> variables;
+
+  private AIAgentConfigRequest(Builder builder) {
+    this.key = builder.key;
+    this.defaultValue = builder.defaultValue;
+    this.variables = builder.variables == null
+        ? null : Collections.unmodifiableMap(new HashMap<>(builder.variables));
+  }
+
+  /**
+   * Returns the agent key to retrieve.
+   *
+   * @return the agent key, never {@code null}
+   */
+  public String getKey() {
+    return key;
+  }
+
+  /**
+   * Returns the default for this agent.
+   *
+   * @return the default, or {@code null} if a disabled default should be used
+   */
+  public AIAgentConfigDefault getDefaultValue() {
+    return defaultValue;
+  }
+
+  /**
+   * Returns the interpolation variables for this agent's instructions.
+   *
+   * @return an unmodifiable map of variables, or {@code null} if none were specified
+   */
+  public Map<String, Object> getVariables() {
+    return variables;
+  }
+
+  /**
+   * Creates a new builder for a request with the given agent key.
+   *
+   * @param key the agent key; must not be {@code null}
+   * @return a new {@link Builder}
+   * @throws NullPointerException if {@code key} is {@code null}
+   */
+  public static Builder builder(String key) {
+    return new Builder(Objects.requireNonNull(key, "key"));
+  }
+
+  /**
+   * Builder for {@link AIAgentConfigRequest}.
+   */
+  public static final class Builder {
+    private final String key;
+    private AIAgentConfigDefault defaultValue;
+    private Map<String, Object> variables;
+
+    private Builder(String key) {
+      this.key = key;
+    }
+
+    /**
+     * Sets the default for this agent.
+     *
+     * @param defaultValue the default; may be {@code null}
+     * @return this builder
+     */
+    public Builder defaultValue(AIAgentConfigDefault defaultValue) {
+      this.defaultValue = defaultValue;
+      return this;
+    }
+
+    /**
+     * Sets the interpolation variables for this agent's instructions. The map is copied defensively.
+     *
+     * @param variables the variables; may be {@code null}
+     * @return this builder
+     */
+    public Builder variables(Map<String, Object> variables) {
+      this.variables = variables;
+      return this;
+    }
+
+    /**
+     * Builds the immutable {@link AIAgentConfigRequest}.
+     *
+     * @return a new {@link AIAgentConfigRequest}
+     */
+    public AIAgentConfigRequest build() {
+      return new AIAgentConfigRequest(this);
+    }
+  }
+}