Karl

The main entry point and facade for interacting with the KARL (Kotlin Adaptive Reasoning Learner) library.

This object serves as the primary API surface for developers integrating KARL into their applications. It provides a clean, fluent builder pattern API that abstracts the complexity of container creation and dependency wiring while ensuring proper lifecycle management.

Key responsibilities:

• Provides a type-safe builder pattern for KarlContainer creation

• Abstracts implementation details from client code

• Ensures all required dependencies are properly configured before container instantiation

• Maintains consistent API contracts across different KARL implementations

Usage pattern:

val container = Karl.forUser("user_123")
    .withLearningEngine(learningEngine)
    .withDataStorage(dataStorage)
    .withDataSource(dataSource)
    .withCoroutineScope(scope)
    .build()

container.initialize()

Design rationale:

• Static object ensures singleton-like behavior for the API entry point

• Builder pattern provides fluent configuration and prevents invalid states

• User-scoped containers enable multi-tenant scenarios within single applications

• Delayed initialization pattern allows for proper lifecycle management