Kotlin SDK

Use the Kotlin SDK when your client or agent runs on the JVM or on Android.

The Maven Central coordinates are com.thalovant:thalovant-sdk. JVM 17 or newer is required, or an Android toolchain that produces Java 17 bytecode. The SDK uses OkHttp, kotlinx-serialization, and kotlinx-coroutines.

Source and releases: thalovant-kotlin-sdk on GitHub.

Install

Add the dependency to your Gradle build:

dependencies {
    implementation("com.thalovant:thalovant-sdk:0.1.4")
}

First Request

This flow signs in, creates a client identity, and sends one request over WSS.

import com.thalovant.sdk.CreateClientIdentityOptions
import com.thalovant.sdk.ThalovantClient
import com.thalovant.sdk.ThalovantControlPlane
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val api = ThalovantControlPlane()

    api.login("[email protected]", "password")

    val result = api.createClientIdentity(
        "hub-id",
        CreateClientIdentityOptions(name = "kotlin-demo-client"),
    )

    val client = ThalovantClient(result.identity)
    try {
        val reply = client.ask("Tell me a short clean joke.")
        println(reply.text)
    } finally {
        client.close()
    }
}

ThalovantControlPlane() uses https://api.thalovant.com by default.

Caution

Keep result.identity secret. Authenticated API actions require API access on the workspace. Do not log result.asJson(includeSecrets = true).

Sign In With MFA

Accounts with multi-factor authentication enabled must include a TOTP code or a one-time recovery code with the login. Without one, the API rejects the sign-in with HTTP 401 and code mfa_required.

api.login("[email protected]", "password", otpCode = "123456")

// Or use a one-time recovery code instead:
api.login("[email protected]", "password", recoveryCode = "abcd-efgh-ijkl")

The otpCode and recoveryCode values are sent only when provided.

Sign In Without A Password

Device login asks your browser to approve the sign-in, so services and apps never handle your password. The SDK prints a short code and the address https://dash.thalovant.com/activate, opens that page when it can, and waits while you approve the request in the dashboard with your normal sign-in, including Google sign-in or MFA. On approval the SDK holds a scoped, revocable API token.

Device login needs SDK 0.1.1 or newer. Approving the request needs a paid workspace plan; a free plan gets HTTP 402.

import com.thalovant.sdk.DeviceLoginOptions

api.loginWithBrowser(
    DeviceLoginOptions(scopes = listOf("hubs:read"), clientName = "kotlin-demo"),
)

Manage the resulting token on the dashboard’s API Tokens page.

Authenticate With An API Token

Pass a stored API token when the process should start authenticated, such as CI jobs and services. Mint one on the API Tokens page or with loginWithBrowser; the page shows scopes, expiry, and last use, and can revoke the token at any time.

val api = ThalovantControlPlane(accessToken = System.getenv("THALOVANT_API_TOKEN"))

WSS Only In v0.1

This release connects to the hub over WSS only. Requesting https or mqtt throws ThalovantUnsupportedProtocolException. Endpoint selection still honors the shared preference order wss, https, mqtt, so identities created for multi-protocol hubs keep working.

Use the Python, Node.js, Go, or Rust SDK when the client needs the HTTPS or MQTT data plane today.

Inspect what an identity supports:

import com.thalovant.sdk.HubProtocol

println(identity.enabledProtocols())
println(identity.endpointFor(HubProtocol.WSS))
println(identity.mqtt?.endpoint)

Use A Saved Identity

Raw identity files downloaded from Thalovant work directly. The SDK rejects identity files that other users can read or write on Linux and macOS, so protect them with chmod 600 and keep them out of Git.

val client = ThalovantClient.fromIdentityFile("_identity.json")

You can also parse an identity payload you already hold in memory:

import com.thalovant.sdk.ThalovantIdentity

val identity = ThalovantIdentity.fromJson(identityJson)

Follow An Operation

Mutating control-plane commands return durable operations. Poll them with the typed helper:

val operation = api.getOperation("operation-id")
println(operation.status)

See Operations for lifecycle and retry guidance.

Listen For Events

import com.thalovant.sdk.ThalovantEvents

val subscription = client.on(ThalovantEvents.SPEAK) { event ->
    println(event.text)
}
// Later, when the listener is no longer needed:
subscription.close()

Useful Helpers

ask

Send one request and receive a normalized reply with a timeout you control.

sendUtterance

Send speech-like or chat-like input without waiting for the reply.

emit

Send a named event with structured data and context.

getOperation

Poll a durable control-plane command with a typed status.

For cross-language recipes, see SDK Functions.

Provision Hubs

Since SDK 0.1.3 the control plane can create hubs, runtime groups, and skill installs. Browsing the catalog with listMarketplaceSkills() needs hubs:read and works on any plan. createHub, createRuntimeGroup, installRuntimeGroupSkill, releaseHub, and releaseRuntimeGroup need hubs:write and a paid plan.

val group = api.createRuntimeGroup(RuntimeGroupCreatePayload(name = "kiosks"))
val hub = api.createHub(
    HubCreatePayload(
        name = "joke-garden",
        spec = buildJsonObject { },
        runtimeGroupId = group["id"]!!.jsonPrimitive.content,
    ),
)

val current = api.getHub(hub["id"]!!.jsonPrimitive.content)
api.updateHub(
    current["id"]!!.jsonPrimitive.content,
    HubUpdatePayload(active = false),
    etag = current["etag"]!!.jsonPrimitive.content,
)

updateHub and deleteHub take the hub’s current etag as a required argument. See Provision Hubs for the full flow, the immutable fields, and the error table.

Common Issues

Symptom	Check
Missing Thalovant API access token	Call api.login(...) or api.loginWithBrowser(...) before private API actions, or pass accessToken to ThalovantControlPlane.
HTTP 401 with code mfa_required	Pass otpCode or recoveryCode to api.login(...).
API access requires a paid plan	Upgrade the workspace before provisioning private resources through the API.
ThalovantUnsupportedProtocolException	The hub does not expose WSS, or the code requested https or mqtt, which this release does not connect over.
A request times out	Pass a larger timeoutMs to ask(...).