Kuralit SDK for Flutter

Flutter SDK for Kuralit real-time voice and text communication over WebSocket. Supports text chat, voice streaming (Android and Web), product/entity responses, tool status, and automatic reconnection.

To get the Kuralit Agent working for your app, check kuralit.com.

Features

Voice & Text Interactions — Support for both voice and text-based conversations with the AI agent
Beautiful UI Templates — Pre-built, customizable agent overlay UI components
WebSocket Integration — Real-time bidirectional communication with your backend
Product Cards — Display structured product information in an elegant card strip
Audio Streaming — Real-time audio capture and streaming with visual feedback
Customizable Themes — Fully customizable theming system for brand consistency
Responsive Design — Works seamlessly across different screen sizes
Session Management — Built-in session handling for conversation continuity

Installation

From pub.dev (when published):

dependencies:
  kuralit_sdk: ^0.3.0

From a local path (e.g. same repo):

dependencies:
  kuralit_sdk:
    path: ../kuralit   # or path to the kuralit package

Then run:

flutter pub get

Integration (reference code)

Use this as the reference when integrating Kuralit into any Flutter app.

1. Add the import

import 'package:kuralit_sdk/kuralit.dart';

2. Create the controller and UI in a StatefulWidget

Create the WebSocket controller once (e.g. in your home or main screen state) and dispose it when the widget is disposed. Add the KuralitAnchor as the entry point (e.g. floating action button).

class _YourScreenState extends State<YourScreen> {
  late final KuralitWebSocketController _kuralitController =
      KuralitWebSocket.createController(
    config: KuralitWebSocketConfig(appId: 'your-kuralit-app-id'),
  );

  @override
  void dispose() {
    _kuralitController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      floatingActionButton: KuralitAnchor(controller: _kuralitController),
      // ... rest of your UI
    );
  }
}

3. Configuration options

appId is required (no default). If you use baseWsUrl and pass an empty appId, the SDK throws.

Use case	Code
Your app ID (required)	`KuralitWebSocket.createController(config: KuralitWebSocketConfig(appId: 'your-app-id'))`
Custom server + app ID	`KuralitWebSocket.createController(config: KuralitWebSocketConfig(baseWsUrl: 'wss://your-server.com/ws', appId: 'your-app-id'))`
Full URL override (e.g. emulator)	`KuralitWebSocket.createController(config: KuralitWebSocketConfig(wsUrl: 'ws://10.0.2.2:8000/ws', appId: ''))` — when `wsUrl` is set, `appId` can be empty.

4. Permissions (for voice)

Voice streaming is supported on Android and Web only. Add microphone permissions when using voice:

Android: android/app/src/main/AndroidManifest.xml — add if not present:
```
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
```
Web: The browser will prompt for microphone access when voice is used.

iOS: Not yet supported for voice streaming. When support is added, add to ios/Runner/Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone for voice interaction.</string>

API summary

KuralitWebSocket.createController({ config }) — Creates the WebSocket-backed controller. Pass KuralitWebSocketConfig(appId: '...') to set your Kuralit app ID. Uses platform-specific WebSocket (dart:io / web) under the hood.
KuralitWebSocketController — Implements KuralitUiController: connect(), sendText(), startMic() / stopMic(), startNewSession(), dispose(). Emits events (text, products, STT, tool status, connection, errors). Automatic reconnection with backoff (up to 5 attempts) on disconnect.
KuralitAnchor(controller: ..., theme: ..., label: ...) — Widget that opens the agent overlay (e.g. FAB). Pass your KuralitWebSocketController, optional KuralitTheme, and optional label (default: "Ask for help").
KuralitWebSocketConfig — appId, baseWsUrl, optional wsUrl, plus pingInterval, connectTimeout, audioBacklog, audioChunk.
kuralitDefaultBaseWsUrl — Default Kuralit API base URL; use with custom appId if needed.
startNewSession() — Tears down the current connection and reconnects so the backend creates a new session. Use when switching modalities (e.g. text → voice) for a fresh conversation.

Example app

The example app in this repo (example/lib/main.dart) is a minimal Flutter app. Wire Kuralit as in the Integration section above: create KuralitWebSocketController in your screen state, dispose it in dispose(), and add KuralitAnchor(controller: _kuralitController) to your scaffold (e.g. floatingActionButton).