API Reference

This section provides an overview of the primary public Application Programming Interfaces (APIs) exposed by Project KARL. For exhaustive details, including all public classes, interfaces, functions, parameters, return types, and KDoc comments, please refer to the Generated API Documentation (Dokka)

Note: Instructions on how to generate or access the full Dokka documentation will be provided once the build process includes Dokka generation.

The Project KARL library is designed with a clear separation of concerns, primarily through interfaces defined in the :karl-core module. Applications typically interact with KARL via the KarlAPI and the KarlContainer instance it builds.

1. Key Public Interfaces & Classes in com.karl.core.api and com.karl.core.data

The following are the most crucial components developers will use when integrating KARL:

1.1 com.karl.core.api.KarlAPI (Object)

  • Purpose: The main entry point for creating and configuring KarlContainer instances.

  • Key Method:

    • fun forUser(userId: String): KarlContainerBuilder: Initiates the builder pattern to configure a container for a specific user.

  • KarlContainerBuilder (Class): Used to set the LearningEngine, DataStorage, DataSource, initial KarlInstructions, and the CoroutineScope for a new KarlContainer.

See Dokka: KarlAPI for detailed build methods.

1.2 com.karl.core.api.KarlContainer (Interface)

  • Purpose: Represents an isolated AI instance for a user. Orchestrates the learning, prediction, and state management processes.

  • Key Properties/Methods:

    • val userId: String: The unique identifier for this container's user.

    • suspend fun initialize(...): Initializes the container, loads state, and starts data observation.

    • suspend fun getPrediction(): Prediction?: Requests a prediction from the learning engine.

    • suspend fun saveState(): Job: Persists the current learned state of the AI model.

    • suspend fun reset(): Job: Resets the AI to its initial state and clears associated user data.

    • fun updateInstructions(instructions: List): Updates the behavioral rules for the container.

    • suspend fun release(): Cleans up resources and stops observation.

See Dokka: KarlContainer for all methods.

1.3 com.karl.core.api.LearningEngine (Interface)

  • Purpose: Defines the contract for the AI model's learning and inference capabilities. Implementations (e.g., :karl-kldl) provide the actual ML logic.

  • Key Methods:

    • suspend fun initialize(state: KarlContainerState?, coroutineScope: CoroutineScope)

    • fun trainStep(data: InteractionData): Job

    • suspend fun predict(contextData: List, instructions: List): Prediction?

    • suspend fun getCurrentState(): KarlContainerState

    • suspend fun reset()

    • suspend fun release()

See Dokka: LearningEngine for method details.

1.4 com.karl.core.data.DataStorage (Interface)

  • Purpose: Defines the contract for persisting and retrieving KarlContainerState and historical InteractionData. Implementations (e.g., :karl-room) handle the specific storage mechanism (e.g., SQLite database).

  • Key Methods:

    • suspend fun initialize()

    • suspend fun saveContainerState(userId: String, state: KarlContainerState)

    • suspend fun loadContainerState(userId: String): KarlContainerState?

    • suspend fun saveInteractionData(data: InteractionData)

    • suspend fun loadRecentInteractionData(userId: String, limit: Int, type: String?): List

    • suspend fun deleteUserData(userId: String)

    • suspend fun release()

See Dokka: DataStorage for method details.

1.5 com.karl.core.data.DataSource (Interface)

  • Purpose: An interface that **must be implemented by the host application**. It acts as the bridge for feeding application-specific user interaction metadata into the KarlContainer.

  • Key Method:

    • fun observeInteractionData(onNewData: suspend (InteractionData) -> Unit, coroutineScope: CoroutineScope): Job

See Dokka: DataSource for method details.

1.6 com.karl.core.instructions.InstructionParser (Interface)

  • Purpose: Defines the contract for parsing raw user input (e.g., a string from a UI) into a list of structured KarlInstruction objects.

  • Key Method:

    • fun parse(rawInput: String): List

See Dokka: InstructionParser for details.

Core Data Models in com.karl.core.models

These data classes represent the key pieces of information exchanged within KARL:

  • InteractionData: Encapsulates metadata about a single user interaction (type, details, timestamp, userId).
    See Dokka: InteractionData

  • KarlContainerState: Represents the serializable state of the learning engine (model weights, parameters, version). See Dokka: KarlContainerState

  • Prediction: Holds the output of an inference operation (suggestion, confidence, type, metadata).
    See Dokka: Prediction

  • KarlInstruction (Sealed Class): Base class for defining user or application rules that can influence KARL's behavior (e.g., IgnoreDataType, MinConfidence).
    See Dokka: KarlInstruction

Implementation Modules (e.g., :karl-kldl, :karl-room)

These modules provide concrete implementations of the core interfaces. Their public API typically consists of the constructor for their main implementation class (e.g., KLDLLearningEngine(...), RoomDataStorage(...)) and any specific configuration classes or helper functions they expose.

Refer to the documentation within each implementation module's README or its generated Dokka output for details on its specific API and configuration options.

This overview serves as a starting point. For the most accurate and detailed information, generating and consulting the Dokka documentation for the entire project is highly recommended.