feat: add AI Config data model, defensive parsing & Mustache interpolation (AIC-2662)

Implements Step 2 of the Java AI SDK: the AICONF data model plus the
JSON-protocol parsing and interpolation layers. No client methods,
tracker, or evaluation are included (those are later steps).

Public data model (com.launchdarkly.sdk.server.ai.datamodel):
- LDMessage (role enum + content), ModelConfig, ProviderConfig,
  ToolConfig, JudgeConfiguration (+ nested Judge), AIConfigMode.
- Immutable, builder-based, documented public types.

Internal parsing/interpolation (com.launchdarkly.sdk.server.ai.internal):
- LDValueConverter: depth-capped LDValue -> plain Java tree. Integral
  numbers within +/-2^53 decode to Long, otherwise Double (precision
  beyond 2^53 is documented).
- AIConfigParser + AIConfigFlagValue: defensive LDValue -> typed parse.
  Malformed/wrong-typed fields never throw; tools fall back to
  model.parameters.tools[]; evaluationMetricKey resolves to the first
  non-blank of evaluationMetricKey / evaluationMetricKeys[].
- Interpolator: jmustache engine matching the JS/Python escaping policy
  (no HTML escaping, missing/null -> ""), with ldctx merged last so it
  overrides any caller-supplied ldctx, and a thread-safe compiled-template
  cache.

Build:
- Re-add the (now audited) com.samskivert:jmustache:1.16 dependency as
  implementation scope; flip javadoc failOnError back on now that public
  types exist.

Tests: 32 unit tests covering defensive parsing fallbacks, number/tool/
metric-key resolution, tri-state enabled, and interpolation parity
(escaping, missing-variable, ldctx-wins).

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

Author: ctawiah

lib/sdk/server-ai/build.gradle

@@ -44,10 +44,13 @@ ext {
 ext.versions = [
     // The *lowest* version of the base SDK we are compatible with. LDClientInterface
     // appears in this library's public signature, so it is exposed as an `api` dependency.
-    "sdk": "7.14.0"
-    // NOTE: a Mustache templating dependency (for AI Config message/instruction interpolation)
-    // will be added in a later step once it has been fully audited (license / maintenance /
-    // transitive deps). See AIC-2662.
+    "sdk": "7.14.0",
+    // jmustache: Mustache engine for AI Config message/instruction interpolation.
+    // Audit (AIC-2662): com.samskivert:jmustache 1.16 is BSD 2-Clause licensed, actively
+    // maintained, and ships as a single self-contained jar with no transitive runtime
+    // dependencies (verified via the published POM). Chosen over mustache.java / Handlebars.java
+    // for its zero-dependency footprint; HTML escaping is disabled to match the JS/Python SDKs.
+    "jmustache": "1.16"
 ]
 
 ext.libraries = [:]
@@ -56,6 +59,9 @@ dependencies {
     // Exposed on the public API surface (LDClientInterface), therefore `api` not `implementation`.
     api "com.launchdarkly:launchdarkly-java-server-sdk:${versions.sdk}"
 
+    // Mustache templating, kept as `implementation` so it is not leaked onto consumers' classpath.
+    implementation "com.samskivert:jmustache:${versions.jmustache}"
+
     testImplementation "org.hamcrest:hamcrest-all:1.3"
     testImplementation "junit:junit:4.13.2"
     testImplementation "org.mockito:mockito-core:3.12.4"
@@ -74,11 +80,6 @@ java {
 javadoc {
     // exclude internal implementation classes from the published API documentation
     exclude internalPackageGlob
-    // The foundation module (AIC-2661) intentionally ships no public types yet, only
-    // package-info.java. The javadoc tool reports "No public or protected classes found to
-    // document" in that state, so we tolerate it here. TODO(AIC-2662): set failOnError = true
-    // once the data-model public types land.
-    failOnError = false
     options {
         // suppress noisy "no comment" warnings; checkstyle enforces Javadoc on the public surface
         addStringOption('Xdoclint:all,-missing', '-quiet')

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

@@ -0,0 +1,57 @@
+package com.launchdarkly.sdk.server.ai.datamodel;
+
+/**
+ * The mode of an AI Config, as carried by the {@code _ldMeta.mode} field of a flag variation.
+ * <p>
+ * The mode determines which kind of configuration a variation represents and which retrieval
+ * method on the client it is valid for.
+ */
+public enum AIConfigMode {
+  /**
+   * A completion (chat/prompt) configuration. This is the default when no mode is present.
+   */
+  COMPLETION("completion"),
+
+  /**
+   * An agent configuration, which carries {@code instructions} instead of {@code messages}.
+   */
+  AGENT("agent"),
+
+  /**
+   * A judge configuration, used to evaluate the output of another configuration.
+   */
+  JUDGE("judge");
+
+  private final String wireValue;
+
+  AIConfigMode(String wireValue) {
+    this.wireValue = wireValue;
+  }
+
+  /**
+   * Returns the string used to represent this mode in the JSON protocol.
+   *
+   * @return the wire representation (for example {@code "completion"})
+   */
+  public String getWireValue() {
+    return wireValue;
+  }
+
+  /**
+   * Resolves a wire string to a mode.
+   *
+   * @param value the wire value, such as {@code "agent"}; may be {@code null}
+   * @return the matching mode, or {@code null} if the value is {@code null} or unrecognized
+   */
+  public static AIConfigMode fromWireValue(String value) {
+    if (value == null) {
+      return null;
+    }
+    for (AIConfigMode mode : values()) {
+      if (mode.wireValue.equals(value)) {
+        return mode;
+      }
+    }
+    return null;
+  }
+}

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

@@ -0,0 +1,121 @@
+package com.launchdarkly.sdk.server.ai.datamodel;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Configuration referencing the judges that may evaluate an AI Config.
+ * <p>
+ * This is parsed from the {@code judgeConfiguration} field of a flag variation and is visible on
+ * completion and agent configs. In v1.0 judges are invoked manually; the SDK does not auto-attach
+ * them. Instances are immutable.
+ */
+public final class JudgeConfiguration {
+  /**
+   * Configuration for a single judge attachment: which judge AI Config to use and how frequently
+   * to sample it.
+   * <p>
+   * Instances are immutable.
+   */
+  public static final class Judge {
+    private final String key;
+    private final double samplingRate;
+
+    /**
+     * Constructs a judge attachment.
+     *
+     * @param key the key of the judge AI Config; must not be {@code null}
+     * @param samplingRate the sampling rate, nominally in the range {@code 0.0}–{@code 1.0}
+     * @throws NullPointerException if {@code key} is {@code null}
+     */
+    public Judge(String key, double samplingRate) {
+      this.key = Objects.requireNonNull(key, "key");
+      this.samplingRate = samplingRate;
+    }
+
+    /**
+     * Returns the key of the judge AI Config.
+     *
+     * @return the judge key, never {@code null}
+     */
+    public String getKey() {
+      return key;
+    }
+
+    /**
+     * Returns the configured sampling rate.
+     *
+     * @return the sampling rate
+     */
+    public double getSamplingRate() {
+      return samplingRate;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+      if (this == o) {
+        return true;
+      }
+      if (!(o instanceof Judge)) {
+        return false;
+      }
+      Judge other = (Judge) o;
+      return Double.compare(samplingRate, other.samplingRate) == 0 && key.equals(other.key);
+    }
+
+    @Override
+    public int hashCode() {
+      return Objects.hash(key, samplingRate);
+    }
+
+    @Override
+    public String toString() {
+      return "Judge{key=" + key + ", samplingRate=" + samplingRate + '}';
+    }
+  }
+
+  private final List<Judge> judges;
+
+  /**
+   * Constructs a judge configuration.
+   *
+   * @param judges the judge attachments; may be {@code null}, treated as empty
+   */
+  public JudgeConfiguration(List<Judge> judges) {
+    this.judges = judges == null
+        ? Collections.<Judge>emptyList()
+        : Collections.unmodifiableList(new ArrayList<>(judges));
+  }
+
+  /**
+   * Returns the configured judge attachments as an unmodifiable list.
+   *
+   * @return the judges; never {@code null} (empty when none were specified)
+   */
+  public List<Judge> getJudges() {
+    return judges;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (!(o instanceof JudgeConfiguration)) {
+      return false;
+    }
+    return judges.equals(((JudgeConfiguration) o).judges);
+  }
+
+  @Override
+  public int hashCode() {
+    return judges.hashCode();
+  }
+
+  @Override
+  public String toString() {
+    return "JudgeConfiguration{judges=" + judges + '}';
+  }
+}

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

@@ -0,0 +1,130 @@
+package com.launchdarkly.sdk.server.ai.datamodel;
+
+import java.util.Objects;
+
+/**
+ * A single prompt message in an AI Config, consisting of a {@link Role} and string content.
+ * <p>
+ * Instances are immutable.
+ */
+public final class LDMessage {
+  /**
+   * The role of a {@link LDMessage}.
+   */
+  public enum Role {
+    /**
+     * A system message, typically used to set behavior or context.
+     */
+    SYSTEM("system"),
+
+    /**
+     * A message authored by the end user.
+     */
+    USER("user"),
+
+    /**
+     * A message authored by the assistant (model).
+     */
+    ASSISTANT("assistant");
+
+    private final String wireValue;
+
+    Role(String wireValue) {
+      this.wireValue = wireValue;
+    }
+
+    /**
+     * Returns the string used to represent this role in the JSON protocol.
+     *
+     * @return the wire representation (for example {@code "system"})
+     */
+    public String getWireValue() {
+      return wireValue;
+    }
+
+    /**
+     * Resolves a wire string to a role.
+     *
+     * @param value the wire value, such as {@code "user"}; may be {@code null}
+     * @return the matching role, or {@code null} if the value is {@code null} or unrecognized
+     */
+    public static Role fromWireValue(String value) {
+      if (value == null) {
+        return null;
+      }
+      for (Role role : values()) {
+        if (role.wireValue.equals(value)) {
+          return role;
+        }
+      }
+      return null;
+    }
+  }
+
+  private final Role role;
+  private final String content;
+
+  /**
+   * Constructs a message.
+   *
+   * @param role the role of the message; must not be {@code null}
+   * @param content the message content; must not be {@code null}
+   * @throws NullPointerException if {@code role} or {@code content} is {@code null}
+   */
+  public LDMessage(Role role, String content) {
+    this.role = Objects.requireNonNull(role, "role");
+    this.content = Objects.requireNonNull(content, "content");
+  }
+
+  /**
+   * Returns the role of this message.
+   *
+   * @return the role, never {@code null}
+   */
+  public Role getRole() {
+    return role;
+  }
+
+  /**
+   * Returns the content of this message.
+   *
+   * @return the content, never {@code null}
+   */
+  public String getContent() {
+    return content;
+  }
+
+  /**
+   * Returns a copy of this message with the given content, preserving the role.
+   * <p>
+   * Used by the interpolation layer to produce a rendered message without mutating the original.
+   *
+   * @param newContent the replacement content; must not be {@code null}
+   * @return a new {@link LDMessage}
+   */
+  public LDMessage withContent(String newContent) {
+    return new LDMessage(role, newContent);
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (!(o instanceof LDMessage)) {
+      return false;
+    }
+    LDMessage other = (LDMessage) o;
+    return role == other.role && content.equals(other.content);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(role, content);
+  }
+
+  @Override
+  public String toString() {
+    return "LDMessage{role=" + role + ", content=" + content + '}';
+  }
+}