Expose adaptive context APIs for Swift LLM

[shubhamsinnh]

Summary

Fixes #500.

This PR exposes the adaptive-context LLM APIs through the component layer and adds lifecycle-owned Swift accessors so Swift callers can use the model loaded through the existing RunAnywhere.loadModel flow.

Changes included:

• Add rac_llm_component_inject_system_prompt, rac_llm_component_append_context, rac_llm_component_generate_from_context, and rac_llm_component_clear_context.
• Add lifecycle-owned adaptive-context C ABI helpers for the Swift/public path:
  • rac_llm_inject_system_prompt_lifecycle
  • rac_llm_append_context_lifecycle
  • rac_llm_generate_from_context_proto
  • rac_llm_clear_context_lifecycle
• Add Swift public APIs:
  • RunAnywhere.injectSystemPrompt(_:)
  • RunAnywhere.appendContext(_:)
  • RunAnywhere.generateFromContext(query:options:)
  • RunAnywhere.clearContext()
• Update the Swift vendored CRACommons headers.
• Update RACommons.exports so dynamic Apple builds export the new symbols.

Why

The service layer already exposes adaptive-context operations, but Swift's CppBridge.LLM operates through the component/lifecycle surface. Without wrappers, Swift consumers cannot use prefix-caching/adaptive-context workflows without bypassing the normal model lifecycle.

During local review, the public Swift path was kept lifecycle-owned rather than component-handle-owned so these APIs use the same model loaded by RunAnywhere.loadModel and do not require opening a parallel LLM handle.

Local verification

Verified locally on Windows:

• git diff --check
• Focused symbol audit for declarations, definitions, Swift vendored headers, and RACommons.exports
• Confirmed all 8 new symbols are represented where expected
• Reviewed llama.cpp and MetalRT generate_from_context paths to confirm they continue from existing context/cache rather than clearing it

Not run locally because this contributor environment does not have macOS/iOS tooling:

• swift build
• Xcode/iOS build
• CMake/native C++ build
• repo bash validation scripts (bash maps to WSL here, but WSL2 is not enabled)

CI/macOS validation is needed before this is ready for merge.

---

Note

Medium Risk
Changes affect on-device LLM KV-cache behavior and add a new public inference path; risk is moderated by thin wrappers over existing backend ops and lifecycle locking, but incorrect context sequencing could still yield wrong generations.

Overview
Exposes adaptive-context LLM operations (prefix/KV caching for RAG-style flows) through the component layer and a lifecycle-owned C ABI, then surfaces them on Swift as RunAnywhere.injectSystemPrompt, appendContext, generateFromContext, and clearContext.

Commons: New rac_llm_component_* entry points delegate to the existing service vtable (inject_system_prompt, append_context, generate_from_context, clear_context). New lifecycle helpers (rac_llm_inject_system_prompt_lifecycle, rac_llm_append_context_lifecycle, rac_llm_generate_from_context_proto, rac_llm_clear_context_lifecycle) target the model from rac_model_lifecycle_load_proto; generate_from_context_proto mirrors normal proto generate (events, thinking split, structured output) but calls generate_from_context so the KV cache is not cleared first.

Swift: CppBridge.LLM loads those symbols via NativeProtoABI (lifecycle path, not a separate component handle). Public text-generation extensions gate on SDK init and forward to the bridge. Vendored CRACommons headers and RACommons.exports list the new symbols for dynamic Apple builds.

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

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0eea8c08-9fa5-41d5-9620-14eccb1028ea

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ 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 and usage tips.}

[cursor]

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

^{Bugbot Autofix is ON, but it could not run because the branch was deleted or merged before autofix could start.}

Comment @cursor review or bugbot run to trigger another review on this PR

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

[cursor]

Null options skip component defaults

Medium Severity

rac_llm_component_generate_from_context forwards a null options pointer straight to the service, even though its header documents null for defaults. rac_llm_component_generate and streaming generation on the same component substitute component->default_options first, so callers using the new adaptive-context entry point get different (often unsafe) behavior than other generation APIs.

 

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

[shubhamsinnh]

Could a maintainer please approve the GitHub Actions run for this fork PR when you get a chance? I’m contributing from a Windows environment, so I can’t run the macOS/iOS Swift checks locally. I’ve included the local static checks I was able to run in the PR description.