AIKernel.NET Core is a runtime designed to solve three core problems in LLM applications: context drift, lack of reproducibility, and lack of governance.
It is the implementation of a deterministic and immutable Knowledge OS designed for the .NET ecosystem.
It is not merely an LLM wrapper.
AIKernel.NET Core provides a robust execution foundation for managing knowledge assets (ROM), governing context (Context), and treating inference execution as a controlled transaction.
AIKernel.NET Core operates according to the following three canonical principles.
If a signature mismatch, governance rejection, or token budget violation occurs, AIKernel does not allow incomplete success.
Execution stops immediately.
Every inference context is fixed by ContextHash and PromptHash.
Given the same input and execution environment, AIKernel aims to reproduce the same execution context.
The goal is not to make the LLM itself fully deterministic.
The goal is to make the execution process around the LLM reproducible, inspectable, and governable.
Loaded knowledge assets (ROM) and generated execution results (IExecutionResult) are treated as immutable DTOs while flowing through the system.
Once materialized, objects are not modified in place.
AIKernel.NET Core is designed as an OS-like layered runtime.
+-----------------------------+
| Hosting Layer | .NET application integration
+-----------------------------+
| Kernel Layer | Governance and orchestration
+-----------------------------+
| Core Layer | Pure logic: VFS / ROM / Context / Execution
+-----------------------------+
| Provider Layer | External model and service boundaries
+-----------------------------+
This repository consists of runtime, provider, and verification layers.
src/
AIKernel.Common
AIKernel.Core
AIKernel.Kernel
AIKernel.Hosting
Providers/
AIKernel.Providers.MicrosoftAI
tests/
AIKernel.TestKit
AIKernel.Core.Tests
AIKernel.IntegrationTests
python/
AIKernel.Python
Functional primitives shared by the runtime family.
It contains pure Result / Option / Either helpers and does not depend on AIKernel runtime DTOs, providers, hosting, or kernel implementations.
A pure logical engine responsible for the phase transition of knowledge.
VFS → ROM → Context → Execution
This layer owns the Core runtime logic and separates implementation concerns from external Hosting and Provider boundaries.
It also defines OS-independent IMemoryRegion / IMemoryMapper
abstractions for Native Capability modules. The abstractions live in Core while
the concrete Win32/POSIX mapping implementations live in Kernel.
The governance and orchestration layer of the OS.
It exposes the IKernel Facade and integrates all runtime layers.
It also supplies the default OS-specific IMemoryMapper implementation used by
trusted hosts.
The ignition switch for .NET applications.
It provides IServiceCollection extensions and default wiring for ASP.NET Core / Generic Host.
Provider implementations that connect AIKernel to external models and external services.
An OpenAI-compatible Provider implementation based on Microsoft.Extensions.AI (MEAI).
It uses Microsoft’s AI abstraction layer to accelerate development while preserving AIKernel’s Capability-based execution model.
A Contract Test Framework for verifying ABI and behavioral discipline.
It provides the foundation for validating that downstream implementations comply with AIKernel contracts.
Unit tests for internal runtime logic.
Integration tests that pass through multiple runtime layers.
A thin Python binding for AIKernel.Core functional primitives and managed assembly discovery.
It installs as the aikernel-net Python package and is CPU-only by default. The
package exposes Python monad helpers and managed assembly discovery; it does not
ship CUDA, LibTorch, or the native libtorch_bridge ABI. The Python package
does not reimplement OS-specific memory mapping, Kernel internals, or Capability
internals.
dotnet add package AIKernel.Core --version 0.0.5
dotnet add package AIKernel.Hosting --version 0.0.5
dotnet add package AIKernel.Kernel --version 0.0.5
dotnet add package AIKernel.Providers.MicrosoftAI --version 0.0.5For direct use of functional primitives and contract testing helpers:
dotnet add package AIKernel.Common --version 0.0.5
dotnet add package AIKernel.TestKit --version 0.0.5CUDA is optional and lives outside this repository. GPU hosts should install an
external Capability package such as AIKernel.Cuda13.0.Libtorch2.12.win-x64
explicitly. CUDA Capability packages may use split distribution: NuGet.org
contains a small metadata package, while the full runtime package with
LibTorch/CUDA/native payloads is attached to the matching Capability GitHub
Release. For CUDA execution, download the full .nupkg, add its folder as a
local NuGet source, and install from that source:
dotnet nuget add source <folder-containing-full-cuda-nupkg> --name AIKernel-CUDA
dotnet add package AIKernel.Cuda13.0.Libtorch2.12.win-x64 --version 0.0.5 --source <folder-containing-full-cuda-nupkg>LLM / SLM developers who need direct CUDA integration should read docs/development/cuda-capability-development-guide.md. Other CUDA versions, model runtimes, or Linux CUDA hosts should fork the CUDA Capability repository and publish a separate Capability module.
For the optional Python language binding:
pip install aikernel-netThe base Python package is a CPU-only universal py3-none-any wheel for
Windows and Linux. Use NuGet packages from C# hosts, and use the aikernel-net
distribution from Python hosts. Import it as aikernel_net. The PyPI package
named aikernel is a different project. GPU/native runtimes remain explicit
Capability installs.
Stable Python releases are published to PyPI as aikernel-net. Development
builds may be published separately through GitHub Packages as
aikernel-net-dev for CI/CD validation.
For source-based local validation, install from the repository subdirectory:
pip install git+https://github.com/AIKernel-NET/AIKernel.Core.git#subdirectory=pythonThe default Python install is CPU-only/CUDA-free and does not include a native bridge. Install GPU integrations from the matching external Capability package and follow that Capability repository's distribution instructions.
The v0.0.5 package family is aligned with the AIKernel.NET contract packages
AIKernel.Abstractions, AIKernel.Dtos, and AIKernel.Enums v0.0.5.
AIKernel.Vfs is no longer a separate package dependency; the VFS contracts are
provided by AIKernel.Abstractions. The AIKernel.Vfs namespace remains as a
Core implementation namespace for in-process VFS providers and stores; it is not
a separate NuGet package.
Use the Server/API host to hold model credentials and execute OpenAI-compatible providers. Keep browser/WASM clients behind your own API boundary; do not place model API keys in a WebAssembly client.
builder.Services
.AddAIKernelCore(builder.Configuration)
.WithOpenAI(
builder.Configuration.GetSection("AIKernel:Providers:OpenAI"),
(sp, options) =>
{
// Return an IChatClient from Microsoft.Extensions.AI.
// The provider package registers default capabilities and prompt
// capability metadata for the configured ProviderId and ModelId.
return CreateChatClient(options);
});
builder.Services.AddAIKernelKernel();Example configuration:
{
"AIKernel": {
"Providers": {
"OpenAI": {
"ProviderId": "openai-compatible",
"ModelId": "gpt-4.1-mini",
"SecretKeyName": "OpenAI:ApiKey",
"MaxInputTokens": 8192,
"MaxOutputTokens": 1024
}
}
},
"OpenAI": {
"ApiKey": "<store this in user-secrets, Key Vault, or environment configuration>"
}
}For browser/WASM-oriented clients, register only browser-safe VFS providers in the client-side service collection:
services.AddAIKernelBrowserVfsProviders();Use AddAIKernelCoreVfsProviders only in trusted server or desktop hosts where
local filesystem access is expected.
When a host registers external capability modules or model providers, select the
provider through request metadata using KernelFacadeMetadataKeys.ProviderId.
This avoids hard-coded metadata strings across AIKernel.Tools, AIKernel.RH, and
other provider packages.
External provider packages can attach either assembly-referenced providers or
process-backed adapter providers through WithModelProvider<TProvider>. The
extension registers the IModelProvider implementation and its
ModelPromptCapability entries together, so the static resolver can bind the
selected ProviderId and ModelId without provider-specific wiring in Core.
For contract-level external Capability modules, Core registers an in-memory
ICapabilityModuleRegistry and a fail-closed ICapabilityModuleInvoker by
default. Hosts can register module descriptors for CLI, assembly-referenced,
native, DSL ROM, or remote modules without granting execution by accident.
Actual module execution should be supplied by a trusted Tools, Provider, or
host package that replaces the default invoker.
GPU and Native ABI implementations are external Capability packages. For
example, AIKernel.Cuda13.0.Libtorch2.12.win-x64 owns its native bridge, runtime version metadata,
and CUDA-specific implementation while conforming to AIKernel Capability
contracts.
For trusted hosts, AddAIKernelKernel() registers an OS-specific
IMemoryMapper (Win32MemoryMapper on Windows, PosixMemoryMapper elsewhere)
behind the Core memory abstraction. Native Capability packages consume only the
Core abstraction and never reference Kernel directly.
User-land routing pipelines can return a KernelProviderRoutingDecision from a
ResultStep/LINQ chain, then apply it to a KernelRequest and its metadata.
This supports policies such as low-tier versus high-tier LLM selection, or
routing aik... contexts to a CLI-backed capability adapter, while keeping
Kernel execution driven by the same ProviderId / ModelId contract.
AIKernel.Core also includes a standard JSON DSL pipeline runtime for
AI-generated plans. The DSL compiles to deterministic ResultStep pipelines,
supports finite Loop / LoopUntil / Suspend nodes, and can be saved as DSL
ROM under rom/dsl/{namespace}/{name}.json for later invocation through
dsl://{namespace}/{name}. The canonical schema and operational rules are
documented in AIKernel.NET as docs/architecture/18.DSL_PIPELINE_AND_ROM_SPEC.md.
Compiled DSL pipelines also support C# LINQ query composition. Select and
passing where predicates are pure projections and do not append replay nodes;
SelectMany executes the next DSL pipeline with the previous output as input
and concatenates the ResultStep replay log. Failed where predicates are
recorded as deterministic reject nodes.
IKernelPipeline observe = compiler.Compile(observeDocument).Value!;
IKernelPipeline decide = compiler.Compile(decideDocument).Value!;
IKernelPipeline agent =
from first in observe
where first.Data["last_capability"] == "Observe"
from second in decide
select second.With(
"route",
$"{first.Data["last_capability"]}->{second.Data["last_capability"]}");
var result = agent.Execute(DslPipelineExecutionContext.Create());Chat histories can also be fixed as immutable HistoryROM assets. Use
HistoryRomStore.SaveHistoryAsRomAsync to convert ordered chat records into a
signed Markdown ROM, store it in VFS under rom/history/{namespace}/{name}.md,
and register it as history://{namespace}/{name}. Loading a HistoryROM uses the
same ROM signature verification path as other Core ROM assets and rejects hash
mismatches or attempts to overwrite an existing history path with different
content.
[KERNEL] Initializing AIKernel.NET Core v0.1.0...
[KERNEL] Loading VFS Provider: local... [OK]
[KERNEL] Mounting ROM root... [OK]
[KERNEL] Building ContextSnapshot... [OK]
[KERNEL] Computing ContextHash... [OK]
[KERNEL] Resolving Provider: microsoft-ai.openai-compatible... [OK]
[KERNEL] Executing governed inference... [OK]
> Hello Intelligence.
> The Semantic Context is stable.
> Execution is reproducible. Governance is active.
In the minimal implementation, AIKernel.NET Core follows the execution path below.
KernelRequest
→ VFS Mount
→ ROM Load
→ Context Build
→ Governance Check
→ Prompt Composition
→ Provider Execution
→ IExecutionResult
In the initial implementation phase, prompt composition may be simplified and static.
Advanced Governance, signature enforcement, Semantic Cache, and Deterministic Replay will be expanded incrementally.
This phase sets up the initial AIKernel.Core repository.
Based on the Contracts / DTO / Enum packages established in AIKernel.NET, this repository prepares the basic structure for the Core implementation.
- Create the repository structure
- Set up basic project templates
- Prepare the initial
src/andtests/layout - Define the project skeletons for Core / Kernel / Hosting / Provider / Tests
- Organize dependencies on AIKernel.NET contract packages
The purpose of this phase is not to complete an executable Kernel.
The goal is to prepare a foundation that allows future Core implementation to proceed without ambiguity.
During the v0.0.x phase, Core runtime components will be implemented incrementally toward v0.1.0.
Based on the Canonical Contracts fixed in v0.0.1, minor refinements may be made to naming, API boundaries, and test structure where needed for implementation consistency.
- Incremental implementation of Core runtime components
- Foundation for VFS / ROM / Context / Provider integration
- Minimal implementation for mounting local files as VFS
- Loading ROM files and transforming them into Context
- Minimal execution path using static Prompt Composition
- Initial implementation of the MicrosoftAI Provider wrapper
- Initial Hosting / DI wiring
- Unit Test / Integration Test skeletons
- API, naming, and contract-boundary refinements toward v0.1.0
The purpose of this phase is not to fully implement Governance or Deterministic Replay.
The first goal is to confirm that AIKernel.Core can provide the following minimal execution path.
VFS → ROM → Context → Static Prompt → Provider → IExecutionResult
v0.1.0 is the first executable runtime release of AIKernel.Core.
It integrates the Canonical Contracts established in AIKernel.NET v0.0.1 into an executable form through Core implementation, Provider integration, and tests.
This is the Core-side realization of Synthesis: Executable Contracts defined in Issue #6.
- Minimal Core runtime
- VFS-based ROM loading
- ContextSnapshot foundation
- MicrosoftAI Provider wrapper
- Initial Hosting integration
- First executable path from ROM to inference
- Basic generation of
IExecutionResult - Output of
ContextHash - Connection to Contract Test skeletons
The purpose of this release is not to implement the entire AIKernel.NET philosophy all at once.
The purpose is to prove, with a minimal configuration, that AIKernel can load knowledge, construct context, and execute inference through a Provider.
AIKernel.Core development proceeds based on the Canonical Contracts defined by AIKernel.NET.
AIKernel.NET defines the contracts.
AIKernel.Core proves them through implementation.
During the v0.0.x phase, Core runtime components will be implemented incrementally and integrated as the first executable runtime in v0.1.0.
This roadmap preserves the progression established by the existing AIKernel.NET release notes and Issue #6:
Init → Fix → Synthesis
It concretizes that progression on the Core implementation repository side.
AIKernel.NET Core depends on the canonical contract packages defined in the main AIKernel.NET contract repository.
AIKernel.NET
= contracts, DTOs, enums, documentation, contract-test skeletons
↓
AIKernel.Core
= concrete runtime implementation and standard providers
↓
AIKernel.Providers.*
= external model and service integrations
AIKernel.NET defines the contracts.
AIKernel.Core proves them through implementation.
Apache License 2.0.
See the LICENSE file for details.