Skip to main content

sightloom_host/
manifest.rs

1//! Host **model manifest** — JSON inventory of weights (no weights in-repo).
2//!
3//! Hosts keep a `models.manifest.json` next to the cache dir, resolve paths
4//! with a [`crate::ModelFetcher`], and load ONNX via [`crate::OnnxEmbedder`].
5
6use crate::config::{HostBundleConfig, ModelSpec, ModelTask};
7use crate::error::HostError;
8use crate::registry::{ModelFetcher, ensure_cache_dir, write_cache_readme};
9use serde::{Deserialize, Serialize};
10use std::fs;
11use std::path::{Path, PathBuf};
12
13/// Versioned list of host models (download / local placement policy).
14#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
15pub struct ModelManifest {
16    /// Schema version (currently `1`).
17    #[serde(default = "default_manifest_version")]
18    pub version: u32,
19    /// Cache directory for resolved weights (relative or absolute).
20    #[serde(default = "default_manifest_cache")]
21    pub cache_dir: PathBuf,
22    /// Models to materialize.
23    #[serde(default)]
24    pub models: Vec<ModelSpec>,
25    /// Optional human notes (not machine-consumed).
26    #[serde(default)]
27    pub notes: Option<String>,
28}
29
30fn default_manifest_version() -> u32 {
31    1
32}
33
34fn default_manifest_cache() -> PathBuf {
35    PathBuf::from(".sightloom-models")
36}
37
38impl Default for ModelManifest {
39    fn default() -> Self {
40        Self {
41            version: 1,
42            cache_dir: default_manifest_cache(),
43            models: Vec::new(),
44            notes: None,
45        }
46    }
47}
48
49impl ModelManifest {
50    /// Parses JSON text.
51    ///
52    /// # Errors
53    ///
54    /// Serde / schema errors.
55    pub fn from_json(text: &str) -> Result<Self, HostError> {
56        let m: Self = serde_json::from_str(text)
57            .map_err(|e| HostError::Config(format!("manifest json: {e}")))?;
58        if m.version == 0 {
59            return Err(HostError::Config("manifest version must be >= 1".into()));
60        }
61        Ok(m)
62    }
63
64    /// Loads from a JSON file path.
65    ///
66    /// # Errors
67    ///
68    /// I/O or parse failures.
69    pub fn load_path(path: &Path) -> Result<Self, HostError> {
70        let text = fs::read_to_string(path).map_err(|e| HostError::Io(e.to_string()))?;
71        Self::from_json(&text)
72    }
73
74    /// Pretty JSON.
75    ///
76    /// # Errors
77    ///
78    /// Serde errors.
79    pub fn to_json_pretty(&self) -> Result<String, HostError> {
80        serde_json::to_string_pretty(self).map_err(|e| HostError::Config(e.to_string()))
81    }
82
83    /// Writes JSON to `path` (parent dirs created).
84    ///
85    /// # Errors
86    ///
87    /// I/O failures.
88    pub fn save_path(&self, path: &Path) -> Result<(), HostError> {
89        if let Some(parent) = path.parent().filter(|p| !p.as_os_str().is_empty()) {
90            fs::create_dir_all(parent).map_err(|e| HostError::Io(e.to_string()))?;
91        }
92        fs::write(path, self.to_json_pretty()?).map_err(|e| HostError::Io(e.to_string()))
93    }
94
95    /// Example person re-id + person detect skeleton (uris empty — host fills in).
96    #[must_use]
97    pub fn example_person_bundle() -> Self {
98        let mut person_detect = ModelSpec::detector("person_detect", ModelTask::PersonDetect);
99        person_detect.preprocess = crate::preprocess::PreprocessConfig::yolo_detect(640, 640);
100        person_detect.local_path = Some(PathBuf::from(".sightloom-models/person_detect.onnx"));
101
102        let mut person_reid = ModelSpec::embedder("person_reid", ModelTask::PersonReId, 512);
103        person_reid.preprocess = crate::preprocess::PreprocessConfig::imagenet_like(128, 256);
104        person_reid.local_path = Some(PathBuf::from(".sightloom-models/person_reid.onnx"));
105
106        Self {
107            version: 1,
108            cache_dir: PathBuf::from(".sightloom-models"),
109            models: vec![person_detect, person_reid],
110            notes: Some(
111                "Required: person_detect.onnx (NCHW RGB f32 → YOLO / N×6) and \
112                 person_reid.onnx (NCHW RGB f32 → L2 embedding). Optional: \
113                 face_embed.onnx (same embed contract, typically 112×112). \
114                 Fill uri or drop files under cache_dir. sha256 is lowercase hex."
115                    .into(),
116            ),
117        }
118    }
119
120    /// Maps known tasks into a [`HostBundleConfig`] (first match wins per slot).
121    #[must_use]
122    pub fn to_bundle_config(&self) -> HostBundleConfig {
123        let mut cfg = HostBundleConfig {
124            person_detect: None,
125            face_detect: None,
126            person_reid: None,
127            face_embed: None,
128            segmentation: None,
129            cache_dir: self.cache_dir.clone(),
130            require_real_weights: true,
131        };
132        for spec in &self.models {
133            match spec.task {
134                ModelTask::PersonDetect if cfg.person_detect.is_none() => {
135                    cfg.person_detect = Some(spec.clone());
136                }
137                ModelTask::FaceDetect if cfg.face_detect.is_none() => {
138                    cfg.face_detect = Some(spec.clone());
139                }
140                ModelTask::PersonReId if cfg.person_reid.is_none() => {
141                    cfg.person_reid = Some(spec.clone());
142                }
143                ModelTask::FaceEmbed if cfg.face_embed.is_none() => {
144                    cfg.face_embed = Some(spec.clone());
145                }
146                ModelTask::Segmentation if cfg.segmentation.is_none() => {
147                    cfg.segmentation = Some(spec.clone());
148                }
149                _ => {}
150            }
151        }
152        cfg
153    }
154
155    /// Ensures every model is local via `fetcher` (download or filesystem).
156    ///
157    /// Returns resolved paths in manifest order. Verifies `sha256` when set.
158    ///
159    /// # Errors
160    ///
161    /// Fetch / integrity / I/O failures.
162    pub fn ensure_all(&self, fetcher: &mut dyn ModelFetcher) -> Result<Vec<PathBuf>, HostError> {
163        ensure_cache_dir(&self.cache_dir)?;
164        let _ = write_cache_readme(&self.cache_dir);
165        let mut paths = Vec::with_capacity(self.models.len());
166        for spec in &self.models {
167            let path = fetcher.ensure_local(spec, &self.cache_dir)?;
168            crate::integrity::maybe_verify_sha256(path.as_path(), spec.sha256.as_deref())?;
169            paths.push(path);
170        }
171        Ok(paths)
172    }
173
174    /// Spec by id.
175    #[must_use]
176    pub fn get(&self, id: &str) -> Option<&ModelSpec> {
177        self.models.iter().find(|m| m.id == id)
178    }
179}
180
181/// Result of materializing one model for logging / evidence.
182#[derive(Clone, Debug, PartialEq, Eq)]
183pub struct ResolvedModel {
184    /// Spec id.
185    pub id: String,
186    /// Absolute or relative path on disk.
187    pub path: PathBuf,
188    /// Whether sha256 was checked.
189    pub verified: bool,
190}
191
192/// Resolves all models and returns structured results.
193///
194/// # Errors
195///
196/// Same as [`ModelManifest::ensure_all`].
197pub fn resolve_manifest(
198    manifest: &ModelManifest,
199    fetcher: &mut dyn ModelFetcher,
200) -> Result<Vec<ResolvedModel>, HostError> {
201    let paths = manifest.ensure_all(fetcher)?;
202    let mut out = Vec::with_capacity(paths.len());
203    for (spec, path) in manifest.models.iter().zip(paths) {
204        out.push(ResolvedModel {
205            id: spec.id.clone(),
206            path,
207            verified: spec.sha256.is_some(),
208        });
209    }
210    Ok(out)
211}
212
213#[cfg(test)]
214mod tests {
215    use super::*;
216    use crate::registry::FilesystemFetcher;
217    use std::io::Write;
218
219    #[test]
220    fn example_roundtrip_json() {
221        let m = ModelManifest::example_person_bundle();
222        let text = m.to_json_pretty().unwrap();
223        let back = ModelManifest::from_json(&text).unwrap();
224        assert_eq!(back.models.len(), 2);
225        assert_eq!(back.version, 1);
226        let bundle = back.to_bundle_config();
227        assert!(bundle.person_reid.is_some());
228        assert!(bundle.person_detect.is_some());
229        assert!(bundle.require_real_weights);
230    }
231
232    #[test]
233    fn ensure_all_local_and_sha256() {
234        let dir = tempfile::tempdir().unwrap();
235        let cache = dir.path().join("cache");
236        fs::create_dir_all(&cache).unwrap();
237        let weights = cache.join("toy.onnx");
238        {
239            let mut f = fs::File::create(&weights).unwrap();
240            f.write_all(b"fake-onnx-bytes").unwrap();
241        }
242        let digest = crate::integrity::file_sha256_hex(&weights).unwrap();
243
244        let mut spec = ModelSpec::embedder("toy", ModelTask::PersonReId, 8);
245        spec.sha256 = Some(digest);
246        let manifest = ModelManifest {
247            version: 1,
248            cache_dir: cache.clone(),
249            models: vec![spec],
250            notes: None,
251        };
252        let paths = manifest.ensure_all(&mut FilesystemFetcher).unwrap();
253        assert_eq!(paths.len(), 1);
254        assert!(paths[0].is_file());
255    }
256
257    #[test]
258    fn ensure_all_rejects_bad_digest() {
259        let dir = tempfile::tempdir().unwrap();
260        let cache = dir.path().join("cache");
261        fs::create_dir_all(&cache).unwrap();
262        let weights = cache.join("toy.onnx");
263        fs::write(&weights, b"x").unwrap();
264        let mut spec = ModelSpec::embedder("toy", ModelTask::PersonReId, 8);
265        spec.sha256 =
266            Some("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855".into());
267        let manifest = ModelManifest {
268            version: 1,
269            cache_dir: cache,
270            models: vec![spec],
271            notes: None,
272        };
273        let err = manifest.ensure_all(&mut FilesystemFetcher).unwrap_err();
274        assert!(matches!(err, HostError::Integrity(_)));
275    }
276}