Initial public ModelForge release
This commit is contained in:
Jens
@@ -0,0 +1,101 @@
|
||||
# M0 Foundation Contracts
|
||||
|
||||
This document is the implementation-level boundary for M0. The executable forms live in
|
||||
`domain/contracts.py`, `domain/lifecycle.py`, `persistence/models.py`, the Alembic baseline,
|
||||
and validated manifests under `config/`.
|
||||
|
||||
## Product and trust boundaries
|
||||
|
||||
| Plane | Owns | Must not own |
|
||||
|---|---|---|
|
||||
| Control plane | registry, policy, provenance, lifecycle decisions, audit, evidence | inference execution or arbitrary hub code |
|
||||
| Gateway | project authentication, capability/channel resolution, QoS, normalized errors | direct artifact selection by projects |
|
||||
| Runtime plane | adapter-governed load/probe/infer/unload against approved read-only artifacts | public endpoints, project/HF secrets, Docker socket, default egress |
|
||||
| Hardware plane | node/accelerator identity, inventory and measured telemetry | lifecycle or routing decisions |
|
||||
| Hugging Face boundary | discovery metadata and quarantined acquisition by exact revision | approval, deployment or trust decisions |
|
||||
| Project boundary | declares versioned capabilities, SLO, priority, fallback and migration support | model repository names, paths or runtime endpoints |
|
||||
| Runtime-engine boundary | implements the internal adapter contract | leaking engine-specific behavior into capability contracts |
|
||||
|
||||
ModelForge is not a cloud-AI broker, Kubernetes platform, training cluster, generic chatbot,
|
||||
or public multi-user inference service. There is no implicit cloud fallback.
|
||||
|
||||
## Identity, cardinality and lifecycle
|
||||
|
||||
- IDs are UUIDs in persistence; manifest keys are stable human-readable identities.
|
||||
- `Model 1—N ModelRevision 1—N ModelArtifact 1—N DerivedArtifact` preserves source lineage.
|
||||
- A `Deployment` references exactly one revision, exactly one source-or-derived artifact and an
|
||||
immutable runtime profile. Composite foreign keys prevent the artifact revision from diverging.
|
||||
- `Capability 1—N CapabilityContract`; project bindings reference a contract version and channel,
|
||||
never a model.
|
||||
- `ComputeNode 1—N Accelerator`; leases and envelopes remain node-ready while M1/M6 optimize for one GPU.
|
||||
- Benchmark runs, promotions, migrations and lineage references use restrictive deletion. Lifecycle
|
||||
removal is deprecation followed by dependency-checked archival; it is never cascade cleanup.
|
||||
- Approved revisions, verified artifacts, runtime profiles, benchmark runs, promotions and audit events
|
||||
are immutable records. Mutable labels and operational status are separate fields.
|
||||
- All timestamps are timezone-aware UTC database timestamps.
|
||||
|
||||
## Capability and project contract
|
||||
|
||||
Capability contracts version JSON input/output schemas, modalities, language support, streaming,
|
||||
structured output, vector dimensionality/normalization semantics, SLOs, quality metrics, upgrade
|
||||
class, fallback, privacy and resource requirements. Vector-producing contracts with unproven
|
||||
cross-deployment compatibility are rejected unless classified `requires_reindex`.
|
||||
|
||||
Project manifests select a capability contract version plus stable/candidate/experimental channel,
|
||||
priority, optionality, explicit fallback, migration support, project SLO and benchmark suites.
|
||||
The strict schemas reject unknown fields, including attempts to add a concrete model ID.
|
||||
|
||||
## Artifact proof
|
||||
|
||||
The reproducibility chain is:
|
||||
|
||||
`upstream repository + resolved commit SHA → filename/type + SHA-256 → optional source digest +
|
||||
derivation tool/version/arguments → runtime-profile fingerprint → deployment → benchmark run`.
|
||||
|
||||
Storage locations are locators, not identities. The digest and immutable lineage provide identity.
|
||||
A derived artifact is invalid without its source digest and conversion tool/version.
|
||||
|
||||
## Runtime adapter contract
|
||||
|
||||
An adapter validates a runtime profile, probes layered health, loads only under a scheduler lease and
|
||||
unloads by deployment identity. Profiles capture runtime type/version, image digest, artifact digest,
|
||||
quantization, context, concurrency, launch arguments, environment constraints and security toggles.
|
||||
The control plane depends on this protocol rather than vLLM, Transformers, Diffusers or llama.cpp.
|
||||
Concrete adapters belong to M5.
|
||||
|
||||
## Scheduler contract
|
||||
|
||||
Lease requests carry deployment, priority, residency (`always_warm`, TTL-based `keep_warm`,
|
||||
`load_on_demand`, `exclusive`, `lab_only`), measured resource envelope, warm TTL, exclusivity and
|
||||
explicit CPU-fallback permission. Envelopes are scoped by accelerator kind, context, concurrency and
|
||||
batch size and include idle/peak VRAM plus safety margin. A lease moves through requested/acquired/
|
||||
released state. Failure must release reservations and emit a structured event. M6 implements policy;
|
||||
M0 does not pretend to schedule work.
|
||||
|
||||
## Benchmark comparability
|
||||
|
||||
A run binds deployment, revision SHA, artifact digest, runtime/version/image, launch arguments,
|
||||
suite and dataset revisions, CUDA, driver, accelerator identity, context, concurrency, seed,
|
||||
timestamps and a deterministic environment digest. Runtime, driver/CUDA, accelerator or launch
|
||||
profile changes make cross-environment comparisons non-comparable. Historical evidence is retained
|
||||
with a stale reason; it is never rewritten.
|
||||
|
||||
## Promotion and migration
|
||||
|
||||
Promotion is a human-approved routing/lifecycle action backed by verified artifact state, local and
|
||||
project benchmark IDs and a rollback deployment. Migration is separate. For embeddings, promotion is
|
||||
blocked until a migration is `ready` after: current index → distinct shadow index → backfill →
|
||||
validation → shadow queries/benchmarks → atomic cutover. The prior index and deployment remain until
|
||||
the recorded rollback-retention deadline.
|
||||
|
||||
## Failure ownership and health
|
||||
|
||||
The normalized codes are `MODEL_LOAD_FAILED`, `GPU_OOM`, `RUNTIME_CRASH`, `TIMEOUT`,
|
||||
`INVALID_OUTPUT`, `HEALTHCHECK_FAILED`, `ARTIFACT_CORRUPT`, `DRIVER_ERROR` and
|
||||
`CAPABILITY_UNAVAILABLE`. Runtime adapters own load/crash/output faults; the scheduler owns capacity,
|
||||
OOM reservation and lease recovery; the gateway owns timeout and approved fallback/degrade behavior;
|
||||
the control plane owns artifact corruption, deployment blocking and audit; an operator owns explicit
|
||||
security exceptions and hard production promotion decisions. Retries must be bounded and observable.
|
||||
|
||||
Health is reported separately for process, runtime, model smoke inference, capability contract/routing,
|
||||
and required project capabilities. Process liveness alone cannot make a deployment healthy.
|
||||
Reference in New Issue
Block a user