mod-trace 0.3.0__tar.gz → 0.3.2__tar.gz

{mod_trace-0.3.0 → mod_trace-0.3.2}/Cargo.lock

@@ -16,7 +16,7 @@ checksum = "6b947ae49db0d222b1dbc6b113ce7248a3fc3a6ca21b696717bfc000ba4484d8"
 
 [[package]]
 name = "mod-trace"
-version = "0.3.0"
+version = "0.3.2"
 dependencies = [
  "serde",
  "serde_json",

{mod_trace-0.3.0 → mod_trace-0.3.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mod-trace"
-version = "0.3.0"
+version = "0.3.2"
 edition = "2024"
 description = "Rust CLI for inspecting ML model artifacts without loading the framework"
 license = "MIT"

{mod_trace-0.3.0 → mod_trace-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mod-trace
-Version: 0.3.0
+Version: 0.3.2
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only

{mod_trace-0.3.0 → mod_trace-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "mod-trace"
-version = "0.3.0"
+version = "0.3.2"
 description = "Rust CLI for inspecting ML model artifacts without loading the framework"
 readme = "README.md"
 requires-python = ">=3.9"

{mod_trace-0.3.0 → mod_trace-0.3.2}/src/main.rs

@@ -192,11 +192,15 @@ fn print_doctor_report(report: &DoctorReport) {
     println!();
     println!("Available commands:");
     println!(
-        "  inspect .cbm/.onnx/.json: {}",
+        "  inspect .cbm/.lgb/.onnx/.json: {}",
         available_unavailable(report.commands.inspect_artifacts)
     );
     println!(
-        "  diff .cbm/.onnx: {}",
+        "  diff .cbm/.lgb/.onnx: {}",
+        available_unavailable(report.commands.diff_artifacts)
+    );
+    println!(
+        "  explain-diff .cbm/.lgb/.onnx: {}",
         available_unavailable(report.commands.diff_artifacts)
     );
     println!(
@@ -1023,6 +1027,12 @@ fn opt_num(value: Option<usize>) -> String {
         .unwrap_or_else(|| "unknown".to_string())
 }
 
+fn opt_float(value: Option<f64>) -> String {
+    value
+        .map(|value| format!("{value}"))
+        .unwrap_or_else(|| "unknown".to_string())
+}
+
 fn format_count_human(count: usize) -> String {
     let value = count as f64;
     if value >= 1e9 {
@@ -1157,10 +1167,29 @@ fn explain_diff_onnx(old_path: &str, new_path: &str) -> Result<(), String> {
     Ok(())
 }
 
+fn same_or_changed(equal: bool) -> &'static str {
+    if equal { "same" } else { "changed" }
+}
+
 fn explain_diff_lgbm(old_path: &str, new_path: &str) -> Result<(), String> {
     let old = lgbm::inspect(old_path)?;
     let new = lgbm::inspect(new_path)?;
 
+    // Feature-name set comparison (not just the count).
+    let old_features = old.feature_names.iter().collect::<BTreeSet<_>>();
+    let new_features = new.feature_names.iter().collect::<BTreeSet<_>>();
+    let added = new_features
+        .difference(&old_features)
+        .map(|name| name.as_str())
+        .collect::<Vec<_>>();
+    let removed = old_features
+        .difference(&new_features)
+        .map(|name| name.as_str())
+        .collect::<Vec<_>>();
+    let names_known = !old.feature_names.is_empty() || !new.feature_names.is_empty();
+
+    let config_same = lgbm_training_config_same(&old, &new);
+
     println!("Model Change Explanation");
     println!("------------------------");
     println!("Type: LightGBM");
@@ -1179,17 +1208,60 @@ fn explain_diff_lgbm(old_path: &str, new_path: &str) -> Result<(), String> {
         opt_num(old.num_leaves.map(|value| value as usize)),
         opt_num(new.num_leaves.map(|value| value as usize))
     );
+    let feature_note = if !names_known {
+        "names not in header".to_string()
+    } else if added.is_empty() && removed.is_empty() {
+        "same set".to_string()
+    } else {
+        format!("+{} added, -{} removed", added.len(), removed.len())
+    };
     println!(
-        "  Features:          {} -> {}",
+        "  Features:          {} -> {} ({})",
         opt_num(old.num_features.map(|value| value as usize)),
-        opt_num(new.num_features.map(|value| value as usize))
+        opt_num(new.num_features.map(|value| value as usize)),
+        feature_note
     );
+    print_lgbm_feature_list("    added:  ", &added, 8);
+    print_lgbm_feature_list("    removed:", &removed, 8);
+    println!();
+    println!("Training config:");
     println!(
-        "  Objective:         {} -> {}",
+        "  Objective:         {} -> {} ({})",
         old.objective.as_deref().unwrap_or("unknown"),
-        new.objective.as_deref().unwrap_or("unknown")
+        new.objective.as_deref().unwrap_or("unknown"),
+        same_or_changed(old.objective == new.objective)
+    );
+    println!(
+        "  Boosting:          {} -> {} ({})",
+        old.boosting.as_deref().unwrap_or("unknown"),
+        new.boosting.as_deref().unwrap_or("unknown"),
+        same_or_changed(old.boosting == new.boosting)
+    );
+    println!(
+        "  Metric:            {} -> {} ({})",
+        old.metric.as_deref().unwrap_or("unknown"),
+        new.metric.as_deref().unwrap_or("unknown"),
+        same_or_changed(old.metric == new.metric)
+    );
+    println!(
+        "  Learning rate:     {} -> {} ({})",
+        opt_float(old.learning_rate),
+        opt_float(new.learning_rate),
+        same_or_changed(old.learning_rate == new.learning_rate)
+    );
+    println!(
+        "  Max depth:         {} -> {} ({})",
+        old.max_depth.map(lgbm_depth_label).as_deref().unwrap_or("unknown"),
+        new.max_depth.map(lgbm_depth_label).as_deref().unwrap_or("unknown"),
+        same_or_changed(old.max_depth == new.max_depth)
     );
     println!();
+    println!(
+        "File size: {} -> {} ({})",
+        format_bytes(old.bytes),
+        format_bytes(new.bytes),
+        growth_label(old.bytes, new.bytes)
+    );
     match (old.estimated_leaf_values(), new.estimated_leaf_values()) {
         (Some(o), Some(n)) => println!(
             "Estimated leaf-slot growth: {}",
@@ -1204,11 +1276,52 @@ fn explain_diff_lgbm(old_path: &str, new_path: &str) -> Result<(), String> {
         println!("Learned state: unchanged (identical leaf values)");
     }
     println!();
+    println!("Summary:");
+    let structure_same = old.num_trees == new.num_trees && old.num_leaves == new.num_leaves;
+    let features_same = added.is_empty() && removed.is_empty();
+    let descriptor = if !features_same {
+        "feature set changed"
+    } else if !config_same {
+        "training config changed"
+    } else if !structure_same {
+        "same spec, retrained with more/fewer trees"
+    } else {
+        "same spec and features, retrained"
+    };
+    println!(
+        "  {descriptor}; trees {}, features {}.",
+        growth_label(old.num_trees as usize, new.num_trees as usize),
+        if !names_known {
+            "unknown".to_string()
+        } else if features_same {
+            "unchanged".to_string()
+        } else {
+            format!("+{}/-{}", added.len(), removed.len())
+        }
+    );
+    println!();
     println!("Note: parsed natively from the LightGBM text model.");
 
     Ok(())
 }
 
+fn print_lgbm_feature_list(label: &str, names: &[&str], limit: usize) {
+    if names.is_empty() {
+        return;
+    }
+    let shown = names
+        .iter()
+        .take(limit)
+        .copied()
+        .collect::<Vec<_>>()
+        .join(", ");
+    if names.len() > limit {
+        println!("{label} {shown}, ... {} more", names.len() - limit);
+    } else {
+        println!("{label} {shown}");
+    }
+}
+
 fn explain_diff_catboost(old_path: &str, new_path: &str) -> Result<(), String> {
     let old = cbm::inspect(old_path)?;
     let new = cbm::inspect(new_path)?;