API Architecture¶
This section documents the public Python SDK surface and the internal API flows (SDK ↔ daemon ↔ StoreEngine ↔ Global Store) that implement registration, materialization, policy/persistence, and region-backed operations.
These docs are intended to answer, in order of importance:
- What the API/flow is (contract, semantics, invariants)
- Why it exists (tradeoffs, safety, performance, operational needs)
- How it works (RPC sequence, key data structures, and code map)
Reading Start Points¶
- Application user: API Design
- SDK maintainer: API Design → Registration Flow → Materialization Flow
- Daemon engineer: Registration Flow, Policy & Persistence, Region-Backed
- Global Store engineer: Policy & Persistence
- Core Store engineer: Registration Flow and Policy & Persistence
- Observability / on-call: Error, Retry, Observability
Document Map¶
- API Design: Public Python API surface, core concepts, and user-facing contracts.
- Registration Flow:
register/put/register_viewinternals and theBegin/Feed/Commitlifecycle. - Materialization Flow:
Artifactretrieval, source selection, selective materialization, andget_into/region-backed paths. - Policy & Persistence:
StorePolicymodel, placement planning, and persistence task lifecycle. - Region-Backed: VRAM region registration, region-referenced LIP, and quiesced teardown (
DeregisterArtifact). - Error, Retry, Observability: Error taxonomy, retry model, and key metrics/logging signals.
- Artifact Views and Retrieval: Canonical view semantics and retrieval architecture.
Concept Index¶
- Policy model and tier semantics: policy-persistence.md#storepolicy-model
- Durability and background tasks: policy-persistence.md#startpersistence-and-querypersistencestatus
- Registration RPC lifecycle: registration-flow.md#begin-feed-commit
- Region-backed LIP reuse: registration-flow.md#region-referenced-lip-storage
- Key mapping and
keymaterialization: materialization-flow.md#materialize-by-key-and-by-replica - Materialization source selection: materialization-flow.md#fallback-and-source-preference
- Region-backed
get_into: materialization-flow.md#region-backed-get_into-materializeintotarget-v2 - Status codes and retries: error-retry-observability.md#error-model
- View semantics and identity: artifact-views-and-retrieval.md