cherenkov/model/index/
records.rs

1use crate::model::ModelDescription;
2use serde::{Deserialize, Serialize};
3use std::{collections::BTreeMap, path::PathBuf};
4
5/// Catalog identity, source lineage, and selected artifacts for one model.
6#[derive(Clone, Serialize, Deserialize)]
7pub struct ModelEntry {
8    /// Stable catalog ID accepted directly as a model selector.
9    pub id: String,
10    /// Optional unique alias accepted directly as a model selector.
11    pub name: Option<String>,
12    /// Original source location and the identity recorded at registration.
13    pub source: Source,
14    /// Source description captured at registration.
15    pub description: ModelDescription,
16    /// Selected prepared artifact ID, if preparation has been published.
17    pub prepared: Option<String>,
18    /// Retained source artifact ID, if the index tracks a local source copy.
19    pub retained_source: Option<String>,
20}
21
22/// Source identity used to recognize repeat registration and verify local imports.
23#[derive(Clone, Serialize, Deserialize)]
24#[serde(tag = "kind", rename_all = "snake_case")]
25pub enum Source {
26    /// Local checkpoint inspected at registration.
27    Local {
28        /// Canonical source path.
29        path: PathBuf,
30        /// File metadata and configuration fingerprint, not a digest of all weights.
31        fingerprint: String,
32    },
33    /// HF repository pinned to an immutable commit.
34    HuggingFace {
35        /// Repository identifier in `owner/name` form.
36        repo: String,
37        /// Full commit hash resolved during registration.
38        revision: String,
39        /// Hub endpoint used to inspect and later download this source.
40        endpoint: String,
41    },
42}
43
44/// An artifact's role in a model's preparation lifecycle.
45#[derive(Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
46#[serde(rename_all = "snake_case")]
47pub enum ArtifactKind {
48    /// Weights and metadata prepared for the inference engine.
49    Prepared,
50    /// Source checkpoint retained for future preparation.
51    Source,
52}
53
54/// Catalog record for an owned directory or a caller-owned external location.
55#[derive(Clone, Serialize, Deserialize)]
56pub struct Artifact {
57    /// Stable ID used by model references and artifact lease locks.
58    pub id: String,
59    /// Prepared output or retained source.
60    pub kind: ArtifactKind,
61    /// An external location is never owned, even when below the configured root.
62    pub external: Option<PathBuf>,
63    /// Relative to the owned artifact directory; HF snapshots have nested paths.
64    pub entry: PathBuf,
65    /// Whether preparation or acquisition completed before publication.
66    pub ready: bool,
67}
68
69#[derive(Serialize, Deserialize)]
70pub(super) struct Catalog {
71    pub version: u32,
72    pub models: BTreeMap<String, ModelEntry>,
73    pub artifacts: BTreeMap<String, Artifact>,
74    #[serde(default)]
75    pub stores: BTreeMap<String, super::DiskStore>,
76}
77
78impl Default for Catalog {
79    fn default() -> Self {
80        Self {
81            version: 1,
82            models: BTreeMap::new(),
83            artifacts: BTreeMap::new(),
84            stores: BTreeMap::new(),
85        }
86    }
87}
88
89/// Current availability and storage totals for a registered model.
90#[derive(Serialize)]
91pub struct ModelSummary {
92    /// Stable catalog ID.
93    pub id: String,
94    /// Resolvable selector: alias, full source reference, or ID when ambiguous.
95    pub reference: String,
96    /// Optional model alias.
97    pub name: Option<String>,
98    /// Architecture recorded in the source description.
99    pub architecture: crate::model::Architecture,
100    /// Original source identity.
101    pub source: Source,
102    /// Whether the local source path or a retained HF source currently exists.
103    pub source_local: bool,
104    /// Whether the referenced prepared artifact path exists.
105    pub prepared: bool,
106    /// Expert bit widths reported by [`super::prepared_precisions`], descending.
107    pub precisions: Vec<u32>,
108    /// Referenced file lengths, not filesystem blocks reclaimed by removal.
109    pub owned_bytes: u64,
110    /// File lengths in referenced external artifacts; excludes untracked source files.
111    pub external_bytes: u64,
112}
113
114/// Model summary with preparation requirements and artifact ownership details.
115#[derive(Serialize)]
116pub struct ModelDetails {
117    /// Availability and byte totals, flattened in serialized output.
118    #[serde(flatten)]
119    pub summary: ModelSummary,
120    /// Direct when a prepared path exists; otherwise the source's requirements.
121    pub preparation: crate::model::Preparation,
122    /// Artifacts referenced by this model.
123    pub artifacts: Vec<ArtifactDetails>,
124}
125
126/// Location, ownership, and reference count of a catalog artifact.
127#[derive(Serialize)]
128pub struct ArtifactDetails {
129    /// Stable artifact ID.
130    pub id: String,
131    /// Prepared output or retained source.
132    pub kind: ArtifactKind,
133    /// Resolved artifact entry path.
134    pub path: PathBuf,
135    /// Whether garbage collection may delete the artifact's files.
136    pub owned: bool,
137    /// Whether the entry path currently exists; not a full integrity check.
138    pub available: bool,
139    /// Sum of file lengths, including shared hard links at each referenced path.
140    pub bytes: u64,
141    /// Number of model artifact references, excluding live leases.
142    pub references: usize,
143}
144
145/// Garbage collection candidates and artifacts skipped because they are leased.
146#[derive(Default, Serialize)]
147pub struct GcReport {
148    /// Whether collection only inspected candidates.
149    pub dry_run: bool,
150    /// Artifact IDs removed, or eligible for removal during a dry run.
151    pub artifacts: Vec<String>,
152    /// Unreferenced artifact IDs skipped because their lease lock was unavailable.
153    pub leased: Vec<String>,
154    /// Owned candidate file lengths; shared hard links can reduce reclaimed space.
155    pub candidate_bytes: u64,
156}
157
158/// References released by removal; their files have not been collected yet.
159#[derive(Serialize)]
160pub struct Removal {
161    /// Model ID whose references changed.
162    pub id: String,
163    /// Whether only the retained source reference was released.
164    pub source_only: bool,
165    /// Released artifact IDs, which may still be referenced by other models.
166    pub released_artifacts: Vec<String>,
167}
cherenkov/model/index/records.rs

cherenkov/model/index/
records.rs
