AIKernel.NET

AIKernel is an operating system for AI applications.

AIKernel does not define features themselves.
It defines deterministic execution context in which features become inevitable.

This repository manages the canonical contract set of AIKernel.

AIKernel.NET is a contract-first foundation that treats LLMs not as simple APIs, but as capability-bearing processes.

---

NuGet Packages

AIKernel.NET is composed of multiple independent abstraction layers.
Each layer is published as a separate NuGet package.

Layer	Package	Version	Link
Core Types	AIKernel.Enums		https://www.nuget.org/packages/AIKernel.Enums/
Data Models	AIKernel.Dtos		https://www.nuget.org/packages/AIKernel.Dtos/
Contracts	AIKernel.Contracts		https://www.nuget.org/packages/AIKernel.Contracts/
Abstractions	AIKernel.Abstractions		https://www.nuget.org/packages/AIKernel.Abstractions/
Virtual File System	AIKernel.VFS		https://www.nuget.org/packages/AIKernel.VFS/
Context Models (integrated)	AIKernel.Dtos (AIKernel.Dtos.KernelContext)		https://www.nuget.org/packages/AIKernel.Dtos/
Event Models (integrated)	AIKernel.Dtos (AIKernel.Dtos.Events)		https://www.nuget.org/packages/AIKernel.Dtos/

---

See docs/design/DESIGN_INTENT.md for design philosophy.
For executable contracts (spec sheets), see docs/specs/index.md.

Hosting Example (C#)

AIKernel.NET is integrated into ASP.NET Core DI.
By composing Core, Provider, and Governance, you can host an AI execution platform.

Because AIKernel.NET is interface-contract based, implementations can be replaced freely.

Example Implementation

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAIKernelCore(options =>
{
    options.EnableDeterministicReplay = true;
    options.FailClosed = true;
});

builder.Services.AddModelProvider<OpenAIModelProvider>();
builder.Services.AddVfsProvider<GitVfsProvider>();

builder.Services.AddSignatureTrustStore<FileSignatureTrustStore>();

builder.Services.AddControllers();

var app = builder.Build();

using (var scope = app.Services.CreateScope())
{
    var kernel = scope.ServiceProvider.GetRequiredService<IAIKernel>();
    await kernel.InitializeAsync();
}

app.MapControllers();
app.Run();

Target experience (boot log example):

[KERNEL] Initializing AIKernel.NET v0.1.0...
[KERNEL] Loading ISignatureTrustStore... [OK]
[KERNEL] Mounting VFS (Git: ./context)... [OK]
[KERNEL] Verifying System Prompt Signature... [VALID]
[KERNEL] Routing to Provider: [[provider.reasoning.high]]... [OK]

> Hello Intelligence.
> The Semantic Context is stable. Governance is active.
> This boot sequence is deterministic and verifiable.

API Example / curl

AIKernel can be exposed as an OpenAI-compatible API.
Below is a minimal execution example.

curl -X POST http://localhost:5000/v1/execute \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "reasoning",
    "input": "Hello Intelligence",
    "context": {
      "vfs": "git://./context"
    }
  }'

Response Example

{
  "output": "[OpenAI] Hello Intelligence",
  "provider": "openai",
  "capability": "reasoning",
  "context": {
    "vfs": "git://./context"
  }
}

---

1. Purpose

AIKernel.NET aims to provide an OS that enables AI applications with:

• capability-based execution independent of model names
• category separation to maximize inference purity
• deterministic scheduler + nondeterministic LLM hybrid control
• reproducibility (Deterministic Replay)
• governance (signed PromptRules / audit logs)
• OS-like extensibility (Provider = driver / Kernel = execution engine)

---

2. Architecture Overview

AIKernel.NET defines abstract contracts and provides minimal DTOs/Enums.
By fully separating implementation, it preserves Core purity and maximizes implementation flexibility.

AIKernel architecture layers (OS-like):
Core (syscall)
Kernel (AI OS core)
Providers (brain drivers)
VfsProviders (external data sources)
Server (external API adapter)
Hosting (app integration)
Enterprise (operations extensions)

Documentation is organized into four layers:

• docs/architecture: Why (principles, theory, governance)
• docs/design: How (design decisions and implementation strategy)
• docs/specs: What (executable contracts and verifiable requirements)
• docs/guidelines: operational and contribution rules

---

3. Documentation Structure

To keep documentation and source synchronized, this README intentionally avoids deep file-by-file listings.

The documentation is organized into four foundational categories:

• docs/architecture — Why (principles, invariants, governance)
• docs/design — How (design decisions and implementation strategy)
• docs/specs — What (normative contracts and acceptance criteria)
• docs/guidelines — Rules (repository and contribution policies)

For the latest structure and cross-links, use:

• docs/index.md
• docs/index-jp.md

Repository mapping

Repository	Contained solutions/projects	Example directories	Artifacts	Main dependencies
AIKernel.NET	Contracts layer (shared)	Contracts (Interfaces; DTO; Enums)	NuGet contract packages	none (top-level contracts)
AIKernel.Core	Core platform	Core/, Kernel/, Providers/, VfsProviders/, Server/, Hosting/	NuGet libraries	AIKernel.NET
AIKernel.SDK	Client libraries	AIKernel.SDK	NuGet client packages	AIKernel.NET, AIKernel.Core
AIKernel.Web	Admin console	admin-web (SPA/Blazor)	SPA build artifacts	AIKernel.NET, AIKernel.Core
AIKernel.Infra	Deployment definitions	terraform/, k8s/, helm/	Manifests	all repos
AIKernel.Tools	Dev tools & CI templates	cli/, generators/, ci-templates/	CLI binaries; CI templates	all repos
AIKernel.Docs	Documentation aggregation	architecture/, runbooks/	Documentation site	all repos
AIKernel.Enterprise	Enterprise solutions	solutions/, services/, workers/, charts/	Private container images; Helm charts	AIKernel.NET, AIKernel.Core, AIKernel.Infra

---

4. Design Principles

4.1 Category separation (most important)

• Orchestration (inference)
• Expression (output shaping)
• Material (external data)
• History
• Style

Do not mix these categories.

"Information passed to an LLM must not be mixed into a single context." — CATEGORY_SEPARATION_PRINCIPLES.md

---

4.2 Preprocessing-first

Prompts are the final formatting step.

Inference quality is determined by preprocessing structure. — PREPROCESSING_VS_PROMPTING.md

---

4.3 Attention pollution prevention

Mixing examples, RAG, and history breaks inference.

When attention is drawn to surface structures, inference halts. — ATTENTION_POLLUTION_THEORY.md

---

4.4 LLM as suggestor, PDP as decision-maker

LLM is a suggestor; PDP makes final decisions.

4.5 Signed Prompt Governance and Fail-Closed

Prompts carry authority equivalent to code execution.
AIKernel executes only approved, signed prompts and halts immediately when tampering or untrusted signers are detected.

• Verification sequence: IPromptRepository -> IPromptVerifier -> ISignatureTrustStore -> IPromptValidator -> ExecutionPipeline
• Detailed spec: docs/specs/02.SIGNED_PROMPT_GOVERNANCE_SPEC.md

4.6 Relation-Oriented Data Structure (Relation-Oriented Markdown: ROM)

AIKernel treats knowledge not as linear text but as a set of relations.

• YAML: Defines entity metadata and identity.
• Headings: Define semantic categories and contextual scopes.
• Bullets: Declaratively express facts and properties.
• Links ([[id]]): Represent graph edges between entities.
• Semantic Hash: Uses order-insensitive canonical hashing to strengthen signature verification.

With ROM, human-authored notes can be transformed directly into an LLM-reasonable knowledge base.

4.7 Git-Managed Reasoning (ConversationStore)

AI conversations are managed not as linear logs but as tree-structured Git commits.
This natively supports reasoning forks and point-in-time replay.

---

5. Kernel (formerly Runtime)

Kernel is the core OS:

• TaskManager (deterministic scheduler)
• LlmController (nondeterministic inference)
• ProviderRouter (capability-based brain selection)
• RagEngine (materialization)
• PipelineExecutor (DAG execution)
• RulesEngine (PromptRules)
• IPromptVerifier / IPromptValidator (runtime signature verification for fail-closed enforcement)
• ISignatureTrustStore (trust anchor managing trusted signers and revocation state)

---

6. Providers (brain drivers)

Providers declare Capabilities rather than model names:

• chat
• embedding
• multimodal
• reasoning
• vector-search
• streaming

Providers are extensible via SDKs.

---

7. VFS Providers (Git, etc.)

Treat Git as an external data source (VFS), not a Provider.

---

8. Server (OpenAI-compatible API)

Adapter to expose AIKernel as an OpenAI-compatible API.

---

9. Hosting

• DI
• default pipelines
• configuration
• app integration

---

10. Enterprise

• SIEM integration
• multi-tenant support
• SLO dashboards

---

11. License / Contribution

• PR-based contributions
• Explicit compatibility for Contracts and PromptRules
• Attach migration guides for breaking changes

---

12. Final Note

AIKernel.NET provides a structurally correct AI execution platform as an OS. It aims to be the standard OS for AI applications by focusing on category separation, preprocessing-first design, governance, and reproducibility.

For implementation, lock contracts first by following docs/specs/index.md, then apply implementation strategy from docs/design.