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.

Manifest Example

[service]
name = "smart-app-agent"
binary = "/apps/smart-app-agent/bin/agent"

[cores]
network = "2"
inference = "3-6"
source_index = "7"
build_test = "8-11"
migration = "forbidden"

[memory]
model_arena = "shared"
kv_cache_arena = "private"
prefault = true
swap = false
post_ready_page_faults = "fail_cell"

[network]
ports = [8080]
rx_queues = "owned"
tx_queues = "owned"

[git]
repository = "/srv/apps/example"
worktree = "/srv/worktrees/example-agent"
allow_commit = true
allow_push = false
require_tests = true

Hot-Path Invariants

core_migrations = 0
involuntary_context_switches = 0
post_ready_page_faults = 0
timer_ticks_on_hot_cores = 0
interrupts_on_hot_cores = 0 unless declared

Fault Behavior

Fault handling depends on policy:

• hot-path page fault after READY: record counter, drain the cell, and fail the request unless explicitly allowed;
• invalid memory access: stop the cell and preserve crash telemetry;
• build/test failure: keep the patch in the worktree, mark it failed, do not deploy;
• Git conflict: stop before commit/push and require human or policy resolution;
• model arena fault: stop dependent cells or remap only through the control plane.

Patch, Rebuild, and Redeploy

An AI Cell may run source-index, patch, build, test, and deploy workers, but those workers should use declared cores and separate memory arenas. A successful patch flow creates a rollback point before hot reload or redeploy.

Stop and Restart

Stopping a cell drains network queues, stops hot workers, releases core leases, preserves logs and telemetry, and optionally keeps the Git worktree. Restarting requires resource validation again; no previous lease is assumed valid.

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