capability_grower_configuration/

capstone_mode.rs

// ---------------- [ File: capability-grower-configuration/src/capstone_mode.rs ]
crate::ix!();

/// This enum should specify how we generate "capstone" nodes per tree.
/// - Off → No special capstone node will be generated.
/// - Single → Exactly one capstone leaf will be generated.
/// - Probabilistic → a fraction of leaves per level will become capstones.
#[derive(
    Copy,
    SaveLoad,
    Debug, 
    Clone, 
    PartialEq, 
    Eq, 
    Serialize, 
    Default,
    Deserialize, 
    AiJsonTemplate,
    AiJsonTemplateWithJustification,
)]
pub enum CapstoneMode {
    /// This variant should be used if we do not want any special capstones.
    #[default]
    Off,
    /// This variant designates exactly one "capstone" leaf in the entire tree.
    Single,
    /// This variant designates a fraction of leaves as highlight/capstones.
    Probabilistic,
}

impl FuzzyFromJsonValue for JustifiedCapstoneMode {
    fn fuzzy_from_json_value(value: &serde_json::Value) -> Result<Self, FuzzyFromJsonValueError> {
        trace!("(JustifiedCapstoneMode) Entering fuzzy_from_json_value");

        // 1) If null => default Off
        if value.is_null() {
            debug!("(JustifiedCapstoneMode) Null => defaulting to Off");
            return Ok(Self::Off {
                variant_confidence: 0.0,
                variant_justification: String::new(),
            });
        }

        // 2) If string => interpret as variant name with default confidence/justification
        if let Some(variant_str) = value.as_str() {
            trace!("(JustifiedCapstoneMode) Found string => '{}'", variant_str);
            return match variant_str {
                "Off" => Ok(Self::Off {
                    variant_confidence: 0.0,
                    variant_justification: String::new(),
                }),
                "Single" => Ok(Self::Single {
                    variant_confidence: 0.0,
                    variant_justification: String::new(),
                }),
                "Probabilistic" => Ok(Self::Probabilistic {
                    variant_confidence: 0.0,
                    variant_justification: String::new(),
                }),
                other => {
                    error!("(JustifiedCapstoneMode) Unknown string variant='{}'", other);
                    Err(FuzzyFromJsonValueError::Other {
                        target_type: "JustifiedCapstoneMode",
                        detail: format!(
                            "Unknown string variant='{}'; expected [Off,Single,Probabilistic]",
                            other
                        ),
                    })
                }
            };
        }

        // 3) Must be object => flatten if needed
        let mut obj = match value.as_object() {
            Some(m) => {
                trace!("(JustifiedCapstoneMode) Found object => flattening if any 'fields' sub-objects.");
                let mut cloned = m.clone();
                flatten_all_fields(&mut cloned);
                cloned
            }
            None => {
                error!("(JustifiedCapstoneMode) Not an object => fail!");
                return Err(FuzzyFromJsonValueError::NotAnObject {
                    target_type: "JustifiedCapstoneMode",
                    actual: value.clone(),
                });
            }
        };

        // 3A) Single-key object form => e.g. { "Single": {...} }, or just { "Single": {} }
        //     We'll unify that into { "variant_name":"Single", ...subfields... }.
        if obj.len() == 1 && !obj.contains_key("variant_name") {
            let (maybe_variant, nested) = {
                let mut iter = obj.into_iter();
                iter.next().unwrap()
            };
            trace!("(JustifiedCapstoneMode) single-key object => key='{}'", maybe_variant);

            let mut sub_obj = match nested.as_object() {
                Some(sub) => {
                    // flatten sub
                    let mut sclone = sub.clone();
                    flatten_all_fields(&mut sclone);
                    sclone
                }
                None => serde_json::Map::new(),
            };

            // parse variant_confidence & justification if present
            let conf = sub_obj
                .remove("variant_confidence")
                .and_then(|x| x.as_f64())
                .unwrap_or(0.0);
            let just = sub_obj
                .remove("variant_justification")
                .and_then(|x| x.as_str().map(|s| s.to_string()))
                .unwrap_or_default();

            return match maybe_variant.as_str() {
                "Off" => Ok(Self::Off {
                    variant_confidence: conf,
                    variant_justification: just,
                }),
                "Single" => Ok(Self::Single {
                    variant_confidence: conf,
                    variant_justification: just,
                }),
                "Probabilistic" => Ok(Self::Probabilistic {
                    variant_confidence: conf,
                    variant_justification: just,
                }),
                other => {
                    error!("(JustifiedCapstoneMode) Unknown single-key='{}'", other);
                    Err(FuzzyFromJsonValueError::Other {
                        target_type: "JustifiedCapstoneMode",
                        detail: format!("Unknown single key='{}' for capstone mode", other),
                    })
                }
            };
        }

        // 3B) Otherwise, standard object => expect "variant_name"
        let var_name_val = match obj.remove("variant_name") {
            Some(v) => v,
            None => {
                error!("(JustifiedCapstoneMode) Missing 'variant_name' => fail");
                return Err(FuzzyFromJsonValueError::Other {
                    target_type: "JustifiedCapstoneMode",
                    detail: "No 'variant_name' found => cannot parse Off/Single/Probabilistic".to_string(),
                });
            }
        };
        let var_name = match var_name_val.as_str() {
            Some(s) => s,
            None => {
                error!("(JustifiedCapstoneMode) 'variant_name' not a string => fail");
                return Err(FuzzyFromJsonValueError::Other {
                    target_type: "JustifiedCapstoneMode",
                    detail: format!("Expected string for 'variant_name', got {:?}", var_name_val),
                });
            }
        };

        let conf = obj
            .remove("variant_confidence")
            .and_then(|v| v.as_f64())
            .unwrap_or(0.0);
        let just = obj
            .remove("variant_justification")
            .and_then(|v| v.as_str().map(|s| s.to_string()))
            .unwrap_or_default();

        match var_name {
            "Off" => Ok(Self::Off {
                variant_confidence: conf,
                variant_justification: just,
            }),
            "Single" => Ok(Self::Single {
                variant_confidence: conf,
                variant_justification: just,
            }),
            "Probabilistic" => Ok(Self::Probabilistic {
                variant_confidence: conf,
                variant_justification: just,
            }),
            other => {
                error!("(JustifiedCapstoneMode) Unknown variant='{}'", other);
                Err(FuzzyFromJsonValueError::Other {
                    target_type: "JustifiedCapstoneMode",
                    detail: format!("Unknown variant_name='{}'", other),
                })
            }
        }
    }
}

#[cfg(test)]
mod test_fuzzy_from_json_value_for_justified_capstone_mode {
    use super::*;
    use serde_json::json;
    use tracing::{debug, error, info, trace};
    use traced_test::traced_test;

    #[traced_test]
    fn test_null_input() {
        trace!("test_null_input: starting");
        let input = json!(null);
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_ok(),
            "Expected Ok for null input, got error: {:?}",
            result.err()
        );
        let parsed = result.unwrap();
        assert!(
            matches!(parsed, JustifiedCapstoneMode::Off {..}),
            "Expected Off variant for null input, got: {:?}",
            parsed
        );
        if let JustifiedCapstoneMode::Off {
            variant_confidence,
            variant_justification,
        } = parsed
        {
            assert_eq!(variant_confidence, 0.0, "Expected 0.0 confidence for null input");
            assert_eq!(
                variant_justification, "",
                "Expected empty justification for null input"
            );
        }
    }

    #[traced_test]
    fn test_string_off() {
        trace!("test_string_off: starting");
        let input = json!("Off");
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_ok(),
            "Expected Ok for string 'Off', got error: {:?}",
            result.err()
        );
        let parsed = result.unwrap();
        assert!(
            matches!(parsed, JustifiedCapstoneMode::Off {..}),
            "Expected Off variant, got: {:?}",
            parsed
        );
    }

    #[traced_test]
    fn test_string_single() {
        trace!("test_string_single: starting");
        let input = json!("Single");
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_ok(),
            "Expected Ok for string 'Single', got error: {:?}",
            result.err()
        );
        let parsed = result.unwrap();
        assert!(
            matches!(parsed, JustifiedCapstoneMode::Single {..}),
            "Expected Single variant, got: {:?}",
            parsed
        );
    }

    #[traced_test]
    fn test_string_probabilistic() {
        trace!("test_string_probabilistic: starting");
        let input = json!("Probabilistic");
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_ok(),
            "Expected Ok for string 'Probabilistic', got error: {:?}",
            result.err()
        );
        let parsed = result.unwrap();
        assert!(
            matches!(parsed, JustifiedCapstoneMode::Probabilistic {..}),
            "Expected Probabilistic variant, got: {:?}",
            parsed
        );
    }

    #[traced_test]
    fn test_single_key_object_off() {
        trace!("test_single_key_object_off: starting");
        let input = json!({
            "Off": {
                "variant_confidence": 0.9,
                "variant_justification": "Felt best to turn capstones off"
            }
        });
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_ok(),
            "Expected Ok for single-key object 'Off', got error: {:?}",
            result.err()
        );
        let parsed = result.unwrap();
        match parsed {
            JustifiedCapstoneMode::Off {
                variant_confidence,
                variant_justification,
            } => {
                assert_eq!(
                    variant_confidence, 0.9,
                    "Expected 0.9 confidence from single-key object"
                );
                assert_eq!(
                    variant_justification,
                    "Felt best to turn capstones off",
                    "Justification mismatch"
                );
            }
            _ => panic!("Expected Off variant, got: {:?}", parsed),
        }
    }

    #[traced_test]
    fn test_single_key_object_single() {
        trace!("test_single_key_object_single: starting");
        let input = json!({
            "Single": {
                "variant_confidence": 0.8,
                "variant_justification": "A single apex skill is perfect"
            }
        });
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_ok(),
            "Expected Ok for single-key object 'Single', got error: {:?}",
            result.err()
        );
        let parsed = result.unwrap();
        match parsed {
            JustifiedCapstoneMode::Single {
                variant_confidence,
                variant_justification,
            } => {
                assert_eq!(
                    variant_confidence, 0.8,
                    "Expected 0.8 confidence from single-key object"
                );
                assert_eq!(
                    variant_justification,
                    "A single apex skill is perfect",
                    "Justification mismatch"
                );
            }
            _ => panic!("Expected Single variant, got: {:?}", parsed),
        }
    }

    #[traced_test]
    fn test_single_key_object_probabilistic() {
        trace!("test_single_key_object_probabilistic: starting");
        let input = json!({
            "Probabilistic": {
                "variant_confidence": 0.7,
                "variant_justification": "Some portion of leaves should be apex skills"
            }
        });
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_ok(),
            "Expected Ok for single-key object 'Probabilistic', got error: {:?}",
            result.err()
        );
        let parsed = result.unwrap();
        match parsed {
            JustifiedCapstoneMode::Probabilistic {
                variant_confidence,
                variant_justification,
            } => {
                assert_eq!(
                    variant_confidence, 0.7,
                    "Expected 0.7 confidence from single-key object"
                );
                assert_eq!(
                    variant_justification,
                    "Some portion of leaves should be apex skills",
                    "Justification mismatch"
                );
            }
            _ => panic!("Expected Probabilistic variant, got: {:?}", parsed),
        }
    }

    #[traced_test]
    fn test_standard_object_probabilistic() {
        trace!("test_standard_object_probabilistic: starting");
        let input = json!({
            "variant_name": "Probabilistic",
            "variant_confidence": 0.42,
            "variant_justification": "Some fraction of leaves qualify"
        });
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_ok(),
            "Expected Ok for standard object 'Probabilistic', got error: {:?}",
            result.err()
        );
        let parsed = result.unwrap();
        match parsed {
            JustifiedCapstoneMode::Probabilistic {
                variant_confidence,
                variant_justification,
            } => {
                assert_eq!(variant_confidence, 0.42, "Confidence mismatch");
                assert_eq!(
                    variant_justification, "Some fraction of leaves qualify",
                    "Justification mismatch"
                );
            }
            _ => panic!("Expected Probabilistic variant, got: {:?}", parsed),
        }
    }

    #[traced_test]
    fn test_standard_object_off() {
        trace!("test_standard_object_off: starting");
        let input = json!({
            "variant_name": "Off",
            "variant_confidence": 1.0,
            "variant_justification": "Force capstones off entirely"
        });
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_ok(),
            "Expected Ok for standard object 'Off', got error: {:?}",
            result.err()
        );
        let parsed = result.unwrap();
        match parsed {
            JustifiedCapstoneMode::Off {
                variant_confidence,
                variant_justification,
            } => {
                assert_eq!(variant_confidence, 1.0, "Confidence mismatch");
                assert_eq!(
                    variant_justification,
                    "Force capstones off entirely",
                    "Justification mismatch"
                );
            }
            _ => panic!("Expected Off variant, got: {:?}", parsed),
        }
    }

    #[traced_test]
    fn test_unknown_variant_string() {
        trace!("test_unknown_variant_string: starting");
        let input = json!("RandomStuff");
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_err(),
            "Expected an error for unknown string variant, got Ok: {:?}",
            result.ok()
        );
    }

    #[traced_test]
    fn test_unknown_variant_key() {
        trace!("test_unknown_variant_key: starting");
        let input = json!({
            "RandomStuff": {
                "variant_confidence": 0.5,
                "variant_justification": "No idea what this is"
            }
        });
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_err(),
            "Expected an error for unknown single-key variant, got Ok: {:?}",
            result.ok()
        );
    }

    #[traced_test]
    fn test_missing_variant_name_in_object() {
        trace!("test_missing_variant_name_in_object: starting");
        let input = json!({
            "variant_confidence": 0.5,
            "variant_justification": "Missing the variant_name field"
        });
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_err(),
            "Expected an error for missing 'variant_name', got Ok: {:?}",
            result.ok()
        );
    }

    #[traced_test]
    fn test_non_object_non_string() {
        trace!("test_non_object_non_string: starting");
        let input = json!(123);
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_err(),
            "Expected an error for numeric input, got Ok: {:?}",
            result.ok()
        );
    }

    #[traced_test]
    fn test_malformed_variant_name_type() {
        trace!("test_malformed_variant_name_type: starting");
        let input = json!({
            "variant_name": 123
        });
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_err(),
            "Expected an error for integer 'variant_name', got Ok: {:?}",
            result.ok()
        );
    }

    #[traced_test]
    fn test_non_number_variant_confidence() {
        trace!("test_non_number_variant_confidence: starting");
        let input = json!({
            "variant_name": "Single",
            "variant_confidence": "not a number",
            "variant_justification": "But let's see if it defaults"
        });
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_ok(),
            "Expected Ok even if variant_confidence is not numeric, got error: {:?}",
            result.err()
        );
        let parsed = result.unwrap();
        match parsed {
            JustifiedCapstoneMode::Single {
                variant_confidence,
                variant_justification,
            } => {
                assert_eq!(
                    variant_confidence, 0.0,
                    "Expected confidence to default to 0.0 if not numeric"
                );
                assert_eq!(
                    variant_justification, "But let's see if it defaults",
                    "Justification mismatch"
                );
            }
            _ => panic!("Expected Single variant, got: {:?}", parsed),
        }
    }

    #[traced_test]
    fn test_non_string_variant_justification() {
        trace!("test_non_string_variant_justification: starting");
        let input = json!({
            "variant_name": "Probabilistic",
            "variant_confidence": 0.9,
            "variant_justification": 999
        });
        let result = JustifiedCapstoneMode::fuzzy_from_json_value(&input);
        assert!(
            result.is_ok(),
            "Expected Ok even if variant_justification is not a string, got error: {:?}",
            result.err()
        );
        let parsed = result.unwrap();
        match parsed {
            JustifiedCapstoneMode::Probabilistic {
                variant_confidence,
                variant_justification,
            } => {
                assert_eq!(variant_confidence, 0.9, "Confidence mismatch");
                assert_eq!(
                    variant_justification, "",
                    "Expected empty justification if not a valid string"
                );
            }
            _ => panic!("Expected Probabilistic variant, got: {:?}", parsed),
        }
    }
}