capability_grower_configuration/

grower_tree_configuration.rs

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

/// We set the GrowerTreeConfiguration to refine the shape of our model trees:
/// - **Depth**: # of hierarchical levels (≥1)
/// - **Breadth**: baseline sibling count (≥1)
/// - **Density**: variants at leaves (≥1)
/// - **leaf_granularity**: fraction [0..1] controlling fine detail at leaves
/// - **balance_symmetry**: fraction [0..1] controlling symmetrical vs. varied structure
/// - **complexity**: overall complexity level (simple, balanced, or complex)
///
/// Optional advanced sub-structs:
/// - **level_specific**: arrays of breadth/density overrides for each level
/// - **weighted_branching**: mean ± variance approach
/// - **level_skipping**: per-level leaf probabilities
/// - **capstone**: highlight nodes (off, single, or fraction)
/// - **ordering**: sub-branch sorting approach
/// - **ai_confidence**: modifies branch factor based on AI certainty
///
/// New fields:
/// - **aggregator_preference**: fraction [0..1] controlling how often aggregator is used vs. dispatch
/// - **allow_early_leaves**: if true, allows leaf nodes to appear before the final depth
/// - **partial_subbranch_probability**: fraction [0..1] controlling how often each child sub-branch is included
/// - **tree_expansion_policy**: advanced logic for picking among aggregator/dispatch/leaf
/// - **aggregator_depth_limit**, **dispatch_depth_limit**, **leaf_min_depth**: optional constraints on usage of aggregator, dispatch, or leaf nodes by depth
///
/// Your justification must indicate why each justified parameter value was chosen deliberately by
/// using knowledge and an understanding of the target domain as a guide. Since each target domain
/// is different, the trees which map them will have different shapes and different
/// GrowerTreeConfiguration parameters. Your job during justification is to explain clearly why
/// a given parameter setting makes sense in the provided target domain.
#[derive(
    SaveLoad,
    Debug,
    Clone,
    PartialEq,
    Getters,
    Builder,
    Serialize,
    Deserialize,
    AiJsonTemplate,
    AiJsonTemplateWithJustification,
)]
#[builder(pattern = "owned", setter(into), build_fn(name = "try_build"))]
#[getset(get = "pub")]
pub struct GrowerTreeConfiguration {

    /// This field holds *verbatim* the lower-kebab-case target-name belonging to the tree grow process.
    #[builder(default = "\"target\".to_string()")]
    #[serde(default)]
    target_name: String,

    /// Set this integer to define how many levels exist from root to leaf in the tree (≥5).
    /// - Setting a higher number → deeper specialization (depth).
    /// - Setting a lower number → simpler, more general modeling.
    #[builder(default = "4")]
    #[serde(deserialize_with = "fuzzy_u8")]
    depth: u8,

    /// Set this integer to define how many siblings or sub-branches each node has by default (≥7).
    /// - Higher → broad coverage, e.g. "Spread (Loosen)."
    /// - Lower → narrower, e.g. "Narrow (Tighten)."
    #[builder(default = "2")]
    #[serde(deserialize_with = "fuzzy_u8")]
    breadth: u8,

    /// Set this integer to define how many variants (children) each leaf node holds by default (≥9).
    /// - Higher → more fullness ("Dense").
    /// - Lower → sparser representation ("Sparse").
    #[builder(default = "2")]
    #[serde(deserialize_with = "fuzzy_u8")]
    density: u8,

    /// Set this fraction [0..1] to specify how finely detailed each leaf item becomes.
    /// - 0 = coarse (broad, less specialized leaves),
    /// - 1 = extremely specific leaves.
    #[builder(default = "0.5")]
    leaf_granularity: f32,

    /// Set this fraction [0..1] to numerically characerize the symmetrical vs. unbalanced structure of our tree.
    /// - 0.0 = random/unbalanced,
    /// - 1.0 = perfectly balanced.
    #[builder(default = "0.5")]
    balance_symmetry: f32,

    /// Set this field to select between "simple", "balanced", or "complex" for overall usage patterns.
    #[builder(default)]
    complexity: ConfigurationComplexity,

    /// Set this optional sub-struct to specify the arrays for per-level breadth & density overrides.
    #[builder(default)]
    level_specific: Option<TreeLevelSpecificConfiguration>,

    /// Set this optional sub-struct to define mean ± variance if you want random branching factors.
    #[builder(default)]
    weighted_branching: Option<WeightedBranchingConfiguration>,

    /// Set this optional sub-struct to define probabilities for skipping deeper expansions at certain levels.
    #[builder(default)]
    level_skipping: Option<LevelSkippingConfiguration>,

    /// Set this optional sub-struct to define the characteristics of capstone leaves, how many of
    /// them there are, and our chances of encountering one at any given level.
    #[builder(default)]
    capstone: Option<CapstoneGenerationConfiguration>,

    /// Set this optional sub-struct to define how sub-branches get ordered (alphabetical, difficulty, random).
    #[builder(default)]
    ordering: Option<SubBranchOrdering>,

    /// Set this optional sub-struct to define how AI confidence modifies branch factor (if any).
    #[builder(default)]
    ai_confidence: Option<AiTreeBranchingConfidenceConfiguration>,

    /// Set this fraction [0..1] to control how often aggregator nodes are used vs. dispatch nodes at
    /// intermediate levels. 
    /// - 0.0 => always dispatch 
    /// - 1.0 => always aggregator 
    /// - 0.5 => half aggregator, half dispatch
    /// 
    /// This is a simplistic alternative to `tree_expansion_policy`. If tree_expansion_policy is set to something
    /// more advanced, this field might be ignored or used as a fallback.
    #[builder(default = "0.5")]
    aggregator_preference: f32,

    /// If true, leaf nodes may appear before the final `depth`, i.e. some sub-branches might terminate
    /// early with a LeafHolder. 
    /// If false, all leaves appear exactly at `depth`.
    #[builder(default = "false")]
    allow_early_leaves: bool,

    /// Fraction [0..1] controlling how often each potential child sub-branch is included.
    /// - 0.0 => no optional sub-branches 
    /// - 1.0 => all sub-branches are included
    /// 
    /// This might tie into `ChildSpec` `optional` or `probability` fields, e.g. randomizing 
    /// which children appear. 
    #[builder(default = "1.0")]
    partial_subbranch_probability: f32,

    /// An advanced enum describing how to pick among `Dispatch`, `Aggregate`, or `LeafHolder`
    /// at each level. 
    /// - If you set this to `NodeVariantStrategy::Simple`, you get a straightforward approach
    ///   where we do dispatch at intermediate nodes and leaves at final depth.
    /// - If you use `Weighted`, you can do random picks among aggregator/dispatch/leaf.
    /// - If you do `DepthBased`, you can specify exactly which level to start aggregator vs. leaf.
    #[builder(default)]
    tree_expansion_policy: TreeExpansionPolicy,

    /// If set, aggregator nodes will not appear deeper than this level. 
    /// If `None`, no limit. 
    /// If `Some(n)`, aggregator variant is disallowed for levels > n.
    #[builder(default)]
    #[serde(deserialize_with = "fuzzy_option_u8")]
    #[serde(default)]
    aggregator_depth_limit: Option<u8>,

    /// If set, dispatch nodes will not appear deeper than this level.
    /// If `None`, no limit.
    /// If `Some(n)`, dispatch variant is disallowed for levels > n.
    #[builder(default)]
    #[serde(deserialize_with = "fuzzy_option_u8")]
    #[serde(default)]
    dispatch_depth_limit: Option<u8>,

    /// If set, leaf-holder nodes cannot appear before this level (forces deeper expansions).
    /// If `None`, no minimum.
    /// If `Some(n)`, we skip leaf-holder variants until level ≥ n.
    #[builder(default)]
    #[serde(deserialize_with = "fuzzy_option_u8")]
    #[serde(default)]
    leaf_min_depth: Option<u8>,
}

impl Default for GrowerTreeConfiguration {
    fn default() -> Self {
        GrowerTreeConfigurationBuilder::default()
            .build()
            .unwrap()
    }
}

impl GrowerTreeConfigurationBuilder {
    /// Consume the builder, construct the config, then validate it before returning.
    pub fn build(
        self,
    ) -> Result<GrowerTreeConfiguration, GrowerTreeConfigurationError> {

        // First, use the generated try_build (which checks for missing fields)
        //
        // IMPORTANT: this cannot be set to `build` or we will get a hidden recusion
        let config = self.try_build()?;
        // Then validate all semantic constraints
        config.validate()?;
        Ok(config)
    }
}

impl GrowerTreeConfiguration {

    /// This function should validate all fields: baseline parameters and each advanced sub-struct if present.
    /// Returns an error if any invalid configuration is detected.
    #[instrument(level = "trace", skip(self))]
    pub fn validate(&self) -> Result<(), GrowerTreeConfigurationError> {
        if self.depth == 0 {
            return Err(GrowerTreeConfigurationError::DepthMustBeAtLeastOne);
        }
        if self.breadth == 0 {
            return Err(GrowerTreeConfigurationError::BreadthMustBeAtLeastOne);
        }
        if self.density == 0 {
            return Err(GrowerTreeConfigurationError::DensityMustBeAtLeastOne);
        }

        if !(0.0..=1.0).contains(&self.leaf_granularity) {
            return Err(GrowerTreeConfigurationError::LeafGranularityMustBeWithinZeroOne);
        }
        if !(0.0..=1.0).contains(&self.balance_symmetry) {
            return Err(GrowerTreeConfigurationError::BalanceSymmetryMustBeWithinZeroOne);
        }

        if let Some(ref ls) = self.level_specific {
            ls.validate(self.depth)?;
        }
        if let Some(ref wb) = self.weighted_branching {
            wb.validate()?;
        }
        if let Some(ref skip) = self.level_skipping {
            skip.validate(self.depth)?;
        }
        if let Some(ref cap) = self.capstone {
            cap.validate()?;
        }
        if let Some(ref ai_conf) = self.ai_confidence {
            ai_conf.validate()?;
        }

        Ok(())
    }

    /// This function should parse a `GrowerTreeConfiguration` from TOML string input.
    #[instrument(level = "trace")]
    pub fn from_toml_str(s: &str) -> Result<Self, GrowerTreeConfigurationError> {
        let cfg: GrowerTreeConfiguration = toml::from_str(s)
            .map_err(GrowerTreeConfigurationError::TomlDeError)?;
        Ok(cfg)
    }

    /// This function should convert the `GrowerTreeConfiguration` into a pretty TOML string.
    #[instrument(level = "trace", skip(self))]
    pub fn to_toml_string(&self) -> Result<String, GrowerTreeConfigurationError> {
        let out = toml::to_string_pretty(self)
            .map_err(GrowerTreeConfigurationError::TomlSerError)?;
        Ok(out)
    }

    /// This function should load a `GrowerTreeConfiguration` from a TOML file on disk.
    #[instrument(level = "trace", skip(path))]
    pub fn from_toml_file<P: AsRef<Path>>(path: P) -> Result<Self, GrowerTreeConfigurationError> {
        let contents = std::fs::read_to_string(path)
            .map_err(GrowerTreeConfigurationError::IoError)?;
        Self::from_toml_str(&contents)
    }

    /// This function should write the `GrowerTreeConfiguration` to a file in TOML format.
    #[instrument(level = "trace", skip(self, path))]
    pub fn to_toml_file<P: AsRef<Path>>(&self, path: P) -> Result<(), GrowerTreeConfigurationError> {
        let data = self.to_toml_string()?;
        std::fs::write(path, data).map_err(GrowerTreeConfigurationError::IoError)?;
        Ok(())
    }
}

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

        // Must be an object => flatten deeply
        let mut obj = match value.as_object() {
            Some(m) => {
                trace!("(JustifiedGrowerTreeConfiguration) Received JSON object => BFS-flatten all 'fields'.");
                let mut cloned = m.clone();
                flatten_all_fields(&mut cloned);
                cloned
            }
            None => {
                error!("(JustifiedGrowerTreeConfiguration) Received non-object => cannot parse!");
                return Err(FuzzyFromJsonValueError::NotAnObject {
                    target_type: "JustifiedGrowerTreeConfiguration",
                    actual: value.clone(),
                });
            }
        };

        let target_name_val = if let Some(raw) = obj.get("target_name") {
            raw.to_string().to_kebab_case()
        } else {
            warn!("(JustifiedGrowerTreeConfiguration) 'target-name' missing => will default to target-name-unset");
            "target-name-unset".to_string()
        };

        let target_name_conf = get_f64_field(&obj, "target_name_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let target_name_just = get_string_field(&obj, "target_name_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // 1) depth => fuzzy_u8
        let depth_val = if let Some(raw) = obj.get("depth") {
            match fuzzy_u8_from_value(raw) {
                Ok(u) => u,
                Err(e) => {
                    error!("(JustifiedGrowerTreeConfiguration) parse 'depth' => {}", e);
                    return Err(FuzzyFromJsonValueError::Other {
                        target_type: "JustifiedGrowerTreeConfiguration",
                        detail: format!("Cannot parse depth: {}", e),
                    });
                }
            }
        } else {
            debug!("(JustifiedGrowerTreeConfiguration) 'depth' missing => default 0");
            0
        };
        let depth_conf = get_f64_field(&obj, "depth_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let depth_just = get_string_field(&obj, "depth_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // 2) breadth => fuzzy_u8
        let breadth_val = if let Some(raw) = obj.get("breadth") {
            match fuzzy_u8_from_value(raw) {
                Ok(u) => u,
                Err(e) => {
                    error!("(JustifiedGrowerTreeConfiguration) parse 'breadth' => {}", e);
                    return Err(FuzzyFromJsonValueError::Other {
                        target_type: "JustifiedGrowerTreeConfiguration",
                        detail: format!("Cannot parse breadth: {}", e),
                    });
                }
            }
        } else {
            debug!("(JustifiedGrowerTreeConfiguration) 'breadth' missing => default 0");
            0
        };
        let breadth_conf = get_f64_field(&obj, "breadth_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let breadth_just = get_string_field(&obj, "breadth_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // 3) density => fuzzy_u8
        let density_val = if let Some(raw) = obj.get("density") {
            match fuzzy_u8_from_value(raw) {
                Ok(u) => u,
                Err(e) => {
                    error!("(JustifiedGrowerTreeConfiguration) parse 'density' => {}", e);
                    return Err(FuzzyFromJsonValueError::Other {
                        target_type: "JustifiedGrowerTreeConfiguration",
                        detail: format!("Cannot parse density: {}", e),
                    });
                }
            }
        } else {
            debug!("(JustifiedGrowerTreeConfiguration) 'density' missing => default 0");
            0
        };
        let density_conf = get_f64_field(&obj, "density_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let density_just = get_string_field(&obj, "density_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // leaf_granularity => f32
        let lg_f64 = get_f64_field(&obj, "leaf_granularity", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let leaf_granularity = lg_f64 as f32;
        let lg_conf = get_f64_field(&obj, "leaf_granularity_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let lg_just = get_string_field(&obj, "leaf_granularity_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // balance_symmetry => f32
        let bs_f64 = get_f64_field(&obj, "balance_symmetry", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let balance_symmetry = bs_f64 as f32;
        let bs_conf = get_f64_field(&obj, "balance_symmetry_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let bs_just = get_string_field(&obj, "balance_symmetry_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // aggregator_preference => f32
        let ap_f64 = get_f64_field(&obj, "aggregator_preference", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let aggregator_preference = ap_f64 as f32;
        let ap_conf = get_f64_field(&obj, "aggregator_preference_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let ap_just = get_string_field(&obj, "aggregator_preference_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // allow_early_leaves => bool
        let allow_early_leaves = match obj.get("allow_early_leaves") {
            Some(serde_json::Value::Bool(b)) => *b,
            _ => {
                debug!("(JustifiedGrowerTreeConfiguration) no 'allow_early_leaves' => false");
                false
            }
        };
        let ael_conf = get_f64_field(&obj, "allow_early_leaves_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let ael_just = get_string_field(&obj, "allow_early_leaves_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // partial_subbranch_probability => f32
        let psp_f64 = get_f64_field(&obj, "partial_subbranch_probability", "JustifiedGrowerTreeConfiguration").unwrap_or(1.0);
        let partial_subbranch_probability = psp_f64 as f32;
        let psp_conf = get_f64_field(&obj, "partial_subbranch_probability_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let psp_just = get_string_field(&obj, "partial_subbranch_probability_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // aggregator_depth_limit => fuzzy_option_u8
        let adl_val = obj.get("aggregator_depth_limit");
        let aggregator_depth_limit = match adl_val {
            Some(val) => match fuzzy_option_u8_from_value(val) {
                Ok(opt) => opt,
                Err(e) => {
                    error!("(JustifiedGrowerTreeConfiguration) aggregator_depth_limit parse => {}", e);
                    return Err(FuzzyFromJsonValueError::Other {
                        target_type: "JustifiedGrowerTreeConfiguration",
                        detail: format!("Error aggregator_depth_limit: {:?}", e),
                    });
                }
            },
            None => None,
        };
        let adl_conf = get_f64_field(&obj, "aggregator_depth_limit_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let adl_just = get_string_field(&obj, "aggregator_depth_limit_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // dispatch_depth_limit => fuzzy_option_u8
        let ddl_val = obj.get("dispatch_depth_limit");
        let dispatch_depth_limit = match ddl_val {
            Some(val) => match fuzzy_option_u8_from_value(val) {
                Ok(opt) => opt,
                Err(e) => {
                    error!("(JustifiedGrowerTreeConfiguration) dispatch_depth_limit parse => {}", e);
                    return Err(FuzzyFromJsonValueError::Other {
                        target_type: "JustifiedGrowerTreeConfiguration",
                        detail: format!("Error dispatch_depth_limit: {:?}", e),
                    });
                }
            },
            None => None,
        };
        let ddl_conf = get_f64_field(&obj, "dispatch_depth_limit_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let ddl_just = get_string_field(&obj, "dispatch_depth_limit_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // leaf_min_depth => fuzzy_option_u8
        let lmd_val = obj.get("leaf_min_depth");
        let leaf_min_depth = match lmd_val {
            Some(val) => match fuzzy_option_u8_from_value(val) {
                Ok(opt) => opt,
                Err(e) => {
                    error!("(JustifiedGrowerTreeConfiguration) leaf_min_depth parse => {}", e);
                    return Err(FuzzyFromJsonValueError::Other {
                        target_type: "JustifiedGrowerTreeConfiguration",
                        detail: format!("Error leaf_min_depth: {:?}", e),
                    });
                }
            },
            None => None,
        };
        let lmd_conf = get_f64_field(&obj, "leaf_min_depth_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let lmd_just = get_string_field(&obj, "leaf_min_depth_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // complexity => optional => fallback Balanced if missing
        let complexity_val = obj.get("complexity");
        let (complexity, complexity_conf, complexity_just) = match complexity_val {
            Some(cv) => {
                let cparsed = JustifiedConfigurationComplexity::fuzzy_from_json_value(cv)?;
                let cc = get_f64_field(&obj, "complexity_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
                let cj = get_string_field(&obj, "complexity_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();
                (cparsed, cc, cj)
            }
            None => {
                debug!("(JustifiedGrowerTreeConfiguration) no 'complexity' => default Balanced");
                let fallback = JustifiedConfigurationComplexity::Balanced {
                    variant_confidence: 0.0,
                    variant_justification: "".to_string(),
                };
                (fallback, 0.0, "".to_string())
            }
        };

        // level_specific => optional
        let level_spec_parsed = match obj.get("level_specific") {
            Some(x) => Some(JustifiedTreeLevelSpecificConfiguration::fuzzy_from_json_value(x)?),
            None => None,
        };
        let ls_conf = get_f64_field(&obj, "level_specific_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let ls_just = get_string_field(&obj, "level_specific_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // weighted_branching => optional
        let wb_parsed = match obj.get("weighted_branching") {
            Some(x) => Some(JustifiedWeightedBranchingConfiguration::fuzzy_from_json_value(x)?),
            None => None,
        };
        let wb_conf = get_f64_field(&obj, "weighted_branching_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let wb_just = get_string_field(&obj, "weighted_branching_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // level_skipping => optional
        let lskip_parsed = match obj.get("level_skipping") {
            Some(x) => Some(JustifiedLevelSkippingConfiguration::fuzzy_from_json_value(x)?),
            None => None,
        };
        let lskip_conf = get_f64_field(&obj, "level_skipping_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let lskip_just = get_string_field(&obj, "level_skipping_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // capstone => optional
        let cap_parsed = match obj.get("capstone") {
            Some(x) => Some(JustifiedCapstoneGenerationConfiguration::fuzzy_from_json_value(x)?),
            None => None,
        };
        let cap_conf = get_f64_field(&obj, "capstone_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let cap_just = get_string_field(&obj, "capstone_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // ordering => optional
        let ordering_parsed = match obj.get("ordering") {
            Some(x) => Some(JustifiedSubBranchOrdering::fuzzy_from_json_value(x)?),
            None => None,
        };
        let ordering_conf = get_f64_field(&obj, "ordering_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let ordering_just = get_string_field(&obj, "ordering_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // ai_confidence => optional
        let ai_conf_parsed = match obj.get("ai_confidence") {
            Some(x) => Some(JustifiedAiTreeBranchingConfidenceConfiguration::fuzzy_from_json_value(x)?),
            None => None,
        };
        let aic_conf = get_f64_field(&obj, "ai_confidence_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
        let aic_just = get_string_field(&obj, "ai_confidence_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();

        // tree_expansion_policy => optional => fallback "Simple" if missing
        let tep_val = obj.get("tree_expansion_policy");
        let (tree_expansion_policy, tep_conf, tep_just) = match tep_val {
            Some(tv) => {
                let parsed = JustifiedTreeExpansionPolicy::fuzzy_from_json_value(tv)?;
                let cf = get_f64_field(&obj, "tree_expansion_policy_confidence", "JustifiedGrowerTreeConfiguration").unwrap_or(0.0);
                let cj = get_string_field(&obj, "tree_expansion_policy_justification", "JustifiedGrowerTreeConfiguration").unwrap_or_default();
                (parsed, cf, cj)
            }
            None => {
                debug!("(JustifiedGrowerTreeConfiguration) no 'tree_expansion_policy' => default=>Simple");
                let fallback = JustifiedTreeExpansionPolicy::Simple {
                    variant_confidence: 0.0,
                    variant_justification: "".to_string(),
                };
                (fallback, 0.0, "".to_string())
            }
        };

        let jcfg = JustifiedGrowerTreeConfiguration {
            target_name:               target_name_val,
            target_name_confidence:    target_name_conf,
            target_name_justification: target_name_just,
            depth:                     depth_val,
            depth_confidence:          depth_conf,
            depth_justification:       depth_just,

            breadth: breadth_val,
            breadth_confidence: breadth_conf,
            breadth_justification: breadth_just,

            density: density_val,
            density_confidence: density_conf,
            density_justification: density_just,

            leaf_granularity,
            leaf_granularity_confidence: lg_conf,
            leaf_granularity_justification: lg_just,

            balance_symmetry,
            balance_symmetry_confidence: bs_conf,
            balance_symmetry_justification: bs_just,

            complexity,
            complexity_confidence: complexity_conf,
            complexity_justification: complexity_just,

            level_specific: level_spec_parsed,
            level_specific_confidence: ls_conf,
            level_specific_justification: ls_just,

            weighted_branching: wb_parsed,
            weighted_branching_confidence: wb_conf,
            weighted_branching_justification: wb_just,

            level_skipping: lskip_parsed,
            level_skipping_confidence: lskip_conf,
            level_skipping_justification: lskip_just,

            capstone: cap_parsed,
            capstone_confidence: cap_conf,
            capstone_justification: cap_just,

            ordering: ordering_parsed,
            ordering_confidence: ordering_conf,
            ordering_justification: ordering_just,

            ai_confidence: ai_conf_parsed,
            ai_confidence_confidence: aic_conf,
            ai_confidence_justification: aic_just,

            aggregator_preference,
            aggregator_preference_confidence: ap_conf,
            aggregator_preference_justification: ap_just,

            allow_early_leaves,
            allow_early_leaves_confidence: ael_conf,
            allow_early_leaves_justification: ael_just,

            partial_subbranch_probability,
            partial_subbranch_probability_confidence: psp_conf,
            partial_subbranch_probability_justification: psp_just,

            aggregator_depth_limit,
            aggregator_depth_limit_confidence: adl_conf,
            aggregator_depth_limit_justification: adl_just,

            dispatch_depth_limit,
            dispatch_depth_limit_confidence: ddl_conf,
            dispatch_depth_limit_justification: ddl_just,

            leaf_min_depth,
            leaf_min_depth_confidence: lmd_conf,
            leaf_min_depth_justification: lmd_just,

            tree_expansion_policy,
            tree_expansion_policy_confidence: tep_conf,
            tree_expansion_policy_justification: tep_just,
        };

        trace!("(JustifiedGrowerTreeConfiguration) Successfully constructed => returning Ok.");
        Ok(jcfg)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // ------------------------------------------------------------------------
    // Sub-structure test modules, verifying each with an exhaustive approach
    // ------------------------------------------------------------------------

    mod test_weighted_branching {
        use super::*;

        #[traced_test]
        fn test_valid() {
            let wb = WeightedBranchingConfigurationBuilder::default()
                .mean(4)
                .variance(3)
                .build()
                .unwrap();
            assert!(wb.validate().is_ok());
        }

        #[traced_test]
        fn test_variance_exceeds_mean() {
            let wb = WeightedBranchingConfigurationBuilder::default()
                .mean(2)
                .variance(4)
                .build()
                .unwrap();
            let res = wb.validate();
            assert!(res.is_err());
            assert!(matches!(res.err().unwrap(), GrowerTreeConfigurationError::WeightedBranchMeanLessThanVariance));
        }

        #[traced_test]
        fn test_mean_zero() {
            let wb = WeightedBranchingConfigurationBuilder::default()
                .mean(0)
                .variance(0)
                .build()
                .unwrap();
            let res = wb.validate();
            assert!(res.is_err());
            assert!(matches!(res.err().unwrap(), GrowerTreeConfigurationError::WeightedBranchMeanCannotBeZero));
        }
    }

    mod test_level_specific {
        use super::*;

        #[traced_test]
        fn test_valid() {
            let ls = TreeLevelSpecificConfigurationBuilder::default()
                .breadth_per_level(vec![3,4])
                .density_per_level(vec![2,5])
                .build()
                .unwrap();
            assert!(ls.validate(3).is_ok());
        }

        #[traced_test]
        fn test_breadth_len_exceeds_depth() {
            let ls = TreeLevelSpecificConfigurationBuilder::default()
                .breadth_per_level(vec![3,4,5,6])
                .density_per_level(vec![2])
                .build()
                .unwrap();
            let res = ls.validate(3);
            assert!(res.is_err());
            assert!(matches!(res.err().unwrap(), GrowerTreeConfigurationError::LevelSpecificBreadthLenExceedsDepth));
        }
    }

    mod test_level_skipping {
        use super::*;

        #[traced_test]
        fn test_valid() {
            let skip = LevelSkippingConfigurationBuilder::default()
                .leaf_probability_per_level(vec![0.0,0.2,0.4])
                .build()
                .unwrap();
            assert!(skip.validate(3).is_ok());
        }

        #[traced_test]
        fn test_probability_exceeds_depth() {
            let skip = LevelSkippingConfigurationBuilder::default()
                .leaf_probability_per_level(vec![0.0,0.2,0.4,0.6])
                .build()
                .unwrap();
            let res = skip.validate(3);
            assert!(res.is_err());
            assert!(matches!(res.err().unwrap(), GrowerTreeConfigurationError::LeafProbabilityLenExceedsDepth));
        }

        #[traced_test]
        fn test_probability_out_of_range() {
            let skip = LevelSkippingConfigurationBuilder::default()
                .leaf_probability_per_level(vec![-0.1,1.1])
                .build()
                .unwrap();
            let res = skip.validate(3);
            assert!(res.is_err());
            // We expect LeafProbabilityOutOfRange
        }
    }

    mod test_capstone {
        use super::*;

        #[traced_test]
        fn test_off_ok() {
            let cap = CapstoneGenerationConfigurationBuilder::default()
                .mode(CapstoneMode::Off)
                .probability(0.0)
                .build()
                .unwrap();
            assert!(cap.validate().is_ok());
        }

        #[traced_test]
        fn test_single_ok() {
            let cap = CapstoneGenerationConfigurationBuilder::default()
                .mode(CapstoneMode::Single)
                .probability(0.0)
                .build()
                .unwrap();
            assert!(cap.validate().is_ok());
        }

        #[traced_test]
        fn test_probabilistic_valid() {
            let cap = CapstoneGenerationConfigurationBuilder::default()
                .mode(CapstoneMode::Probabilistic)
                .probability(0.5)
                .build()
                .unwrap();
            assert!(cap.validate().is_ok());
        }

        #[traced_test]
        fn test_probabilistic_out_of_range() {
            let cap = CapstoneGenerationConfigurationBuilder::default()
                .mode(CapstoneMode::Probabilistic)
                .probability(1.2)
                .build()
                .unwrap();
            let res = cap.validate();
            assert!(res.is_err());
            assert!(matches!(res.err().unwrap(), GrowerTreeConfigurationError::CapstoneProbabilityOutOfRange));
        }
    }

    mod test_ai_confidence {
        use super::*;

        #[traced_test]
        fn test_valid() {
            let aic = AiTreeBranchingConfidenceConfigurationBuilder::default()
                .base_factor(4)
                .factor_multiplier(0.5)
                .build()
                .unwrap();
            assert!(aic.validate().is_ok());
        }

        #[traced_test]
        fn test_negative_multiplier() {
            let aic = AiTreeBranchingConfidenceConfigurationBuilder::default()
                .base_factor(2)
                .factor_multiplier(-0.1)
                .build()
                .unwrap();
            let res = aic.validate();
            assert!(res.is_err());
            assert!(matches!(res.err().unwrap(), GrowerTreeConfigurationError::AIConfidenceFactorNegative));
        }
    }

    // ------------------------------------------------------------------------
    // Finally, test the main struct with sub-structs
    // ------------------------------------------------------------------------

    #[traced_test]
    fn test_main_config_ok() {
        let cfg = GrowerTreeConfigurationBuilder::default()
            .depth(3)
            .breadth(2)
            .density(2)
            .leaf_granularity(0.5)
            .balance_symmetry(0.5)
            .complexity(ConfigurationComplexity::Balanced)
            // Provide sub-struct
            .weighted_branching(Some(
                WeightedBranchingConfigurationBuilder::default()
                    .mean(4)
                    .variance(1)
                    .build()
                    .unwrap()
            ))
            .build()
            .unwrap();
        cfg.validate().unwrap();
    }

    #[traced_test]
    fn test_main_config_toml_round_trip() {
        let cfg = GrowerTreeConfigurationBuilder::default()
            .depth(2)
            .breadth(2)
            .density(2)
            .leaf_granularity(0.6)
            .balance_symmetry(0.6)
            .complexity(ConfigurationComplexity::Complex)
            .build()
            .unwrap();

        let toml_str = cfg.to_toml_string().unwrap();
        let parsed = GrowerTreeConfiguration::from_toml_str(&toml_str).unwrap();
        parsed.validate().unwrap();
        assert_eq!(parsed, cfg);
    }

    #[traced_test]
    fn test_main_config_file_io() {
        let dir = tempdir().unwrap();
        let file_path = dir.path().join("cfg.toml");

        let cfg = GrowerTreeConfigurationBuilder::default()
            .depth(5)
            .breadth(3)
            .density(4)
            .leaf_granularity(0.8)
            .balance_symmetry(0.4)
            .complexity(ConfigurationComplexity::Simple)
            .build()
            .unwrap();

        cfg.validate().unwrap();
        cfg.to_toml_file(&file_path).unwrap();

        let loaded = GrowerTreeConfiguration::from_toml_file(&file_path).unwrap();
        loaded.validate().unwrap();
        assert_eq!(loaded, cfg);
    }

    #[traced_test]
    #[disable]
    fn test_ai_json_template_schema_generation() {
        // 1) Construct a GrowerTreeConfiguration with some sample data:
        let config = GrowerTreeConfigurationBuilder::default()
            .depth(3)
            .breadth(2)
            .density(2)
            .leaf_granularity(0.7)
            .balance_symmetry(0.5)
            .complexity(ConfigurationComplexity::Complex)
            // Provide a sub-struct, e.g. weighted branching
            .weighted_branching(Some(
                WeightedBranchingConfigurationBuilder::default()
                    .mean(4)
                    .variance(1)
                    .build()
                    .unwrap()
            ))
            .build()
            .expect("Failed building GrowerTreeConfiguration");

        // 2) Call to_template(), producing the JSON schema describing the config for AI generation:
        let schema_json = GrowerTreeConfiguration::to_template();

        // 3) Optionally print it out for debugging/logging:
        info!("AiJsonTemplate => {:#?}", schema_json);

        // 4) Perform some basic assertions on the schema structure:
        //    e.g., check that "fields" is present, or "struct_name" is correct, etc.
        assert!(schema_json.is_object(), "Top-level schema should be an object.");

        let root_obj = schema_json.as_object().unwrap();
        assert!(root_obj.contains_key("struct_name"), "Schema must contain 'struct_name'");
        assert_eq!(root_obj["struct_name"], "GrowerTreeConfiguration");

        // 5) Check that the "fields" sub-object exists:
        let fields_val = root_obj.get("fields").expect("Schema must contain 'fields'");
        assert!(fields_val.is_object(), "'fields' should be an object.");

        // 6) Inspect one of the fields (e.g. "leaf_granularity") to ensure it has instructions:
        let fields_obj = fields_val.as_object().unwrap();
        let leaf_granularity_schema = fields_obj.get("leaf_granularity").expect("Expected 'leaf_granularity' in schema");

        // Example: leaf_granularity_schema should have "type":"number", "required":true, etc.
        let schema_map = leaf_granularity_schema.as_object().expect("Should be an object schema");
        assert_eq!(schema_map["type"], "number", "leaf_granularity must be numeric in AI schema");
        assert_eq!(schema_map["required"], true, "leaf_granularity is not optional.");

        // 7) If desired, parse instructions or do more assertions here.
        // e.g., let instructions = schema_map["generation_instructions"].as_str().unwrap();
        //       assert!(instructions.contains("fraction [0..1]"), "Should mention fraction range in doc comment.");

        // If it reaches here, the test is considered passing.
    }
}