Integrating KARL into Your Application

Initializing & Managing a KARL Container

Proper management of the KarlContainer lifecycle is crucial.

Creating a New Container for a User/Context

As shown in the Getting Started↗ guide, use the Karl.forUser(userId).build() pattern to construct a container instance. You must provide implementations for LearningEngine, DataStorage, your application's DataSource, and a CoroutineScope tied to the relevant lifecycle (e.g., user session, ViewModel).

Key Snippet (from "Getting Started")

val karlContainer = Karl.forUser(userId)
    .withLearningEngine(myEngineImpl)
    .withDataStorage(myDataStorageImpl)
    .withDataSource(myDataSourceImpl)
    .withCoroutineScope(applicationManagedScope)
    .build()
applicationManagedScope.launch {
    karlContainer.initialize(...) 
    // Pass dependencies again for now
}

Loading and Saving Container State (Persistence across sessions)

The learned state of the AI (model weights, etc.) is encapsulated in KarlContainerState.

• Loading: Occurs automatically during karlContainer.initialize() if a previous state exists for the user in the DataStorage.

• Saving: Your application must call karlContainer.saveState() at appropriate times:

  • Periodically during long sessions (e.g., after a certain number of interactions or time interval).

  • When the application is about to close or the user session ends. This is critical to persist the latest learning.

  
  applicationManagedScope.launch { karlContainer.saveState().join() } 
  // .join() if saving is critical before exit
                                      

The chosen DataStorage implementation (e.g., :karl-room) handles the actual serialization and disk I/O.

Handling Multiple Containers (If applicable)

If your application supports multiple distinct users or isolated contexts on the same device, you would create and manage a separate KarlContainer instance for each, identified by a unique userId passed to Karl.forUser(userId). Each container will have its own independent learned state.

Feeding Data to KARL (Triggering the learning step)

This is primarily the role of your DataSource implementation.

When and How DataSource Provides Data

Your DataSource implementation's observeInteractionData method will be called by the KarlContainer during its initialization. Inside this method, your application should:

1. Subscribe or listen to relevant internal application events that represent user interactions.

2. Upon receiving an event, transform it into an InteractionData object (as discussed in 4.1.2).

3. Call the onNewData: suspend (InteractionData) -> Unit callback (provided by the KarlContainer) with the new InteractionData. This callback internally queues the data for processing by the LearningEngine's trainStep().

The KarlContainer handles invoking the LearningEngine's trainStep() internally when new data is received from the DataSource via the onNewData callback.

Asynchronous Processing (Using Kotlin Coroutines)

All KARL operations that might be long-running (initialization, saving state, training steps, predictions) are designed to be suspend functions or return Jobs. It is crucial that your application:

• Provides a CoroutineScope to the KarlContainer that is tied to an appropriate lifecycle (e.g., ViewModel scope, application scope, user session scope).

• Launches calls to KARL's suspend functions (like initialize, getPrediction, saveState, reset, release) within this scope or another appropriate coroutine context to avoid blocking the main UI thread.

• The onNewData callback in your DataSource is a suspend function. The KarlContainer calls this from its own internal coroutine, and the LearningEngine.trainStep() is also designed to be non-blocking or offload work.

Using KARL's Predictions (Triggering the inference step)

When and How to Call predict()

Your application requests a prediction by calling suspend fun getPrediction(): Prediction? on your KarlContainer instance. You might do this:

• In response to a specific user action (e.g., after the user types a command, to predict the next one).

• When a particular screen or UI component becomes active, to personalize its content.

• Periodically, if you want to proactively update a suggestion UI.

applicationManagedScope.launch 
val currentPrediction = karlContainer.getPrediction
if (currentPrediction != null) 
// Update UI or application logic

Interpreting Prediction Output (Prediction data class)

The getPrediction() method returns a nullable Prediction object. This data class contains:

• suggestion: String: The primary suggested output.

• confidence: Float: The model's confidence in this suggestion (typically 0.0 to 1.0).

• type: String: A category for the prediction, helping your app understand how to use it.

• metadata: Map?: Optional additional data. Your application logic will use these fields to, for example, display the suggestion, decide whether to show it based on confidence, or perform different actions based on the prediction type.

Integrating with UI Frameworks (e.g., Jetpack Compose)

If your application uses a declarative UI framework like Jetpack Compose, you can integrate KARL's outputs reactively.

Displaying Suggestions

Use Compose's state management (e.g., StateFlow collected as state) to hold the latest Prediction. When the state updates, your Composable UI will recompose to display the new suggestion.

Conceptual Snippet (ViewModel/StateHolder):

private val _karlPrediction = MutableStateFlow(null)
val karlPrediction: StateFlow = _karlPrediction.asStateFlow()
fun fetchKarlPrediction() {
    viewModelScope.launch { // Assuming ViewModel scope
        _karlPrediction.value = karlContainer.getPrediction()
    }
}
val prediction by viewModel.karlPrediction.collectAsState()
if (prediction != null) { Text("KARL Suggests: ${prediction.suggestion}") }

Visualizing KARL's Learning Progress (The "maturity" UI element)

The :karl-compose-ui module provides a KarlLearningProgressIndicator. To use this effectively, your application or the LearningEngine would need to expose a metric representing the model's "maturity" or learning progress (e.g., number of interactions processed, a confidence score trend). This is an advanced feature that requires careful design in the LearningEngine.

Handling User Interaction with Suggestions

Provide UI elements for users to accept, reject, or ignore KARL's suggestions. This feedback can itself be valuable InteractionData to further refine KARL's learning (e.g., InteractionData(type="suggestion_accepted",details=mapOf("suggestion_type" to prediction.type))).

Customizing the AI Model

While KARL aims for ease of use, advanced users or specific applications might require model customization.

Choosing or Configuring the Model Architecture

The default LearningEngine implementation (e.g., in :karl-kldl) might use a simple model like an MLP. Future versions or custom implementations could allow:

• Selecting different model types (RNNs, Transformers for sequence data) via configuration.

• Adjusting layer sizes, number of layers, or other architectural parameters if the engine's constructor or factory methods expose them.

Currently, deep customization requires modifying the chosen LearningEngine implementation module or creating your own.

Hyperparameters (Tuning the Learning Process)

Hyperparameters like learning rate, batch size (for mini-batch training if implemented), or regularization factors significantly impact learning. If an LearningEngine implementation exposes these (e.g., via its constructor), you can tune them. However, on-device hyperparameter tuning is complex; usually, sensible defaults are provided.