capability_grower_configuration/

capstone_generation_configuration.rs

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

/// In the context of our tree-generation system, a capstone node is a special type of leaf node
/// that represents a culminating skill, concept, or endpoint of a hierarchical branch. 
///
/// Capstone nodes stand out clearly as a final, specialized mastery points—often signifying an advanced,
/// important, or unique skill within a skill-tree.
///
/// Capstone nodes act as distinctive markers, clearly communicating to users that this particular node is either:
/// - Essential: representing the core or pinnacle achievement of a skill branch.
/// - Prestigious: indicating a high-level mastery or rare skill.
/// - Strategic: highlighting a concept that offers substantial practical or conceptual leverage.
///
/// This struct merges the chosen capstone mode with its relevant probability (if any).
///
#[derive(
    SaveLoad,
    Debug, 
    Clone, 
    PartialEq, 
    Getters, 
    Builder, 
    Default, 
    Serialize, 
    Deserialize, 
    AiJsonTemplate,
    AiJsonTemplateWithJustification,
)]
#[builder(pattern="owned", setter(into))]
#[getset(get="pub")]
pub struct CapstoneGenerationConfiguration {
    /// This field should be one of Off, Single, or Probabilistic.
    mode: CapstoneMode,

    /// This fraction [0..1] is only meaningful if `mode=Probabilistic`, specifying
    /// which fraction of leaves become highlight/capstones.
    probability: f32,
}

impl CapstoneGenerationConfiguration {
    pub fn validate(&self) -> Result<(), GrowerTreeConfigurationError> {
        if self.mode == CapstoneMode::Probabilistic {
            if !(0.0..=1.0).contains(&self.probability) {
                return Err(GrowerTreeConfigurationError::CapstoneProbabilityOutOfRange);
            }
        }
        Ok(())
    }
}

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

        // 1) If null => default
        if value.is_null() {
            debug!("(JustifiedCapstoneGenerationConfiguration) Null => returning default with mode=Off, probability=0");
            return Ok(Self {
                mode: JustifiedCapstoneMode::Off {
                    variant_confidence: 0.0,
                    variant_justification: String::new(),
                },
                mode_confidence: 0.0,
                mode_justification: String::new(),
                probability: 0.0,
                probability_confidence: 0.0,
                probability_justification: String::new(),
            });
        }

        // 2) Must be an object => parse
        let mut obj = match value.as_object() {
            Some(m) => {
                trace!("(JustifiedCapstoneGenerationConfiguration) Found object => flattening if needed.");
                let mut cloned = m.clone();
                flatten_all_fields(&mut cloned);
                cloned
            }
            None => {
                error!("(JustifiedCapstoneGenerationConfiguration) Not an object => fail!");
                return Err(FuzzyFromJsonValueError::NotAnObject {
                    target_type: "JustifiedCapstoneGenerationConfiguration",
                    actual: value.clone(),
                });
            }
        };

        // 3) We parse the "mode" field (which is required). Then leftover fields 
        //    like "mode_confidence" or "probability" belong to the parent struct.
        trace!("(JustifiedCapstoneGenerationConfiguration) Parsing 'mode' => sub-enum fuzzy");
        let raw_mode_val = match obj.remove("mode") {
            Some(sub) => sub,
            None => {
                error!("(JustifiedCapstoneGenerationConfiguration) Missing 'mode' => cannot parse!");
                return Err(FuzzyFromJsonValueError::MissingField {
                    field_name: "mode",
                    target_type: "JustifiedCapstoneGenerationConfiguration",
                });
            }
        };

        // We'll parse the child's (JustifiedCapstoneMode) logic here
        let mode_val: JustifiedCapstoneMode = match raw_mode_val.as_object() {
            Some(mode_map) => {
                // We do a single-key unify if there's exactly one recognized variant (Off, Single, Probabilistic)
                let mut mode_obj = mode_map.clone();
                flatten_all_fields(&mut mode_obj);

                let recognized_variants = &["Off", "Single", "Probabilistic"];
                let mut found_variant_keys = Vec::new();
                for k in mode_obj.keys() {
                    if recognized_variants
                        .iter()
                        .any(|known| known.eq_ignore_ascii_case(k))
                    {
                        found_variant_keys.push(k.clone());
                    }
                }

                if found_variant_keys.len() == 1 {
                    // unify that recognized variant into "variant_name"
                    let variant_key = found_variant_keys[0].clone();
                    trace!(
                        "(JustifiedCapstoneGenerationConfiguration) Found single variant='{}' in 'mode' object => unifying",
                        variant_key
                    );

                    let variant_val = mode_obj.remove(&variant_key).unwrap_or(serde_json::Value::Null);

                    let mut new_map = serde_json::Map::new();
                    new_map.insert("variant_name".to_string(), serde_json::Value::String(variant_key));

                    if let Some(nested_obj) = variant_val.as_object() {
                        // merge subfields
                        for (kk, vv) in nested_obj {
                            new_map.insert(kk.clone(), vv.clone());
                        }
                    }
                    // Now parse the recognized capstone variant
                    let wrapped = serde_json::Value::Object(new_map);
                    JustifiedCapstoneMode::fuzzy_from_json_value(&wrapped)
                        .map_err(|err| {
                            error!("(JustifiedCapstoneGenerationConfiguration) error parsing single variant key => {:?}", err);
                            err
                        })?
                } else {
                    // fallback => maybe "variant_name" or some other shape
                    let reconstructed = serde_json::Value::Object(mode_obj);
                    JustifiedCapstoneMode::fuzzy_from_json_value(&reconstructed)
                        .map_err(|err| {
                            error!("(JustifiedCapstoneGenerationConfiguration) error parsing 'mode' => {:?}", err);
                            err
                        })?
                }
            }
            None => {
                // If the user wrote `"mode": "Off"` or similar => direct parse:
                JustifiedCapstoneMode::fuzzy_from_json_value(&raw_mode_val)
                    .map_err(|err| {
                        error!("(JustifiedCapstoneGenerationConfiguration) 'mode' parse error => {:?}", err);
                        err
                    })?
            }
        };

        // Now parse leftover fields belonging to this parent struct:
        // e.g. "mode_confidence","mode_justification","probability", etc.
        let mode_conf = get_f64_field(&obj, "mode_confidence", "JustifiedCapstoneGenerationConfiguration")
            .unwrap_or(0.0);
        let mode_just = get_string_field(&obj, "mode_justification", "JustifiedCapstoneGenerationConfiguration")
            .unwrap_or_default();

        // 5) probability => f32
        trace!("(JustifiedCapstoneGenerationConfiguration) Parsing 'probability' => f32");
        let prob_f64 = get_f64_field(&obj, "probability", "JustifiedCapstoneGenerationConfiguration")
            .unwrap_or(0.0);
        let probability = prob_f64 as f32;

        let prob_conf = get_f64_field(&obj, "probability_confidence", "JustifiedCapstoneGenerationConfiguration")
            .unwrap_or(0.0);
        let prob_just = get_string_field(&obj, "probability_justification", "JustifiedCapstoneGenerationConfiguration")
            .unwrap_or_default();

        trace!("(JustifiedCapstoneGenerationConfiguration) Successfully parsed => returning final struct.");
        Ok(Self {
            mode: mode_val,
            mode_confidence: mode_conf,
            mode_justification: mode_just,
            probability,
            probability_confidence: prob_conf,
            probability_justification: prob_just,
        })
    }
}