How theaniketraj/project-karl works
Purpose and entry points
KARL is a Kotlin library for private, on-device incremental learning from application interaction metadata. Its core is Kotlin Multiplatform; the runnable JVM desktop integration is karl-example-desktop/src/jvmMain/kotlin/Main.kt. Consumers primarily create and operate containers through karl-core/src/commonMain/kotlin/com/karl/core/api/KarlAPI.kt.
Module boundaries
The Gradle multi-module build is rooted at settings.gradle.kts and build.gradle.kts. karl-core owns platform-neutral contracts and orchestration; optional modules supply UI, learning, and persistence implementations:
• karl-core/build.gradle.kts
• karl-kldl/build.gradle.kts
• karl-room/build.gradle.kts
Public contract and domain model
The core API defines the extension boundary between a host app and KARL. Hosts provide a DataSource for relevant user events, a DataStorage for local persistence, and a LearningEngine for training/prediction. Shared models carry interaction metadata and serializable container state:
• karl-core/src/commonMain/kotlin/com/karl/core/api/KarlCoreInterfaces.kt
• karl-core/src/commonMain/kotlin/com/karl/core/models/DataModels.kt
• karl-core/src/commonMain/kotlin/com/karl/core/models/DataStorage.kt
Container orchestration
KarlContainerImpl is the per-user/per-scope control boundary. It coordinates event intake, instruction handling, learning-engine calls, predictions, and state persistence. This container model prevents learning context from being global to an application:
• karl-core/src/commonMain/kotlin/com/karl/core/container/KarlContainerImpl.kt
• karl-core/src/commonMain/kotlin/com/karl/core/api/KarlAPI.kt
Learning and instruction stages
Incoming interaction data is interpreted under optional user/application rules, then used for incremental training. Predictions are requested from the engine and are based on locally retained learned state. The engine interface permits alternate ML implementations; the included JVM KLDL module supplies an MLP-backed engine:
• karl-core/src/commonMain/kotlin/com/karl/core/learning/LearningEngine.kt
• karl-core/src/commonMain/kotlin/com/karl/core/instructions/InstructionParser.kt
• karl-kldl/src/jvmMain/kotlin/com/karl/kldl/KLDLLearningEngine.kt
Persistence boundary
Storage is abstract in core, with a Room-backed implementation in karl-room. Room entities represent interaction records and container state; JVM factory/storage code connects that schema to the core DataStorage contract. Data is intended to remain on device; no cloud or network service is represented in this repository:
• karl-room/src/commonMain/kotlin/com/karl/room/KarlDao.kt
• karl-room/src/commonMain/kotlin/com/karl/room/KarlRoomDatabase.kt
• karl-room/src/jvmMain/kotlin/com/karl/room/RoomDataStorage.kt
Presentation and reference integration
karl-compose-ui provides Compose Multiplatform UI around a KARL container, including learning-progress presentation, without becoming part of core orchestration. The desktop example wires concrete storage and learning components into a local app and includes a local SQLite database artifact:
• karl-compose-ui/src/commonMain/kotlin/com/karl/ui/KarlContainerUI.kt
• karl-example-desktop/src/main/kotlin/com/karl/example/DesktopExampleApp.kt
• karl-example-desktop/src/main/kotlin/com/karl/example/RealDataStorage.kt
Runtime and delivery
Primary runtimes are Kotlin Multiplatform common code and JVM implementations; karl-room also declares Android support via its manifest. GitHub Actions builds, releases, and deploys Dokka documentation; the documented docs site is Netlify-hosted, while learning/storage execution stays local:
• .github/workflows/build.yml
• .github/workflows/release.yml
• .github/workflows/deploy_dokka.yml
Main entry points: settings.gradle.kts Gradle multi-module build · KarlContainerImpl.kt Karl container · DesktopExampleApp.kt Desktop example app · RoomDataStorage.kt Room data storage
Components 18
Kotlin Multiplatform Core
Platform-neutral API, models, and container orchestration.
- Karl API · Host entry point for creating and operating containers.
karl-core/src/commonMain/kotlin/com/karl/core/api/KarlAPI.kt - Host extension contracts · DataSource, DataStorage, and LearningEngine integration boundary.
karl-core/src/commonMain/kotlin/com/karl/core/api/KarlCoreInterfaces.kt - Interaction models · Shared interaction metadata and container state.
karl-core/src/commonMain/kotlin/com/karl/core/models/DataModels.kt - Storage state contract · Serializable storage-facing container state.
karl-core/src/commonMain/kotlin/com/karl/core/models/DataStorage.kt - Karl container · Isolates learning context per user or scope.
karl-core/src/commonMain/kotlin/com/karl/core/container/KarlContainerImpl.kt - Instruction parser · Interprets optional user and application rules.
karl-core/src/commonMain/kotlin/com/karl/core/instructions/InstructionParser.kt - Learning engine contract · Supports interchangeable incremental training and prediction engines.
karl-core/src/commonMain/kotlin/com/karl/core/learning/LearningEngine.kt
Optional Implementations
Learning, persistence, and UI modules.
- KLDL MLP engine · Included MLP-backed LearningEngine implementation.
karl-kldl/src/jvmMain/kotlin/com/karl/kldl/KLDLLearningEngine.kt - Room schema & DAO · Persists interaction records and container state.
karl-room/src/commonMain/kotlin/com/karl/room/KarlRoomDatabase.kt - Room data storage · Connects Room persistence to the core storage contract.
karl-room/src/jvmMain/kotlin/com/karl/room/RoomDataStorage.kt - Compose container UI · Presents a container and learning progress outside core orchestration.
karl-compose-ui/src/commonMain/kotlin/com/karl/ui/KarlContainerUI.kt
Desktop Integration & Delivery
Reference JVM application and automation.
- Desktop entry point · Starts the runnable desktop reference integration.
karl-example-desktop/src/jvmMain/kotlin/Main.kt - Desktop example app · Wires KARL into a local desktop app.
karl-example-desktop/src/main/kotlin/com/karl/example/DesktopExampleApp.kt - Example local storage · Provides the example application's local persistence setup.
karl-example-desktop/src/main/kotlin/com/karl/example/RealDataStorage.kt - Build workflow · Build automation for the repository.
.github/workflows/build.yml - Release workflow · Release automation.
.github/workflows/release.yml - Dokka deployment · Builds and deploys documentation.
.github/workflows/deploy_dokka.yml
Other components
- Gradle multi-module build · Defines the KARL module topology.
settings.gradle.kts
Connections 23
- Gradle multi-module build → Karl API: includes
- Gradle multi-module build → KLDL MLP engine: includes
- Gradle multi-module build → Room data storage: includes
- Gradle multi-module build → Compose container UI: includes
- Karl API → Karl container: creates and operates
- Host extension contracts → Karl container: implemented by host dependencies
- Interaction models → Karl container: carries events and state
- Storage state contract → Host extension contracts: supports persistence contract
- Karl container → Instruction parser: interprets events with
- Karl container → Learning engine contract: trains and predicts through
- Karl container → Host extension contracts: persists through
- KLDL MLP engine → Learning engine contract: implements
- Room data storage → Host extension contracts: implements DataStorage
- Room data storage → Room schema & DAO: reads and writes
- Compose container UI → Karl container: presents
- Desktop entry point → Desktop example app: starts
- Desktop example app → Karl API: uses
- Desktop example app → KLDL MLP engine: wires
- Desktop example app → Example local storage: configures
- Example local storage → Room data storage: uses
- Build workflow → Gradle multi-module build: builds
- Release workflow → Gradle multi-module build: releases
- Dokka deployment → Gradle multi-module build: generates documentation from