Convert Android LLM extension from Java to Kotlin (#19211)

[kirklandsign]

Summary:

Convert LlmModule, LlmCallback, LlmGenerationConfig, and LlmModuleConfig
from Java to Kotlin while preserving all public API signatures and JNI
compatibility.

Key changes:

• Use Kotlin idioms: external fun for native methods, companion object
  for static members, require() for validation, apply {} in Builders
• Preserve HybridData/fbjni pattern with DoNotStrip and JvmStatic
• Add JvmName annotations for boolean getters (isEcho, isWarming) to
  maintain Java source compatibility
• Keep all constructor overloads as secondary constructors for backward
  compatibility with Java callers (e.g., benchmark LlmModelRunner)
• Update BUCK target language from JAVA to KOTLIN
• Remove package-info.java (no Kotlin equivalent needed)

Reviewed By: psiddh

Differential Revision: D102880053

[pytorch-bot]

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/19211

• 📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

❌ 1 New Failure, 2 Unrelated Failures, 1 Unclassified Failure

As of commit d075546 with merge base ec76470 ():

NEW FAILURE - The following job has failed:

• pull / test-parakeet-xnnpack-linux / linux-job (gh)
  RuntimeError: Command docker exec -t 393ad7e2a73573a55dced4d11b98e588cff87858fcbbefbd5147c000b1357432 /exec failed with exit code 1

UNCLASSIFIED FAILURE - DrCI could not classify the following job because the workflow did not run on the merge base. The failure may be pre-existing on trunk or introduced by this PR:

• Check Labels / Check labels (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
  RuntimeError: GraphQL query

BROKEN TRUNK - The following jobs failed but were present on the merge base:

👉 Rebase onto the `viable/strict` branch to avoid these failures

• pull / unittest / macos / macos-job (gh) (trunk failure)
  ##[error]The operation was canceled.
• pull / unittest-editable / macos / macos-job (gh) (trunk failure)
  ##[error]The operation was canceled.

This comment was automatically generated by Dr. CI and updates every 15 minutes.

[meta-codesync]

@kirklandsign has exported this pull request. If you are a Meta employee, you can view the originating Diff in D102880053.

[github-actions]

This PR needs a release notes: label

If your change should be included in the release notes (i.e. would users of this library care about this change?), please use a label starting with release notes:. This helps us keep track and include your important work in the next release notes.

To add a label, you can comment to pytorchbot, for example
@pytorchbot label "release notes: none"

For more information, see
https://github.com/pytorch/pytorch/wiki/PyTorch-AutoLabel-Bot#why-categorize-for-release-notes-and-how-does-it-work.

[Copilot]

Pull request overview

Converts the Android LLM extension surface area from Java to Kotlin while aiming to preserve the existing public API and JNI/fbjni HybridData integration.

Changes:

• Replaced Java implementations of LlmModule, LlmModuleConfig, and LlmGenerationConfig with Kotlin equivalents.
• Updated LlmCallback to Kotlin and adjusted BUCK to compile the target as Kotlin sources.
• Preserved the HybridData init pattern and external/native method declarations for JNI compatibility.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
extension/android/executorch_android/src/main/java/org/pytorch/executorch/extension/llm/LlmModule.kt	Kotlin port of the LLM module wrapper and JNI entrypoints.
extension/android/executorch_android/src/main/java/org/pytorch/executorch/extension/llm/LlmModule.java	Removed Java version after Kotlin conversion.
extension/android/executorch_android/src/main/java/org/pytorch/executorch/extension/llm/LlmModuleConfig.kt	Kotlin port of module initialization configuration + builder.
extension/android/executorch_android/src/main/java/org/pytorch/executorch/extension/llm/LlmModuleConfig.java	Removed Java version after Kotlin conversion.
extension/android/executorch_android/src/main/java/org/pytorch/executorch/extension/llm/LlmGenerationConfig.kt	Kotlin port of generation configuration + builder with Java getter name compatibility.
extension/android/executorch_android/src/main/java/org/pytorch/executorch/extension/llm/LlmGenerationConfig.java	Removed Java version after Kotlin conversion.
extension/android/executorch_android/src/main/java/org/pytorch/executorch/extension/llm/LlmCallback.kt	Kotlin port of callback interface for generation results/stats/errors.
extension/android/BUCK	Switches the LLM extension BUCK target from Java to Kotlin sources.

Comments suppressed due to low confidence (1)

extension/android/executorch_android/src/main/java/org/pytorch/executorch/extension/llm/LlmCallback.kt:46

• onStats / onError are declared with Kotlin interface method bodies. Unless the module is compiled with Kotlin JVM default methods enabled (e.g., -Xjvm-default=all or all-compatibility), these will be emitted via DefaultImpls and will still be abstract to Java callers—breaking existing Java implementers that previously relied on Java-8 default methods (e.g., code that only overrides onResult). To preserve Java source/binary compatibility, either enable JVM default mode for this Android library and/or use @JvmDefaultWithCompatibility on these methods, or keep LlmCallback as a Java interface with real default methods.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Same issue here: image.remaining() is an Int but expectedBytes is a Long, so image.remaining() >= expectedBytes won’t compile. After you’ve ensured the computed byte count is within Int range, cast once and do all remaining comparisons using the same type.

[Copilot]

This require(...) mixes Long (expectedBytes) with Int (Int.MAX_VALUE, image.remaining()), which won’t compile in Kotlin because numeric types aren’t implicitly converted. Convert the Int values to Long (e.g., Int.MAX_VALUE.toLong() / image.remaining().toLong()) or cast expectedBytes to Int after the bounds check and compare as Int.

Suggested change

	expectedBytes <= Int.MAX_VALUE &&
	image.remaining() >= expectedBytes) {
	expectedBytes <= Int.MAX_VALUE.toLong() &&
	image.remaining().toLong() >= expectedBytes) {

[kirklandsign]

@claude review

[kirklandsign]

@claude review

[claude]

Claude finished @kirklandsign's task in 3m 30s —— View job

---

Review: Convert Android LLM extension from Java to Kotlin

• Read changed files and understand the conversion
• Check for type safety issues (Long/Int mixing flagged by Copilot)
• Verify JNI compatibility and API preservation
• Check Kotlin idiom usage and backward compatibility
• Post review feedback

---

Overall this is a clean conversion that preserves the public API surface well. Good use of Kotlin idioms (external fun, companion object with const val, require(), apply {} in Builders, listOfNotNull). The @JvmName annotations for boolean getters and @JvmStatic on create() methods ensure Java source compatibility.

I have two concerns — one potentially blocking and one worth investigating:

---

Issue 1: Int vs Long comparison in require() (potential compilation failure)

LlmModule.kt:361-362 and LlmModule.kt:413

Kotlin does not implicitly widen Int to Long for comparisons the way Java does. The require block mixes types:

expectedBytes <= Int.MAX_VALUE &&          // Long <= Int
image.remaining() >= expectedBytes         // Int >= Long

In the original Java, this worked via implicit widening. In Kotlin, these comparisons will fail to compile. Fix:

expectedBytes <= Int.MAX_VALUE.toLong() &&
image.remaining().toLong() >= expectedBytes

Same pattern applies in prefillNormalizedImage at line 413:

image.remaining() >= expectedBytes   // Int >= Long

should become image.remaining().toLong() >= expectedBytes.

Fix this →

---

Issue 2: Kotlin interface default methods and Java caller compatibility

LlmCallback.kt:37,46 — onStats and onError have default (empty) bodies.

The build.gradle kotlinOptions block only sets jvmTarget = "11" without -Xjvm-default=all:

kotlinOptions {
    jvmTarget = "11"
}

With Kotlin 1.9.x (used in this project), interface default method bodies are still compiled using the DefaultImpls pattern by default — meaning they appear abstract to Java callers. The existing Java caller extension/benchmark/android/benchmark/app/src/main/java/org/pytorch/minibench/LlmModelRunner.java implements LlmCallback and does NOT override onError, which would cause a compilation error.

Recommended fix — add to kotlinOptions in executorch_android/build.gradle:

kotlinOptions {
    jvmTarget = "11"
    freeCompilerArgs += ["-Xjvm-default=all"]
}

This will emit proper JVM default methods instead of DefaultImpls, matching the original Java interface behavior.

Alternatively, for the BUCK build, ensure the equivalent Kotlin compiler arg is passed. (Meta's internal build may handle this differently.)

---

Minor observations (non-blocking)

1. LlmModule.kt:41-42: The requireNotNull calls happen before validateFilePath, which means a null path throws IllegalArgumentException("model path must not be null") rather than whatever validateFilePath would throw. This is fine and arguably better than the original Java which would NPE inside validateFilePath.

2. Constants accessibility from Java ✓ — const val in companion objects correctly compiles to public static final fields, so LlmModule.MODEL_TYPE_TEXT and LlmModuleConfig.LOAD_MODE_MMAP remain directly accessible.

3. Constructor overloads ✓ — All secondary constructors properly delegate to the primary private constructor, preserving backward compat with Java callers like LlmModelRunner.

4. JNI compatibility ✓ — external fun generates the same JNI method names as Java native. The @DoNotStrip + @JvmStatic on initHybrid in the companion object preserves the fbjni HybridData pattern.

5. LlmModuleConfig.Builder fields are internal — this means they're visible within the same Kotlin module but not from Java. The original Java used package-private. If any Java code in the same package accessed builder fields directly (unlikely given the builder pattern), this could break. Probably fine for this codebase.

---

Summary

The conversion is well-executed. The two issues above (Int/Long comparisons and interface default method compilation) should be verified — if the internal Meta build passes, it may be that their Kotlin compiler configuration handles both (via different Kotlin version or compiler flags). But for OSS Gradle builds, both are likely problems.

---

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (2)

extension/android/executorch_android/src/main/java/org/pytorch/executorch/extension/llm/LlmCallback.kt:47

• LlmCallback previously provided Java 8 default methods for onStats/onError, so Java callers could implement only onResult. In Kotlin, interface methods with bodies will not become Java default methods unless the module is compiled with -Xjvm-default (e.g. all-compatibility), so this likely breaks Java source compatibility. Consider enabling -Xjvm-default=all-compatibility for this module (Gradle + Buck) or reverting LlmCallback to a Java interface / providing a Java-friendly adapter that preserves optional overrides.
  extension/android/executorch_android/src/main/java/org/pytorch/executorch/extension/llm/LlmCallback.kt:28
• The Android tests exercise LlmCallback from Kotlin, but the stated goal is Java source compatibility. Adding a small Java-side compilation/runtime test (e.g., a Java class implementing LlmCallback overriding only onResult) would catch regressions like missing Java default methods / incorrect nullability annotations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

In Java, LlmModule was non-final and had public constructors, so it was technically extensible/overridable by API consumers. Kotlin classes/methods are final by default, so this conversion makes the class non-extendable and methods non-overridable, which is a source-compatibility break for any downstream code that subclasses LlmModule. If preserving Java source compatibility is required, mark the class (and any intended-to-be-overridable methods) as open, or explicitly document/commit to it being non-inheritable and provide an alternative extension mechanism.

[Copilot]

PR description says package-info.java was removed, but org/pytorch/executorch/extension/llm/package-info.java still exists in this package. Either remove it as described, or update the PR description to avoid confusion about what changed.

[kirklandsign]

@claude review

[claude]

Claude finished @kirklandsign's task in 2m 1s —— View job

---

Review: Convert Android LLM extension from Java to Kotlin (#19211)

• Read changed files and understand the conversion
• Check for type safety issues (Int/Long mixing)
• Verify JNI compatibility and API preservation
• Check Kotlin idiom usage and backward compatibility
• Check interface default method compatibility
• Post review feedback

---

Overall this is a solid, well-executed conversion. The Kotlin idioms are used appropriately (external fun, companion object with const val, require(), apply {} in Builders, listOfNotNull). The @JvmName annotations for boolean getters and @JvmStatic on initHybrid/create() ensure Java caller compatibility. The Int/Long comparisons in the require() blocks (lines 576-577, 639) correctly use .toLong() conversions — this was flagged in the earlier review but appears already addressed in the current code.

Two concerns remain — one potentially blocking:

---

Issue 1 (Medium): Kotlin interface default methods and Java callers

LlmCallback.kt:37,46 — onStats and onError have default (empty) bodies.

The Gradle build uses Kotlin 1.9.23 (from libs.versions.toml) and the kotlinOptions block in executorch_android/build.gradle:52-54 only sets jvmTarget = "11" without -Xjvm-default=all:

kotlinOptions {
    jvmTarget = "11"
}

With Kotlin 1.9.x, interface methods with bodies are compiled using the DefaultImpls companion pattern by default — these appear abstract to Java callers. The existing Java caller LlmModelRunner.java (extension/benchmark/android/benchmark/app/src/main/java/org/pytorch/minibench/LlmModelRunner.java:20) implements LlmCallback and does NOT override onError, which would cause a compilation error.

Recommended fix — add -Xjvm-default=all to kotlinOptions in executorch_android/build.gradle:

kotlinOptions {
    jvmTarget = "11"
    freeCompilerArgs += ["-Xjvm-default=all"]
}

This emits proper JVM default methods matching the original Java interface behavior. For the BUCK build, ensure the equivalent Kotlin compiler arg is passed (Meta's internal build may handle this differently).

Fix this →

---

Issue 2 (Low): Class finality — API surface change

LlmModule.kt:28 — The original Java class was public class LlmModule (non-final, theoretically extensible). Kotlin classes are final by default, so this conversion makes LlmModule non-subclassable — a source-compatibility break for any downstream code that subclasses it.

Given that:

• The class is marked @Experimental
• The primary constructor is private
• Subclassing an fbjni HybridData-backed class is risky anyway

This is likely intentional and correct. But worth noting for the changelog — if any downstream consumer subclassed LlmModule, they'll need to adjust. If preserving extensibility is desired, mark the class as open.

---

Minor observations (non-blocking)

1. Builder field visibility — LlmModuleConfig.Builder fields are internal (Kotlin module-scoped) vs the original Java's package-private. Since the builder pattern exposes setters, this is fine — no caller should access fields directly.

2. LlmGenerationConfig constructor — The private constructor + Builder pattern is clean. @JvmStatic fun create(): Builder ensures Java callers can still do LlmGenerationConfig.create().echo(true).build().

3. Constants accessibility ✓ — const val in companion objects compiles to public static final fields. LlmModule.MODEL_TYPE_TEXT and LlmModuleConfig.LOAD_MODE_MMAP remain directly accessible from Java.

4. JNI compatibility ✓ — external fun generates the same JNI method signatures as Java native. The @DoNotStrip + @JvmStatic on initHybrid in the companion object preserves the fbjni HybridData pattern correctly.

5. Constructor overloads ✓ — All secondary constructors properly delegate to the primary private constructor. The LlmModelRunner.java line new LlmModule(mModelFilePath, mTokenizerFilePath, 0.8f) maps to the 3-arg (String, String, Float) constructor at line 148.

6. package-info.java deletion — Copilot flagged that PR description mentions this removal. The file appears in the diff as deleted (DELETED), which matches the description. No action needed.

---

Summary

The conversion is well-done. The main actionable item is Issue 1 (adding -Xjvm-default=all) to prevent breaking Java callers that rely on default method implementations in LlmCallback. Without this flag, the OSS Gradle build will likely fail when compiling LlmModelRunner.java.

---

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.