Android (Kotlin)
Install
dependencies {
implementation("com.heysada:rafiq:0.1.0")
}
The assistant’s chats, Skills references and settings inside a host app, for Android and iOS, with Compose Multiplatform screens (Material 3). Apache-2.0 (LICENSE).
rafiq/: the library (com.heysada.rafiq.sdk). Android, iOS (iosArm64,iosSimulatorArm64, a staticRafiqSdkframework) and the desktop JVM, which is there so the tests run in seconds.
It builds with the stack apps/org-app uses (Kotlin, Compose Multiplatform, Ktor, AGP from the same
gradle/libs.versions.toml values), so the org app can embed it without a second Kotlin or Compose.
Set it up
val rafiq = Rafiq.init(
baseUrl = "https://assistant.example.com", // the panel's Install screen fills these in
appKey = "pk_…",
// Optional: the signed-in person, from your server (HS256, the app's identity secret).
userToken = { myBackend.rafiqToken() },
appId = BuildConfig.APPLICATION_ID, // iOS reads its bundle id by itself
guestStore = myGuestStore, // keeps the guest across launches
// The client connection's calls, made inside your app with your own session.
clientCaller = KtorClientCaller("https://api.example.com") { mapOf("Authorization" to "Bearer ${myToken()}") },
// The app's client tools, by name: offered to the model with every message to the AI, run
// here on the person's device (input in, result text out).
clientTools = mapOf(
"open_screen" to ClientTool("Opens one of the app's screens", screenSchema) { input -> navigate(input); "opened" },
),
language = null, // "en" or "ar" fixes the screens' language; null: the client's setting, else the app's locale
)
The SDK never holds a secret. With appKey alone it starts its own session (POST /v1/sessions/sdk):
a guest Rafiq names (its guest_token kept in guestStore; this run only by default, so pass a
lasting store), or the signed-in person when userToken gives your server’s token. appId goes
as X-App-Id, which a live app’s key is held to. session (advanced) gives a JWT your
backend mints with the app’s secret instead. A 401 starts the session again, once. Each answer has
a thumbs up and down (ChatSession.rate).
The screens
Open them from any button. RafiqHost draws the open one full screen over the host’s content:
val host = rememberRafiqHostState()
RafiqHost(rafiq, host, attachments = myPicker) {
MyScreen(onHelp = { host.open(RafiqScreen.Chat) })
}
Or place RafiqChatScreen(rafiq), RafiqKnowledgeScreen(rafiq) and RafiqSettingsScreen(rafiq) in
your own navigation.
RafiqChatScreen: the viewer’s chats (and the messages that mention them), and a conversation. The composer writes to the assistant or to the team,@-mentions members and the assistant, attaches files (attachments: your picker; without one there is no attach button), replies, and edits the viewer’s own message (an edit to the assistant asks it again). A message’s menu asks for the latest answer again and, withkb.write, saves a message to the knowledge. The run’s bar shows what the assistant is doing, what it waits for and how many requests wait behind it, with Stop for the person it acts for. The composer also points at the product’s things (a post, a ticket: whatever the app’s MCP servers list): the@button, or typing@word, opens the kinds a person can pick from and their newest things; a kind opens its own list, and several can be picked. They ride with the message asthings, and the assistant reads each with its tools. A host’s “ask about this” link passesask = RafiqAsk(listOf(Thing(uri, kind, title))): a new chat opens with them in its composer (onAskedsays it was taken).rafiq.api.things(kind, query)is the list.- **### Embedded Skills contract
The Skills screen saves one aggregate through /v1/skills: Name, Content (description only),
Trigger words, Facts, Apply to, When and Status. GET returns the complete aggregate and its
revision; PUT requires that revision and returns 409 after a concurrent edit. Web callers use
listSkills, addSkill and updateSkill; KMP uses skills, addSkill and updateSkill.
The signed session supplies app/client scope. kb.read/kb.write still guard this capability.
SDK and taught-chat material remains quoted source data; an activation setting cannot promote
its trust, grant tools or publish private material to Skills Store.
Supported 0.1.x clients retain the /v1/knowledge title/facts/enabled boundary contract and its
public symbols. The adapter builds a complete Skill through the same ai-brain owner, preserving
source, private scope and all other fields on updates. It has no independent authoring table or
resolver. New owned screens use /v1/skills. Remove the boundary with the next major SDK
contract only after the supported-client adoption inventory confirms migration; changing the
UI label alone is not evidence that external clients have upgraded.