1use std::collections::BTreeMap;
4use std::fs;
5use std::path::{Component as PathComponent, Path, PathBuf};
6
7use indexmap::IndexMap;
8use serde::Deserialize;
9use serde_json::{Map, Value};
10use thiserror::Error;
11
12const MANIFEST_FILE: &str = "manifest.json";
13const COMPONENT_FILE: &str = "component.json";
14const MAX_JSON_BYTES: u64 = 4 * 1024 * 1024;
15
16#[derive(Debug, Error)]
18pub enum PackageError {
19 #[error("failed to read {path}: {source}")]
20 Io {
21 path: PathBuf,
22 #[source]
23 source: std::io::Error,
24 },
25 #[error("invalid JSON in {path}: {source}")]
26 Json {
27 path: PathBuf,
28 #[source]
29 source: serde_json::Error,
30 },
31 #[error("invalid model package: {0}")]
32 Invalid(String),
33 #[error("component '{0}' was not found")]
34 UnknownComponent(String),
35 #[error("variant '{variant}' was not found in component '{component}'")]
36 UnknownVariant { component: String, variant: String },
37 #[error("no variant in component '{component}' matches {request}")]
38 NoMatchingVariant { component: String, request: String },
39}
40
41#[derive(Debug, Clone, Copy, Default, Deserialize, PartialEq, Eq)]
43#[serde(rename_all = "lowercase")]
44pub enum PackageLayout {
45 #[default]
47 Portable,
48 Installed,
53}
54
55#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
65pub enum HostTrust {
66 #[default]
69 Confined,
70 AllowInstalledLayout,
73}
74
75#[derive(Debug, Clone, Deserialize)]
77pub struct Manifest {
78 pub schema_version: String,
79 pub package_name: Option<String>,
80 pub package_version: Option<String>,
81 pub description: Option<String>,
82 #[serde(default)]
83 pub layout: PackageLayout,
84 pub components: IndexMap<String, ComponentReference>,
85 #[serde(default)]
86 pub shared_assets: BTreeMap<String, String>,
87 #[serde(default)]
88 pub additional_metadata: Map<String, Value>,
89 #[serde(flatten)]
90 pub unknown_fields: Map<String, Value>,
91}
92
93#[derive(Debug, Clone, Deserialize)]
95#[serde(untagged)]
96pub enum ComponentReference {
97 Inline(Box<Component>),
98 External(String),
99}
100
101#[derive(Debug, Clone, Deserialize)]
103pub struct Component {
104 pub component_name: String,
105 pub variants: IndexMap<String, Variant>,
106 #[serde(default)]
107 pub additional_metadata: Map<String, Value>,
108 #[serde(flatten)]
109 pub unknown_fields: Map<String, Value>,
110}
111
112#[derive(Debug, Clone, Deserialize)]
114pub struct Variant {
115 pub variant_directory: String,
116 pub ep: Option<String>,
117 pub device: Option<String>,
118 pub compatibility_string: Option<String>,
119 #[serde(default)]
120 pub executor_info: Map<String, Value>,
121 #[serde(default)]
122 pub additional_metadata: Map<String, Value>,
123 #[serde(flatten)]
124 pub unknown_fields: Map<String, Value>,
125}
126
127#[derive(Debug, Clone, Deserialize)]
130pub struct ExecutorInfo {
131 pub schema_version: Option<String>,
132 pub model_file: String,
133 pub genai_config: Option<String>,
134 pub inference_metadata: Option<String>,
135 pub tokenizer: Option<String>,
136 #[serde(default)]
137 pub session_options: BTreeMap<String, String>,
138 #[serde(default)]
139 pub provider_options: BTreeMap<String, String>,
140 #[serde(flatten)]
141 pub unknown_fields: Map<String, Value>,
142}
143
144#[derive(Debug, Clone, Default, PartialEq, Eq)]
146pub struct SelectionRequest {
147 pub variant: Option<String>,
148 pub execution_provider: Option<String>,
149 pub precision: Option<String>,
150}
151
152impl SelectionRequest {
153 #[must_use]
155 pub fn named(name: impl Into<String>) -> Self {
156 Self {
157 variant: Some(name.into()),
158 ..Self::default()
159 }
160 }
161
162 #[must_use]
164 pub fn for_execution_provider(execution_provider: impl Into<String>) -> Self {
165 Self {
166 execution_provider: Some(execution_provider.into()),
167 ..Self::default()
168 }
169 }
170}
171
172#[derive(Debug, Clone, PartialEq, Eq)]
174pub struct SelectedVariant {
175 pub component_name: String,
176 pub variant_name: String,
177 pub variant_directory: PathBuf,
178 pub model_path: PathBuf,
179 pub genai_config_path: Option<PathBuf>,
180 pub inference_metadata_path: Option<PathBuf>,
181 pub tokenizer_directory: Option<PathBuf>,
182}
183
184#[derive(Debug, Clone)]
186pub struct ModelPackage {
187 root: PathBuf,
188 manifest: Manifest,
189 trust: HostTrust,
190}
191
192impl ModelPackage {
193 pub fn open(root: impl AsRef<Path>) -> Result<Self, PackageError> {
198 Self::open_with_trust(root, HostTrust::Confined)
199 }
200
201 pub fn open_with_trust(root: impl AsRef<Path>, trust: HostTrust) -> Result<Self, PackageError> {
209 let root = root.as_ref();
210 if !root.is_dir() {
211 return Err(PackageError::Invalid(format!(
212 "package directory does not exist: {}",
213 root.display()
214 )));
215 }
216 let manifest_path = root.join(MANIFEST_FILE);
217 let manifest: Manifest = read_json(&manifest_path)?;
218 validate_version(&manifest.schema_version, "package")?;
219 if manifest.components.is_empty() {
220 return Err(PackageError::Invalid(
221 "manifest components must not be empty".to_string(),
222 ));
223 }
224 let root = root.canonicalize().map_err(|source| PackageError::Io {
225 path: root.to_path_buf(),
226 source,
227 })?;
228 Ok(Self {
229 root,
230 manifest,
231 trust,
232 })
233 }
234
235 #[must_use]
237 pub fn manifest(&self) -> &Manifest {
238 &self.manifest
239 }
240
241 pub fn select(
243 &self,
244 component_name: &str,
245 request: &SelectionRequest,
246 ) -> Result<SelectedVariant, PackageError> {
247 let component = self.load_component(component_name)?;
248 let (variant_name, variant) = if let Some(requested_name) = &request.variant {
249 component
250 .variants
251 .get_key_value(requested_name)
252 .ok_or_else(|| PackageError::UnknownVariant {
253 component: component_name.to_string(),
254 variant: requested_name.clone(),
255 })?
256 } else {
257 component
258 .variants
259 .iter()
260 .find(|(_, variant)| variant_matches(variant, request))
261 .ok_or_else(|| PackageError::NoMatchingVariant {
262 component: component_name.to_string(),
263 request: describe_request(request),
264 })?
265 };
266
267 self.resolve_selected(component_name, variant_name, variant)
268 }
269
270 pub fn validate(&self) -> Result<(), PackageError> {
272 for component_name in self.manifest.components.keys() {
273 let component = self.load_component(component_name)?;
274 if component.component_name != *component_name {
275 return Err(PackageError::Invalid(format!(
276 "component map key '{component_name}' does not match component_name '{}'",
277 component.component_name
278 )));
279 }
280 if component.variants.is_empty() {
281 return Err(PackageError::Invalid(format!(
282 "component '{component_name}' has no variants"
283 )));
284 }
285 for (variant_name, variant) in &component.variants {
286 self.resolve_selected(component_name, variant_name, variant)?;
287 }
288 }
289 Ok(())
290 }
291
292 fn load_component(&self, name: &str) -> Result<Component, PackageError> {
293 let reference = self
294 .manifest
295 .components
296 .get(name)
297 .ok_or_else(|| PackageError::UnknownComponent(name.to_string()))?;
298 match reference {
299 ComponentReference::Inline(component) => Ok(component.as_ref().clone()),
300 ComponentReference::External(reference) => {
301 let mut path = self.resolve_path(&self.root, reference, true)?;
302 if path.is_dir() {
303 path = self.canonicalize_confined(&path.join(COMPONENT_FILE))?;
308 }
309 read_json(&path)
310 }
311 }
312 }
313
314 fn resolve_selected(
315 &self,
316 component_name: &str,
317 variant_name: &str,
318 variant: &Variant,
319 ) -> Result<SelectedVariant, PackageError> {
320 let variant_directory = self.resolve_path(&self.root, &variant.variant_directory, true)?;
321 if !variant_directory.is_dir() {
322 return Err(PackageError::Invalid(format!(
323 "variant '{variant_name}' directory is not a directory: {}",
324 variant_directory.display()
325 )));
326 }
327 let executor_info = self.load_executor_info(variant_name, variant, &variant_directory)?;
328 if let Some(version) = &executor_info.schema_version {
329 validate_version(version, "executor")?;
330 }
331 let model_path = self.resolve_path(&variant_directory, &executor_info.model_file, true)?;
332 ensure_file(&model_path, "model_file")?;
333 let genai_config_path = self.resolve_optional_file(
334 &variant_directory,
335 executor_info.genai_config.as_deref(),
336 "genai_config",
337 )?;
338 let inference_metadata_path = self.resolve_optional_file(
339 &variant_directory,
340 executor_info.inference_metadata.as_deref(),
341 "inference_metadata",
342 )?;
343 let tokenizer_directory = executor_info
344 .tokenizer
345 .as_deref()
346 .map(|reference| self.resolve_path(&variant_directory, reference, true))
347 .transpose()?;
348 if let Some(path) = &tokenizer_directory
349 && !path.is_dir()
350 {
351 return Err(PackageError::Invalid(format!(
352 "tokenizer reference is not a directory: {}",
353 path.display()
354 )));
355 }
356 for (key, reference) in &executor_info.session_options {
357 if matches!(
358 key.as_str(),
359 "session.model_external_initializers_file_folder_path" | "ep.context_file_path"
360 ) {
361 self.resolve_path(&variant_directory, reference, true)?;
362 }
363 }
364 Ok(SelectedVariant {
365 component_name: component_name.to_string(),
366 variant_name: variant_name.to_string(),
367 variant_directory,
368 model_path,
369 genai_config_path,
370 inference_metadata_path,
371 tokenizer_directory,
372 })
373 }
374
375 fn load_executor_info(
376 &self,
377 variant_name: &str,
378 variant: &Variant,
379 variant_directory: &Path,
380 ) -> Result<ExecutorInfo, PackageError> {
381 let (namespace, value) = variant
382 .executor_info
383 .get_key_value("nxrt")
384 .or_else(|| variant.executor_info.get_key_value("ort"))
385 .ok_or_else(|| {
386 PackageError::Invalid(format!(
387 "variant '{variant_name}' has no executor_info.nxrt or executor_info.ort"
388 ))
389 })?;
390 match value {
391 Value::String(reference) => {
392 let path = self.resolve_path(variant_directory, reference, true)?;
393 read_json(&path)
394 }
395 Value::Object(_) => serde_json::from_value(value.clone()).map_err(|source| {
396 PackageError::Json {
397 path: PathBuf::from(format!(
398 "{MANIFEST_FILE}:components.*.variants.{variant_name}.executor_info.{namespace}"
399 )),
400 source,
401 }
402 }),
403 _ => Err(PackageError::Invalid(format!(
404 "executor_info.{namespace} for variant '{variant_name}' must be an object or path"
405 ))),
406 }
407 }
408
409 fn resolve_optional_file(
410 &self,
411 base: &Path,
412 reference: Option<&str>,
413 field: &str,
414 ) -> Result<Option<PathBuf>, PackageError> {
415 reference
416 .map(|reference| {
417 let path = self.resolve_path(base, reference, true)?;
418 ensure_file(&path, field)?;
419 Ok(path)
420 })
421 .transpose()
422 }
423
424 fn confinement_enforced(&self) -> bool {
428 !(self.manifest.layout == PackageLayout::Installed
429 && self.trust == HostTrust::AllowInstalledLayout)
430 }
431
432 fn canonicalize_confined(&self, path: &Path) -> Result<PathBuf, PackageError> {
435 if !path.exists() {
436 return Err(PackageError::Invalid(format!(
437 "referenced path does not exist: {}",
438 path.display()
439 )));
440 }
441 let canonical = path.canonicalize().map_err(|source| PackageError::Io {
442 path: path.to_path_buf(),
443 source,
444 })?;
445 if self.confinement_enforced() && !canonical.starts_with(&self.root) {
446 return Err(PackageError::Invalid(format!(
447 "package reference resolves outside package root: {}",
448 path.display()
449 )));
450 }
451 Ok(canonical)
452 }
453
454 fn resolve_path(
455 &self,
456 base: &Path,
457 reference: &str,
458 must_exist: bool,
459 ) -> Result<PathBuf, PackageError> {
460 let path = if let Some(asset_reference) = reference.strip_prefix("sha256:") {
461 self.resolve_shared_asset(asset_reference)?
462 } else {
463 let reference_path = Path::new(reference);
464 if self.confinement_enforced() {
465 validate_portable_reference(reference_path)?;
466 }
467 if reference_path.is_absolute() {
468 reference_path.to_path_buf()
469 } else {
470 base.join(reference_path)
471 }
472 };
473 if must_exist {
474 return self.canonicalize_confined(&path);
475 }
476 Ok(path)
477 }
478
479 fn resolve_shared_asset(&self, reference: &str) -> Result<PathBuf, PackageError> {
480 let (digest, tail) = reference
481 .split_once('/')
482 .map_or((reference, None), |(digest, tail)| (digest, Some(tail)));
483 if digest.len() != 64
484 || !digest
485 .bytes()
486 .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
487 {
488 return Err(PackageError::Invalid(format!(
489 "invalid sha256 shared-asset reference: sha256:{reference}"
490 )));
491 }
492 let override_path = self
493 .manifest
494 .shared_assets
495 .get(&format!("sha256:{digest}"))
496 .or_else(|| self.manifest.shared_assets.get(digest));
497 let root = override_path.map_or_else(
498 || {
499 Ok(self
500 .root
501 .join("shared_assets")
502 .join(format!("sha256-{digest}")))
503 },
504 |reference| {
505 let path = Path::new(reference);
506 if self.confinement_enforced() {
507 validate_portable_reference(path)?;
508 }
509 Ok(if path.is_absolute() {
510 path.to_path_buf()
511 } else {
512 self.root.join(path)
513 })
514 },
515 )?;
516 let path = tail.map_or(root.clone(), |tail| root.join(tail));
517 self.canonicalize_confined(&path)
518 }
519}
520
521#[must_use]
524pub fn is_model_package_directory(path: impl AsRef<Path>) -> bool {
525 let path = path.as_ref();
526 let Ok(bytes) = fs::read(path.join(MANIFEST_FILE)) else {
527 return false;
528 };
529 let Ok(value) = serde_json::from_slice::<Value>(&bytes) else {
530 return has_package_suffix(path);
531 };
532 value.get("schema_version").is_some() && value.get("components").is_some()
533 || has_package_suffix(path)
534}
535
536fn has_package_suffix(path: &Path) -> bool {
537 path.extension().is_some_and(|extension| {
538 extension.eq_ignore_ascii_case("ortpackage") || extension.eq_ignore_ascii_case("nxpackage")
539 })
540}
541
542fn read_json<T: for<'de> Deserialize<'de>>(path: &Path) -> Result<T, PackageError> {
543 let metadata = fs::metadata(path).map_err(|source| PackageError::Io {
544 path: path.to_path_buf(),
545 source,
546 })?;
547 if metadata.len() > MAX_JSON_BYTES {
548 return Err(PackageError::Invalid(format!(
549 "JSON file exceeds {MAX_JSON_BYTES} bytes: {}",
550 path.display()
551 )));
552 }
553 let bytes = fs::read(path).map_err(|source| PackageError::Io {
554 path: path.to_path_buf(),
555 source,
556 })?;
557 serde_json::from_slice(&bytes).map_err(|source| PackageError::Json {
558 path: path.to_path_buf(),
559 source,
560 })
561}
562
563fn validate_version(version: &str, kind: &str) -> Result<(), PackageError> {
564 let (major, minor) = version.split_once('.').ok_or_else(|| {
565 PackageError::Invalid(format!("{kind} schema_version must be '<major>.<minor>'"))
566 })?;
567 let major = major.parse::<u64>().map_err(|_| {
568 PackageError::Invalid(format!("{kind} schema_version has a non-numeric major"))
569 })?;
570 minor.parse::<u64>().map_err(|_| {
571 PackageError::Invalid(format!("{kind} schema_version has a non-numeric minor"))
572 })?;
573 if major != 1 {
574 return Err(PackageError::Invalid(format!(
575 "unsupported {kind} schema major version {major}; supported major is 1"
576 )));
577 }
578 Ok(())
579}
580
581fn validate_portable_reference(path: &Path) -> Result<(), PackageError> {
582 if path.as_os_str().is_empty()
583 || path.is_absolute()
584 || path.components().any(|component| {
585 matches!(
586 component,
587 PathComponent::ParentDir | PathComponent::RootDir | PathComponent::Prefix(_)
588 )
589 })
590 {
591 return Err(PackageError::Invalid(format!(
592 "portable package reference escapes its base: {}",
593 path.display()
594 )));
595 }
596 Ok(())
597}
598
599fn ensure_file(path: &Path, field: &str) -> Result<(), PackageError> {
600 if path.is_file() {
601 Ok(())
602 } else {
603 Err(PackageError::Invalid(format!(
604 "{field} is not a file: {}",
605 path.display()
606 )))
607 }
608}
609
610fn variant_matches(variant: &Variant, request: &SelectionRequest) -> bool {
611 let execution_provider_matches = request.execution_provider.as_ref().is_none_or(|requested| {
612 variant
613 .ep
614 .as_ref()
615 .is_some_and(|actual| actual.eq_ignore_ascii_case(requested))
616 });
617 let precision_matches = request.precision.as_ref().is_none_or(|requested| {
618 variant
619 .additional_metadata
620 .get("precision")
621 .and_then(Value::as_str)
622 .is_some_and(|actual| actual.eq_ignore_ascii_case(requested))
623 });
624 execution_provider_matches && precision_matches
625}
626
627fn describe_request(request: &SelectionRequest) -> String {
628 let mut attributes = Vec::new();
629 if let Some(execution_provider) = &request.execution_provider {
630 attributes.push(format!("execution provider '{execution_provider}'"));
631 }
632 if let Some(precision) = &request.precision {
633 attributes.push(format!("precision '{precision}'"));
634 }
635 if attributes.is_empty() {
636 "the default selection".to_string()
637 } else {
638 attributes.join(" and ")
639 }
640}