AI Cells

AI Cells

Purpose

This page defines the AI Cell, the core resource unit in OSAI.

Contents

• Definition
• Resource Contract
• Ownership Areas
• Lifecycle
• Telemetry

Definition

An AI Cell is a fixed-resource execution container for one app-local CPU-only AI agent or a tightly related group of workers.

An AI Cell is not a general process scheduler class. It is a resource contract with explicit ownership.

Resource Contract

Each AI Cell declares:

• CPU cores;
• memory arenas;
• model files and shared model-weight mappings;
• private KV/cache budget;
• NIC RX/TX queues;
• source-code index;
• build/test sandbox;
• Git workspace;
• telemetry counters;
• permissions and capabilities.

If the requested resources cannot be granted without violating another service contract, OSAI should refuse startup.

Ownership Areas

Core ownership means hot workers do not migrate by default.

Memory ownership means model arenas, KV/cache arenas, source indexes, build output, and network buffers are distinct and observable.

NIC queue ownership means app-agent traffic can stay on the intended core whenever hardware allows it.

Model-weight ownership means one physical read-only model copy can be mapped into many AI Cells while each agent keeps private KV/cache state.

Git/build/test ownership means code-changing agents work inside explicit workspaces and sandboxes.

Lifecycle

Example lifecycle:

DECLARED
  -> RESOURCES_GRANTED
  -> MODEL_MAPPED
  -> ARENAS_PREFAULTED
  -> WORKERS_PINNED
  -> READY
  -> RUNNING
  -> DRAINING
  -> STOPPED

After READY, the hot path should avoid scheduler migration, unexpected context switching, and page faults.

Telemetry

Minimum counters:

• core migration count;
• context switch count;
• post-warmup page fault count;
• RX/TX latency percentiles;
• model arena faults;
• memory bandwidth pressure;
• build/test resource usage;
• rollback count.

Related Pages

• Scheduler and Core Isolation
• Memory System
• Networking