docs(llm): update generate_stream token_callback docstring for UTF-8 …

[Sarah-Mahmoud-29]

…runs

Fixes #923. Updates rac_llm_component_generate_stream docstring to reflect UTF-8 text runs instead of per-token delivery.

Description

Brief description of the changes made.

Type of Change

• Bug fix
• New feature
• Documentation update
• Refactoring

Testing

• Lint passes locally
• Added/updated tests for changes

Platform-Specific Testing (check all that apply)

Swift SDK / iOS Sample:

• Tested on iPhone (Simulator or Device)
• Tested on iPad / Tablet
• Tested on Mac (macOS target)

Kotlin SDK / Android Sample:

• Tested on Android Phone (Emulator or Device)
• Tested on Android Tablet

Flutter SDK / Flutter Sample:

• Tested on iOS
• Tested on Android

React Native SDK / React Native Sample:

• Tested on iOS
• Tested on Android

Web SDK / Web Sample:

• Tested in Chrome (Desktop)
• Tested in Firefox
• Tested in Safari
• WASM backends load (LlamaCpp + ONNX)
• OPFS storage persistence verified (survives page refresh)
• Settings persistence verified (localStorage)

Labels

Please add the appropriate label(s):

SDKs:

• Swift SDK - Changes to Swift SDK (bindings/swift)
• Kotlin SDK - Changes to Kotlin SDK (bindings/kotlin)
• Flutter SDK - Changes to Flutter SDK (bindings/flutter)
• React Native SDK - Changes to React Native SDK (bindings/react-native)
• Web SDK - Changes to Web SDK (bindings/web)
• Commons - Changes to shared native code (core)

Sample Apps:

• Flutter Sample - Changes to Flutter example app (bindings/flutter/example)
• React Native Sample - Changes to React Native example app (bindings/react-native/example)
• Minimal Examples - Changes to an in-repo SDK harness (bindings/{swift,kotlin,web}/example)

The iOS, Android, Web, and Electron consumer apps live in their own
repositories (RunanywhereAI/runanywhere-{ios,android,web,electron}) — open
those PRs there.

Checklist

• Code follows project style guidelines
• Self-review completed
• Documentation updated (if needed)

Screenshots

Attach relevant UI screenshots for changes (if applicable):

• Mobile (Phone)
• Tablet / iPad
• Desktop / Mac

Summary by CodeRabbit

• Documentation
  • Clarified that streaming callbacks are invoked for each UTF-8-safe text run generated by the model, rather than for each individual token.
  • No functional behavior or public API changes.

[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: 6265453b-f43b-4521-8751-580cbf202c32

📥 Commits

Reviewing files that changed from the base of the PR and between 067778a and 43424f7.

📒 Files selected for processing (1)

• core/include/rac/features/llm/rac_llm_component.h

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

---

📝 Walkthrough

Walkthrough

The public documentation for rac_llm_component_generate_stream now states that token_callback receives UTF-8-safe text runs generated by the model.

Changes

LLM callback documentation

Layer / File(s)	Summary
Update callback contract documentation core/include/rac/features/llm/rac_llm_component.h	The token_callback parameter documentation now describes UTF-8-safe text runs instead of individual generated tokens.

Priority: ⬇️ Low

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

Change: Other · Severity of issue fixed: Low

Merge Risk: ⚪ Minimal · up to 43424

The callback documentation now matches the existing chunked UTF-8 delivery behavior, with no merge-blocking risk identified.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The change satisfies issue #923. In core/include/rac/features/llm/rac_llm_component.h, the token_callback documentation now states that the callback receives each UTF-8-safe text run generated by …
Out of Scope Changes check	✅ Passed	The pull request changes only the documented token_callback parameter in the LLM streaming API. This change directly supports issue #923 and introduces no unrelated source, ABI, or behavior changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Title check	✅ Passed	The title clearly identifies the documentation change to the LLM stream callback and its UTF-8 behavior.
Description check	✅ Passed	The description explains the change, marks it as a documentation update, and records lint testing. The remaining unchecked test, checklist, label, and screenshot items are either non-critical or not a…

✨ 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.}

[sanchitmonga22]

Thanks for this, @Sarah-Mahmoud-29! Correcting the streaming docstring to describe UTF-8-safe text runs instead of raw tokens is exactly the right fix -- it matches how the llama.cpp backend actually chunks output and the ABI v9 typedef's own note that a delta can coalesce multiple tokens.

Before we merge, one thing to sort out:

1. core/include/rac/features/llm/rac_llm_component.h:199 -- the new wording promises every callback delivers a UTF-8-safe run, but when generation ends by hitting max_tokens mid-codepoint, engines/llamacpp/llamacpp_backend.cpp flushes the trailing incomplete UTF-8 bytes to the callback unchanged (see the comment right before the final sink(stop_window) call). Could you soften the wording to call out that one exception -- something like "Called for each UTF-8-safe text run generated by the model (the final run before generation ends may contain a trailing incomplete multi-byte sequence)"?

Optional, not required: the callback typedef doc two lines above in this same file (rac_llm_component.h:44) still says "@PARAM token The generated token" -- feel free to touch that up too while you're in there, but it's fine to leave for later either way.

Not blocking this PR: I opened #929 for keeping the VLM/Swift-bindings sibling headers in sync with this same wording -- you're welcome to pick it up if you're interested.

Once that's in we'll take another look. Thanks again!

Reviewed with help from Claude Code and Codex.