fix(kotlin): stop deprecations pointing at deprecated replacements

[ayaangazali]

What is wrong

Six @Deprecated messages on the legacy extension surface tell the caller to move to a namespace method that is itself deprecated, so following the advice lands them on a second deprecation:

legacy extension	current advice	that target's own annotation
unloadModel	models.unload(category)	@Deprecated("Use unloadAll(category).")
stopSynthesis	tts.stop()	@Deprecated("Use the SpeechHandle returned by speak().")
stopSpeaking	tts.stop()	same
streamVAD	vad.detectStream(audio, options)	@Deprecated("Use vad.openStream(format, options).")
resetVAD	vad.detectStream	same
transcribeStream	stt.transcribeStream(audio, options)	@Deprecated("Use stt.openStream(format, options).")

The IDE shows the strikethrough and the message, the caller migrates, and gets struck through again. ReplaceWith is not involved in any of these, so nothing auto-applies, but the written guidance is a dead end and no gate covers it. check_deprecated_surfaces.sh tracks which deprecated surfaces exist against an allowlist; it does not check that a deprecation's target is supported.

What this changes

Each message now names the replacement the namespace's own annotation points at, so one hop reaches a supported API:

• models.unloadAll(category)
• interrupt() on the SpeechHandle returned by tts.speak()
• vad.openStream(format, options), and close() on the VadStream it returns for the reset case
• stt.openStream(format, options)

I took each target from the deprecated namespace method's own annotation rather than picking one, and confirmed the members exist: ModelsNamespace.unloadAll (:266), TtsNamespace.speak (:60) returning SpeechHandle with interrupt() (Results.kt:252), SttNamespace.openStream (:189), and VadStream.close() (Results.kt:315).

Message strings only. No signature, body, or ReplaceWith target changes, so this cannot alter behaviour.

How I found them

Collected the deprecated methods declared inside public/api/*Namespace.kt, then looked for any @Deprecated message elsewhere naming <namespace>.<method> for that set. Six hits, four files. After the change the same scan reports zero.

Worth noting the scan produced 31 raw hits at first and 25 were false positives, because a deprecated extension and the live namespace method often share a simple name (generate, rerank, diarize). Those messages are correct and I left them alone; only the six above name a target that really is deprecated.

Verification

• ./gradlew :compileDebugKotlin --rerun-tasks -x :buildLocalJniLibs -x :downloadJniLibs -x :syncAndroidRuntimeLibs -Prunanywhere.useLocalNatives=false: BUILD SUCCESSFUL
• ./gradlew ktlintMainSourceSetCheck: clean
• git status shows only the four source files; the codegen the Gradle build runs left nothing behind

No test added: these are annotation strings, and a test asserting the text of a deprecation message would pin prose rather than behaviour.

Summary by CodeRabbit

• Documentation
  • Updated deprecation guidance for model unloading, speech-to-text streaming, text-to-speech controls, and voice activity detection.
  • Deprecated APIs now point to recommended replacement workflows, including stream handles and lifecycle methods.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[ayaangazali]

Heads up on the red python-linux (3.9) and (3.12) cells here: they are not from this diff.

Both are red on main too, at b2d2ff6d (run 32011099890), with "The job has exceeded the maximum execution time of 1h30m0s". The job hangs inside auditwheel repair because the prep step's ln -sf libonnxruntime.so lib/libonnxruntime.so.1 overwrites the middle link of the chain the new RunAnywhere desktop prebuilt ships, turning libonnxruntime.so and libonnxruntime.so.1 into a symlink loop.

I opened #736 with the evidence and a one-line guard. Nothing to do on this PR; every other check here is green.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 3d09eaea-f539-42e6-b6a4-69ae9bfbcb34

📥 Commits

Reviewing files that changed from the base of the PR and between 488cf27 and 4710704.

📒 Files selected for processing (4)

• bindings/kotlin/src/main/kotlin/com/runanywhere/sdk/public/extensions/Models/RunAnywhereModelLifecycle.kt
• bindings/kotlin/src/main/kotlin/com/runanywhere/sdk/public/extensions/STT/RunAnywhereSTT.kt
• bindings/kotlin/src/main/kotlin/com/runanywhere/sdk/public/extensions/TTS/RunAnywhereTTS.kt
• bindings/kotlin/src/main/kotlin/com/runanywhere/sdk/public/extensions/VAD/RunAnywhereVAD.kt

Included review availability: Your plan provides up to 10 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

Updated Kotlin deprecation messages for model, STT, TTS, and VAD APIs. The messages now reference current replacement APIs and stream lifecycle methods.

Changes

Kotlin API guidance

Layer / File(s)	Summary
Replacement API deprecation messages bindings/kotlin/.../Models/RunAnywhereModelLifecycle.kt, bindings/kotlin/.../STT/RunAnywhereSTT.kt, bindings/kotlin/.../TTS/RunAnywhereTTS.kt, bindings/kotlin/.../VAD/RunAnywhereVAD.kt	Updated deprecated API messages to reference unloadAll, openStream, SpeechHandle.interrupt(), and closing VadStream.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to 47107

This is a documentation-only API guidance update with no identified merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the Kotlin deprecation fix and matches the main change: preventing deprecated guidance from pointing to deprecated replacements.
Description check	✅ Passed	The description explains the problem, lists all affected APIs and replacements, documents verification, and states why no tests were added. It does not use the repository template headings or complete…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[ayaangazali]

Rebased onto 0b95af9ae (0.20.27), diff unchanged.

Still reproduces. Re-ran the check against current main: five Kotlin deprecations still send the caller to a replacement that is itself deprecated.

RunAnywhereModelLifecycle.kt:100   -> RunAnywhere.models.unload
RunAnywhereTTS.kt:180              -> RunAnywhere.tts.stop
RunAnywhereTTS.kt:244              -> RunAnywhere.tts.stop
RunAnywhereVAD.kt:96               -> RunAnywhere.vad.detectStream
RunAnywhereSTT.kt:88               -> RunAnywhere.stt.transcribeStream

Following any of those trades one deprecation warning for another. This retargets them at the live replacements.

For context on scope: the same defect exists in Swift and Web and is #762, and ReplaceWith targets elsewhere in the Kotlin SDK all resolve correctly, so this is the complete Kotlin set rather than a sample.

[ayaangazali]

Still reproduces on c11f78ef4. Re-checked each of the four replacement targets this time rather than the diff, and every one of them is itself deprecated on main:

ModelsNamespace.kt:281  @Deprecated("Use unloadAll(category).", ReplaceWith("unloadAll(category)"))
                        public suspend fun unload(category: ModelCategory? = null)

SttNamespace.kt:205     @Deprecated("Use stt.openStream(format, options).", ReplaceWith("openStream(format, options)"))
                        public fun transcribeStream(

TtsNamespace.kt:80      @Deprecated("Use the SpeechHandle returned by speak().")
                        public suspend fun stop()

VadNamespace.kt:186     @Deprecated("Use vad.openStream(format, options).", ReplaceWith("openStream(format, options)"))
                        public fun detectStream(

So the six extension deprecations this PR touches send a caller to a symbol that immediately warns again and carries its own ReplaceWith pointing one hop further on. Following the IDE quick-fix gets you a second deprecation warning rather than working code. The fix is to name the end of the chain directly, which is what these six messages now do.

The replacements they point at all exist and are not deprecated (ModelsNamespace.unloadAll:266, SttNamespace.openStream:189, VadNamespace.openStream:171, and the SpeechHandle returned by tts.speak()).

Text-only change to @Deprecated messages, no behaviour. Merges clean, CI green.

[ayaangazali]

Still reproduces on 45e91276e (0.20.36), and there is now cross-SDK confirmation that this is a pattern rather than a Kotlin oversight.

I verified the same defect on the Swift and Web side while working #762, and it is the identical shape. Swift deprecates a helper by pointing at tts.stop():

// bindings/swift/.../Public/Extensions/TTS/RunAnywhere+TTS.swift:55
@available(*, deprecated, renamed: "tts.stop()")

and that target is itself deprecated:

// bindings/swift/.../Public/API/Namespaces/TTSNamespace.swift:102
@available(*, deprecated, message: "Use the SpeechHandle returned by speak(_:options:) to interrupt one utterance")
public func stop() async {

So the chain this PR fixes in Kotlin exists in at least three SDKs, with the same end state (the SpeechHandle returned by speak). The four Kotlin targets are unchanged on main:

ModelsNamespace.kt:281  @Deprecated("Use unloadAll(category).", ReplaceWith("unloadAll(category)"))
SttNamespace.kt:205     @Deprecated("Use stt.openStream(format, options).", ...)
TtsNamespace.kt:80      @Deprecated("Use the SpeechHandle returned by speak().")
VadNamespace.kt:186     @Deprecated("Use vad.openStream(format, options).", ...)

The ReplaceWith entries are the part that stings, because that is what drives the IDE's automated migration: accepting the quick-fix rewrites one deprecated call into another.

Text-only change to @Deprecated messages, no behaviour. Merges clean, CI green.

[sanchitmonga22]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[sanchitmonga22]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[sanchitmonga22]

Thanks for this, @ayaangazali! Retargeting these @Deprecated messages away from other deprecated symbols makes the migration path for Models/STT/TTS/VAD callers a lot clearer, and the investigation you posted along the way is genuinely thorough.

Before we merge, a few things to sort out — all in what the new targets actually do, not the file list:

1. bindings/kotlin/.../Models/RunAnywhereModelLifecycle.kt:100 — the new message sends every unloadModel(request) caller to models.unloadAll(category), but ModelUnloadRequest can also target one model by model_id, and unloadAll never reads that field — it unloads a whole category (or everything) instead. Suggest: "Use RunAnywhere.models.unload(id) for a single model, or unloadAll(category) for a whole category."
2. bindings/kotlin/.../TTS/RunAnywhereTTS.kt:180 — stopSynthesis() also stops audio started via tts.synthesizeStream(), but the new message only names the SpeechHandle from tts.speak(), which streaming callers never get. Suggest adding: "Cancel the Flow returned by RunAnywhere.tts.synthesizeStream(), or call interrupt() on the SpeechHandle returned by RunAnywhere.tts.speak()."
3. bindings/kotlin/.../VAD/RunAnywhereVAD.kt:118 — resetVAD() resets the lifecycle detector's adaptive state (thresholds, timing) via resetLifecycle(); VadStream.close() only cancels that one stream session and never touches that state, so following the new message doesn't actually reset anything. There isn't a non-deprecated equivalent of the lifecycle reset today, which is worth saying plainly rather than pointing at something that doesn't do it.

Not blocking this PR — I opened #862 for the same deprecation-chain pattern in the Swift and Web SDKs (outside this PR's scope), #863 for giving batch tts.synthesize a non-deprecated way to cancel, and #864 for updating the Kotlin docs that still present these legacy extensions as the current API. You're welcome to pick any of those up if you're interested.

Once the three messages above point at something that actually does what the old one did, we'll take another look. Thanks again for the thorough work here!

Reviewed with help from Claude Code and Codex.