build

Validates configuration and constructs a new KarlContainer instance.

This method performs comprehensive validation of all required dependencies and constructs a properly configured container instance. The validation process ensures that all essential components are present and correctly configured before creating the container, preventing runtime failures and configuration errors.

Validation performed:

• Dependency presence: Ensures all required components are configured

• Dependency validity: Verifies that components are properly initialized

• Configuration consistency: Checks for conflicting settings or constraints

• Resource availability: Validates that required resources are accessible

• Scope validity: Ensures the provided coroutine scope is active and suitable

Container creation process:

1. Validate all required dependencies are present and properly configured

2. Create internal container implementation with dependency injection

3. Configure internal components with provided settings and instructions

4. Return ready-to-initialize container instance

Post-build requirements: The returned container is NOT yet initialized and ready for use. You MUST call container.initialize() to complete the setup process. This two-phase initialization pattern provides several benefits:

• Error handling: Allows separate handling of configuration vs. runtime errors

• Lifecycle control: Enables precise control over when background processes start

• Testing support: Facilitates unit testing by allowing mock initialization

• Resource management: Ensures resources are allocated only when needed

Initialization sequence after build():

val container = builder.build()  // Configuration validation and container creation
container.initialize()           // State loading and background process startup

// Container is now ready for predictions and learning
val prediction = container.predict(context)
container.processInteraction(interactionData)

// Proper cleanup when done
container.saveState().join()
container.release()

Error scenarios and recovery:

• Configuration errors: Thrown immediately with detailed error messages

• Resource errors: May be deferred until initialize() is called

• Dependency errors: Validation catches most issues at build time

• Recovery strategies: Failed builds can be retried with corrected configuration

Thread safety and concurrency:

• Builder validation is single-threaded and not thread-safe

• Resulting container is designed for concurrent access from multiple threads

• All internal synchronization is handled by the container implementation

• Container lifecycle methods can be called from any thread

Memory and resource considerations:

• Container holds references to all provided dependencies

• Background resources are allocated during initialize(), not build()

• Proper cleanup requires calling release() when container is no longer needed

• Consider using weak references or lifecycle observers for automatic cleanup

See also

Throws