169 lines
4.4 KiB
Markdown
169 lines
4.4 KiB
Markdown
# Domain Model
|
|
|
|
The implementation-ready field, cardinality, mutability, deletion and cross-plane contracts are
|
|
normative in `M0_FOUNDATION_CONTRACTS.md`. The SQLAlchemy mapping and Alembic baseline are the
|
|
executable persistence form of this model.
|
|
|
|
## Core entities
|
|
|
|
### Model
|
|
|
|
Logical upstream model family/reference. Does not imply a downloadable or runnable artifact.
|
|
|
|
Important fields:
|
|
|
|
- stable internal ID
|
|
- display name
|
|
- upstream provider/source
|
|
- model family
|
|
- modalities/tasks
|
|
- parameter metadata
|
|
- upstream license metadata
|
|
|
|
### ModelRevision
|
|
|
|
An immutable upstream revision, preferably resolved to a concrete commit SHA.
|
|
|
|
Fields include:
|
|
|
|
- model ID
|
|
- upstream revision name supplied by discovery
|
|
- resolved commit SHA
|
|
- discovery timestamp
|
|
- upstream metadata snapshot
|
|
|
|
### ModelArtifact
|
|
|
|
Concrete downloaded files associated with a revision.
|
|
|
|
- storage location
|
|
- content digests
|
|
- serialization format
|
|
- size
|
|
- security state
|
|
- license state
|
|
- provenance
|
|
|
|
### DerivedArtifact
|
|
|
|
A locally generated quantization/conversion/merge derived from one immutable source artifact.
|
|
|
|
Examples:
|
|
|
|
- AWQ 4-bit
|
|
- GGUF Q4_K_M
|
|
- GGUF Q5_K_M
|
|
|
|
Derived artifacts must maintain lineage to their source.
|
|
|
|
### RuntimeProfile
|
|
|
|
The reproducible execution configuration:
|
|
|
|
- runtime type and version/image digest
|
|
- artifact variant
|
|
- quantization interpretation
|
|
- context policy
|
|
- concurrency/batch settings
|
|
- GPU-memory policy
|
|
- launch arguments
|
|
- environment constraints
|
|
|
|
### Deployment
|
|
|
|
Runnable combination of revision + artifact + runtime profile assigned to one or more capabilities/channels.
|
|
|
|
### Capability
|
|
|
|
Logical function requested by projects, such as `rag.embedding`, `vision.embedding` or `speech.transcription`.
|
|
|
|
### CapabilityContract
|
|
|
|
Versioned semantics for a capability:
|
|
|
|
- accepted input/output schema
|
|
- quality metrics
|
|
- required modalities/languages
|
|
- SLOs
|
|
- upgrade class
|
|
- migration compatibility
|
|
- fallback semantics
|
|
|
|
### Project
|
|
|
|
ModelForge consumer, e.g. ExampleRAG or ExampleVision.
|
|
|
|
### ProjectBinding
|
|
|
|
Maps a project to a capability contract and deployment channel, plus priorities, benchmark suites and migration support.
|
|
|
|
### ComputeNode
|
|
|
|
Machine capable of hosting one or more inference workers.
|
|
|
|
It has stable identity distinct from hostname, an observation source, agent protocol/version and
|
|
capabilities, central liveness state, heartbeat/inventory/telemetry timestamps, role/labels and
|
|
explicit production/lab/benchmark eligibility. Enrollment and node credentials are separate
|
|
hash-only security records; they are not node identity.
|
|
|
|
### Accelerator
|
|
|
|
GPU/accelerator attached to a compute node.
|
|
|
|
### ResourceEnvelope
|
|
|
|
Measured runtime behavior for a deployment under a test profile:
|
|
|
|
- context length
|
|
- concurrency
|
|
- cold/warm load time
|
|
- idle VRAM
|
|
- peak VRAM
|
|
- TTFT
|
|
- throughput
|
|
- p50/p95/p99 latency
|
|
- power/temperature
|
|
- OOM/failure behavior
|
|
|
|
### BenchmarkSuite
|
|
|
|
Versioned benchmark cases and scoring rules.
|
|
|
|
### BenchmarkRun
|
|
|
|
Immutable execution record tying a suite revision to a deployment and environment fingerprint.
|
|
|
|
### Experiment
|
|
|
|
Human-driven or automatic A/B comparison. May graduate individual cases into a benchmark suite.
|
|
|
|
### Recommendation
|
|
|
|
Advisor output with structured evidence, blockers, regressions, migration cost and confidence.
|
|
|
|
### Promotion
|
|
|
|
Audited action changing deployment channel state.
|
|
|
|
### Migration
|
|
|
|
Controlled process required when an upgrade changes persistent derived data or output schemas.
|
|
|
|
### AuditEvent
|
|
|
|
Append-only record of security-sensitive and operationally meaningful actions.
|
|
|
|
Audit events include actor, action, resource, outcome, correlation ID, UTC occurrence time, structured
|
|
details and previous/current event hashes. Update and delete are rejected by the persistence layer.
|
|
|
|
## Key invariants
|
|
|
|
1. Approved model revisions and artifacts are immutable.
|
|
2. Deployments reference immutable revision/artifact identities.
|
|
3. A project binds to a capability contract, not a path or model repository name.
|
|
4. Every stable deployment has local validation and benchmark evidence; M0 defines no production waiver.
|
|
5. `requires_reindex` changes must create a migration; direct promotion is invalid.
|
|
6. Deletion cannot proceed while a live binding, rollback target, migration, benchmark evidence, or lineage dependency requires the artifact.
|
|
7. Storage URIs are mutable locators; revision SHA and artifact digests are immutable identities.
|
|
8. Promotion and migration are distinct records and a promotion never implies completed data migration.
|