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

[ctawiah]

Requirements

• I have added test coverage for new or changed functionality
• I have followed the repository's pull request submission guidelines
• I have validated my changes against all supported platform versions

Related issues

AIC-2663 — Step 3: AICONF config types & LDAIClient methods. Part of epic AIC-2629.

Stacked on #172 (feat/AIC-2695/ai-sdk-vendor-mustache), which is stacked on #171. It builds on the data model + parser (#171) and the vendored-Mustache Interpolator (#172). Base retargets up the stack as each merges.

Describe the solution you've provided

Implements 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. The behavior mirrors the JS reference the spec points to.

• Config types — .NET-style two-hierarchy design (AIConfig / AIConfigDefault bases): AICompletionConfig(+messages), AIAgentConfig(+instructions), AIJudgeConfig(+evaluationMetricKey) result types plus parallel *Default builder types, and AIAgentConfigRequest for batch agent retrieval. A generic base builder keeps the *Default builders DRY.
• LDAIClient methods — completionConfig, agentConfig, agentConfigs, judgeConfig:
  • serialize the caller default to a flag value (tagged with the requested mode) and pass it through jsonValueVariation, so an absent flag yields the default and the eval event records the correct default;
  • mode validation: 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.
• evaluationMetricKey resolves to the first non-blank entry (handled by the feat: AgentControl data model, parsing & interpolation (AIC-2662) #171 parser).

Key decisions

• Synchronous API (no CompletableFuture). Matches the core Java server SDK's blocking style and sidesteps Android API-level/threading concerns. variation is in-memory after init, so agentConfigs fan-out parallelism buys ~nothing while adding real complexity. Resolves the ticket's async-surface question.
• No per-field merge of missing model/provider/instructions from the default (matches JS).
• Tracking 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 config types.
• Construction: new LDAIClientImpl(ldClient) (interface LDAIClient is provided for mocking/DI). A second constructor accepts an LDLogger.

Thread-safety — LDAIClientImpl holds only the thread-safe base client, a logger, and one shared Interpolator (thread-safe template cache); every returned config is immutable.

Tests — LDAIClientImplTest (17 cases) covers usage events, SDK-info emission + constructor guard, typed retrieval, interpolation/ldctx, mode-mismatch (disabled + single warning, no NPE), default semantics (absent → default; no per-field merge), and agentConfigs ordering/count. LDValueConverterTest extended for the new inverse conversion. ./gradlew clean build green (checkstyle + Javadoc + all tests).

Describe alternatives you've considered

• Single unified config type (default == result) — rejected; the ticket and sibling SDKs intentionally separate the caller-supplied default from the retrieved result (which carries the key + tracker + interpolated content).
• Async CompletableFuture surface — rejected for a server SDK (see decision above).

Additional context

AISdkInfo.VERSION is currently a constant kept in step with gradle.properties; wiring it to a generated/build-time version can be a follow-up.

Made with Cursor

---

Note

Medium Risk
New public SDK API on the flag-evaluation path; incorrect defaults, mode handling, or interpolation would affect how apps load AI configs in production, though scope is additive with guarded telemetry.

Overview
Adds the public AI Config retrieval surface for the Java server AI SDK: immutable AICompletionConfig, AIAgentConfig, and AIJudgeConfig types (plus matching *Default builders and AIAgentConfigRequest for batch agents), wired through LDAIClient / LDAIClientImpl.

LDAIClientImpl evaluates flags via jsonValueVariation with a null sentinel, parses variations, validates mode (mismatch → disabled config + warning), and interpolates messages/instructions (including {{ldctx}}). Absent flags return the caller default with interpolation and no per-field merge from defaults when a variation is present. It emits $ld:ai:sdk:info at construction (failure-safe) and $ld:ai:usage:* metrics per method; LDAIConfigTracker is a placeholder with a no-op implementation until a later step.

The README now documents constructing LDAIClientImpl from LDClient and calling completionConfig. LDAIClientImplTest covers usage events, interpolation, mode mismatch, default semantics, and ordered agentConfigs.

^{Reviewed by Cursor Bugbot for commit ac6b827. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ac6b827. Configure here.}

[cursor]

Eval events ignore caller defaults

Medium Severity

evaluate always passes LDValue.ofNull() into jsonValueVariation, but the server SDK attaches that argument to flag evaluation events as the recorded fallback default. Callers still receive their typed *Default via buildConfigFromDefault, so runtime behavior can be correct while every AI config evaluation is attributed with a null default instead of the serialized default (with the requested mode) described for this step.

 

^{Reviewed by Cursor Bugbot for commit ac6b827. Configure here.}