Runtime and storage

Data directory

The configured directory contains:

• swapai.sqlite and its WAL files;
• immutable runner bundles and manifests;
• candidate and promoted model artifacts;
• the managed local Needle runtime and caches when local inference or training is used.

Transient training bundles are removed after every completed or failed request.

The managed Needle virtual environment, uv-managed Python installation and dependency caches all live below the persistent data directory. If an older deployment leaves a virtual-environment directory whose Python executable is missing, SwapAI replaces that stale environment before installing Needle. One-shot controller containers can therefore reuse a healthy runtime without leaving broken symlinks to an ephemeral filesystem.

Mount it on persistent storage with SQLite-compatible locking. Losing the directory loses datasets, run history and models.

Model identity

Every candidate has one digest over its complete artifact. Numeric candidates include the .cact model and number-label sidecar. SwapAI checks the artifact before evaluation, promotion and loading.

Model metadata records the exact Needle and SwapAI runner versions. Incompatible artifacts are not loaded as though they were current.

Database migrations

createClassifier() migrates supported historical schemas transactionally. Automatic migration is idempotent and uses durable exposure evidence to decide whether legacy rows can be assigned across all four purposes or must stay in the historical training/validation split. An explicit, attested held-out migration is a separate offline operation. See Legacy examples.

The classifier monitor uses a read-compatible path: it can inspect older databases without mutating them. Application initialization is the explicit migration boundary.

Back up the data directory before a major-version upgrade. Do not run two SwapAI versions against the same directory during migration.

Multiple processes

SQLite uses WAL mode and a busy timeout. Durable leases prevent duplicate training. Process heartbeats distinguish a saved model from a currently loaded application.

Do not place the database on a network filesystem that cannot provide SQLite locking. For distributed applications, put collection behind one service or implement a storage adapter with equivalent transactional guarantees.

Shutdown and restart

await classifier.close();

Close finishes queued collection and releases local resources. External runs remain durable. After restart, call reconcileTraining() to use each recorded provider ID, run start time and configured runtime ceiling to recover its status and finish cleanup safely.