SDK (preview)

Not yet published. The Flutter SDK described here is planned but not released. Today, integrate against the API directly — see Getting started. This page previews the shape the SDK will take so you can plan ahead; names and details may change before launch.

The SDK's public surface will be intentionally small: a widget, a config object, a tool registry, and a controller. Everything is plain Dart — no state-management library leaks through, so the SDK fits whatever your app already uses.

VoiceAssistant

The widget you place on screen. It renders the embedded mic button and the transcript sheet, and owns the session lifecycle.

VoiceAssistant(
  config: myConfig,
  controller: myController, // optional, see below
  onTranscript: (text, isFinal) { /* ... */ },
  onError: (err) { /* show a banner */ },
);

VoiceAssistantConfig

Configures a session. Only a few fields are required; the rest have sensible defaults.

final config = VoiceAssistantConfig(
  endpoint: 'https://api.kerai.io',
  apiKey: const String.fromEnvironment('KERAI_KEY'),
  language: 'ml-IN',
  mode: InteractionMode.clientText,
  tools: myAppTools,
);

Registering tools

A Tool is a named function with a typed parameter schema and a handler. ker-ai decides when to call it from the user's speech; your handler does the work and returns JSON-serializable data that the assistant speaks back.

final tool = Tool(
  name: 'check_order_status',
  description: 'Look up the status of an order by its number',
  parameters: {
    'orderNumber': ToolParam.string('The order number to look up'),
  },
  handler: (args) async {
    final status = await orders.statusOf(args['orderNumber']);
    return {'status': status};
  },
);
 
final registry = ToolRegistry([tool]);

Guidelines that make tool calls reliable:

• Write the description for the model, not for yourself — say when to use it.
• Keep parameters flat and typed. Mark optional ones with a defaultValue.
• Return small, structured results. The model speaks a summary, so it does not need your whole database row.

The controller

For programmatic control — start/stop listening, push app context, or react to session state — pass a VoiceAssistantController.

final controller = VoiceAssistantController();
 
// somewhere in your widget tree:
VoiceAssistant(config: config, controller: controller);
 
// elsewhere:
controller.startListening();
controller.stopListening();
 
controller.state.listen((s) {
  // s is a plain enum: idle, listening, thinking, speaking, error
});

The controller exposes plain Streams and methods. There are no framework types in the signatures, so you can bridge it to Riverpod, Bloc, setState, or anything else.

Surfacing recommendations

Beyond reacting to speech, ker-ai can proactively suggest actions from your app's state. Provide a snapshot and ker-ai surfaces relevant nudges through the same widget.

controller.updateAppState({
  'screen': 'cart',
  'cartValue': 1499,
  'lastOrderDays': 12,
});

See recommendations for how snapshots are pulled and turned into suggestions.

Error handling

The SDK reports user-actionable failures — microphone permission denied, an unsupported browser speech API, a dropped connection, an invalid config — through onError and the controller's error state, each with a readable message. Show them; don't swallow them.