Project KARL is an open-source Kotlin library for building privacy-first, locally adaptive AI models that integrate seamlessly into applications using a unique composable container architecture.

KARL empowers developers to add intelligent, personalized features without compromising user data privacy by performing all learning and inference directly on the user's device.

• Project KARL: The Kotlin Adaptive Reasoning Learner
  • Introduction
  • Table of Contents
  • Core Philosophy ✨
  • Motivation
    • Why KARL? 🤔
    • Project Status 🚧
  • Getting Started 🚀
  • Example Application 🖥️
  • Architecture & Internals 🛠️
  • Project Structure 📂
  • Use Cases / Example Implementations 💡
  • Features ✨
  • Documentation 📚
  • Contributing ❤️
  • Security Policy 🛡️
  • License 📄

• 🧠 Local & Adaptive Learning: KARL starts as a blank slate and learns incrementally from individual user actions within your application, creating truly personalized experiences. No massive pre-trained models, no assumptions – just learning directly from usage.
• 🔒 Privacy-First by Design: Zero data egress. All learning and inference happens exclusively on the user's device. User interaction metadata (not sensitive content) is stored locally and encrypted.
• 🧩 Composable Container Architecture: KARL operates within a defined "Container" – a logical and potentially visual sandbox. This provides clear boundaries for the AI's scope and enhances user trust and control.
• 🤝 Open-Source Core: The fundamental KARL engine and container logic are open-source under the Apache License 2.0, fostering transparency, community contributions, and trust.
• 🚀 Kotlin Native: Built primarily with Kotlin, leveraging Kotlin Multiplatform for the core logic and integrating naturally with modern Kotlin/JVM and Jetpack Compose applications.

Traditional AI often requires sending user data to the cloud, creating significant privacy concerns, especially for sensitive data like developer workflows or personal habits. KARL offers an alternative: intelligent personalization without the data privacy trade-off. It's designed for applications where user trust and data locality are paramount.

While initially conceived as the foundation for a Proprietary SaaS Application, the core KARL library is designed to be a general-purpose tool for any Kotlin developer looking to build private, on-device intelligence.

Alpha / Early Development: KARL is currently under active development. APIs might change, and comprehensive testing is ongoing. It is not yet recommended for production use without thorough evaluation. We welcome feedback and contributions!

Please refer to the Getting Started Guide.

For more details, see the Full Documentation.

The :karl-example-desktop module provides a runnable example. To run it:

./gradlew :karl-example-desktop:run

Explore the code in this module to see a practical integration of KARL.

Project KARL is built around several key components interacting within a containerized structure:

1. KarlContainer: The central orchestrator for a specific user's AI instance. It manages the lifecycle, data flow, and interactions between other components. Created via the KarlAPI.
2. LearningEngine (Interface): Defines the contract for the AI model responsible for trainStep() (incremental learning) and predict() (generating suggestions). Implementations (like :karl-kldl) wrap actual ML libraries.
3. DataStorage (Interface): Defines the contract for persistent storage of the KarlContainerState (model weights, etc.) and potentially relevant historical InteractionData. Implementations (like :karl-sqldelight) handle the actual database operations.
4. DataSource (Interface): An interface that the hosting application implements. It's responsible for observing user actions within the app and feeding relevant InteractionData (metadata, not sensitive content) into the KarlContainer.
5. InteractionData (Model): Represents a piece of anonymized user interaction metadata (e.g., event type, timestamp, basic details) used for learning.
6. KarlContainerState (Model): Represents the serializable state of the LearningEngine, allowing the AI's learned knowledge to be saved and loaded.
7. KarlInstruction (Model) & InstructionParser (Interface): Allow for user-defined rules to modify the container's behavior (e.g., filtering data, setting prediction thresholds).

Please refer to the Project Structure.

KARL's privacy-first, local-learning approach makes it suitable for various scenarios:

• Developer Tools: Suggesting commands, predicting errors, personalizing IDE layouts based only on the individual developer's local workflow (as in the original inspiration).
• Personal Productivity Apps: Adapting task suggestions, habit tracking reminders, or focus modes based on the user's private usage patterns without cloud analysis.
• Content Recommendation (On-Device): Recommending articles, music, or products within an app based only on the user's interaction history stored locally.
• Adaptive UI: Dynamically rearranging UI elements or highlighting features based on an individual's frequency of use, calculated entirely on the device.
• Smart Home Control (Local): Learning user preferences for lighting, temperature, etc., based on local interactions, without sending behavioral patterns to the cloud.
• Health & Wellness Apps: Personalizing insights or reminders based on locally tracked data (e.g., mood entries, activity levels) while ensuring HIPAA compliance or general user privacy.

The key is any application where personalization is desired, but sending behavioral data to a server is undesirable or prohibited due to privacy concerns, regulations, or user preference.

• 🧠 Local & Adaptive Learning: Learns directly from individual user behavior on-device.
• 🔒 Privacy-First: Zero data egress by default. All processing and storage are local.
• 🧩 Composable Container: Manages AI state and logic within a defined boundary.
• 🔧 Pluggable Architecture: Core interfaces allow swapping implementations for learning engines (e.g., KotlinDL) and data storage (e.g., SQLDelight).
• 📜 User Instructions: Allows users or applications to define rules guiding the AI's behavior.
• 🚀 Kotlin Native: Built primarily with Kotlin, leveraging Multiplatform for core logic and integrating well with JVM/Compose environments.
• 📄 Apache 2.0 Licensed: Permissive open-source license encourages adoption and contribution.

Detailed documentation covering concepts, integration, API reference, and contribution guidelines can be found in the /docs directory or at KARL-AI DOCS.

Contributions are welcome! Whether it's bug reports, feature suggestions, documentation improvements, or code contributions, please get involved.

1. Reporting Issues: Use the GitHub Issues tab.
2. Suggesting Features: Use the GitHub Issues tab with an appropriate label.
3. Code Contributions: Please read our Contribution Guidelines before submitting a Pull Request.
4. Code of Conduct: Please adhere to our Code of Conduct.

The security of Project KARL is a top priority. We take vulnerabilities seriously and appreciate the community's help in keeping our software secure.

If you discover a security vulnerability, please follow our responsible disclosure policy. Do not report security vulnerabilities through public GitHub issues.

Please refer to our detailed Security Policy for information on how to report a vulnerability.

Project KARL is licensed under the Apache License, Version 2.0. See the LICENSE file for details.