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

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

• 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

• 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.

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

var builder = WebApplication.CreateBuilder(args);

// Register Core contracts and minimal implementations
builder.Services.AddAIKernelCoreContracts();

// Inject user-provided Providers (example)
builder.Services.AddSingleton<IModelProvider, OpenAIModelProvider>();
builder.Services.AddSingleton<IVirtualFileProvider, GitVfsProvider>();

var app = builder.Build();
app.MapControllers();
app.Run();

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

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

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

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

• AIKernel.NET (contracts) prioritizes backward compatibility Breaking changes use major versions and migration steps documented in design/MIGRATION_GUIDE.md

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

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