Purpose

This guide shows dependency injection (DI) registration patterns, lifecycle guidance, and sample code for AIKernel.Core abstractions so integrators can replace Providers easily.

Scope

• Target: implementations referencing AIKernel.NET (contracts) and AIKernel.Core (abstractions)
• Audience: Provider implementers, service developers, operations engineers

Terms and assumptions

• Contracts layer (AIKernel.NET): contains interfaces, DTOs, Enums only
• Core (AIKernel.Core): provides abstract interfaces and minimal NoOp implementations; production implementations live in separate repos

Extension points (excerpt)

• IModelProvider: model inference interface. Singleton recommended.
• IRagProvider: retrieval (RAG) interface. Singleton recommended.
• IEmbeddingProvider: embedding generation. Singleton recommended.
• IVirtualFileProvider: Vfs abstraction (Git/S3/Blob). Singleton recommended.
• IScheduler: job scheduler. Singleton recommended.
• IEventBus: event delivery. Singleton recommended.

Lifecycle guidance

• Singleton: for thread-safe implementations that hold connections or models
• Scoped: for request-scoped state
• Transient: for lightweight utilities only

DI registration pattern (template)

var builder = WebApplication.CreateBuilder(args);\n\n// Register Core contracts and minimal implementations\nbuilder.Services.AddAIKernelCoreContracts();\n\n// Inject user-provided Providers (example)\nbuilder.Services.AddSingleton<IModelProvider, OpenAIModelProvider>();\nbuilder.Services.AddSingleton<IVirtualFileProvider, GitVfsProvider>();\n\nvar app = builder.Build();\napp.MapControllers();\napp.Run();

NoOp implementations

Core provides NoOp/Stub implementations for initial startup. NoOp is for test startup only; replace with production implementations in production.

Error handling and timeouts

• Providers must respect cancellation tokens
• Always set timeouts for network calls
• Retry policies are recommended to be controlled by the caller (Pipeline)

Security and authentication

• Store secrets in Vault/KMS; do not embed in code or images
• Inject credentials via DI or environment providers

Testing guidance

• Design interfaces to be mockable
• Automate integration tests using sample implementations
• Include NoOp-based minimal startup tests in CI

Version compatibility and migration

• AIKernel.NET (contracts) prioritizes backward compatibility

Breaking changes use major versions and migration steps documented in design/MIGRATION_GUIDE.md

References

• Design Intent
• AIKernel.Core/Docs/NOOP IMPLEMENTATION

Changelog

• 2026-05-01 Initial version
• v0.0.1 (2026-05-06): Version upgrade aligned with documentation guidelines