cursus.core.config_fields¶

Configuration Field Manager Package.

This package provides robust tools for managing configuration fields, including: - Field categorization for configuration organization - Type-aware serialization and deserialization - Configuration class registration - Configuration merging and loading - Three-tier configuration architecture components

Primary API functions: - merge_and_save_configs: Merge and save multiple config objects to a unified JSON file - load_configs: Load config objects from a saved JSON file - serialize_config: Convert a config object to a JSON-serializable dict with type metadata - deserialize_config: Convert a serialized dict back to a config object

New Three-Tier Architecture Components: - ConfigFieldTierRegistry: Registry for field tier classifications (Tier 1, 2, 3) - DefaultValuesProvider: Provider for default values (Tier 2) - FieldDerivationEngine: Engine for deriving field values (Tier 3) - Essential Input Models: Pydantic models for Data, Model, and Registration configurations

Usage:

```python from ..config_field_manager import merge_and_save_configs, load_configs, ConfigClassStore # Register config classes for type-aware serialization @ConfigClassStore.register class MyConfig:

…

# Merge and save configs configs = [MyConfig(…), AnotherConfig(…)] merge_and_save_configs(configs, “output.json”)

# Load configs loaded_configs = load_configs(“output.json”)

# Using the three-tier architecture from ..config_field_manager import ( ConfigFieldTierRegistry, DefaultValuesProvider,

FieldDerivationEngine, DataConfig, ModelConfig, RegistrationConfig

)

# Apply defaults and derive fields DefaultValuesProvider.apply_defaults(config) field_engine = FieldDerivationEngine() field_engine.derive_fields(config) ```

merge_and_save_configs(config_list, output_file, processing_step_config_base_class=None, workspace_dirs=None)[source]¶

Merge and save multiple configs to a single JSON file.

Uses UnifiedConfigManager for streamlined processing with workspace awareness.

Parameters:

config_list (List[Any]) – List of configuration objects to merge and save
output_file (str) – Path to the output JSON file
processing_step_config_base_class (type | None) – Optional base class to identify processing step configs
workspace_dirs (List[str] | None) – Optional list of workspace directories for step catalog integration

Returns:

The categorized configuration structure

Return type:

dict

Raises:

ValueError – If config_list is empty or contains invalid configs
IOError – If there’s an issue writing to the output file
TypeError – If configs are not serializable

load_configs(input_file, config_classes=None, workspace_dirs=None)[source]¶

Load multiple configs from a JSON file.

Uses UnifiedConfigManager for streamlined processing with workspace awareness.

Parameters:

input_file (str) – Path to the input JSON file
config_classes (Dict[str, Type] | None) – Optional dictionary mapping class names to class types If not provided, UnifiedConfigManager discovery will be used
workspace_dirs (List[str] | None) – Optional list of workspace directories for step catalog integration

Returns:

A dictionary with the following structure:

{

“shared”: {shared_field1: value1, …}, “specific”: {

”StepName1”: {specific_field1: value1, …}, “StepName2”: {specific_field2: value2, …}, …

}

Return type:

dict

Raises:

FileNotFoundError – If the input file doesn’t exist
json.JSONDecodeError – If the input file is not valid JSON
KeyError – If required keys are missing from the file
TypeError – If deserialization fails due to type mismatches

serialize_config(config)[source]¶

Serialize a configuration object to a JSON-serializable dictionary.

This function serializes a configuration object, preserving its type information and special fields. It embeds metadata including the step name derived from attributes like ‘job_type’, ‘data_type’, and ‘mode’.

Parameters:: config (Any) – The configuration object to serialize
Returns:: A serialized representation of the config
Return type:: dict
Raises:: TypeError – If the config is not serializable

deserialize_config(data, config_classes=None)[source]¶

Deserialize a dictionary back into a configuration object.

This function deserializes a dictionary into a configuration object based on type information embedded in the dictionary. If the dictionary contains the __model_type__ field, it will attempt to reconstruct the original object type using the step catalog system.

Parameters:

data (Dict[str, Any]) – The serialized dictionary
config_classes (Dict[str, Type] | None) – Optional dictionary mapping class names to class types If not provided, all classes registered with ConfigClassStore will be used

Returns:

The deserialized configuration object

Return type:

Any

Raises:

TypeError – If the data cannot be deserialized to the specified type

class UnifiedConfigManager(workspace_dirs=None)[source]¶

Bases: object

Single integrated component replacing three separate systems.

Replaces: - ConfigClassStore: Uses step catalog integration - TierRegistry: Uses config classes’ own categorize_fields() methods - CircularReferenceTracker: Simple tier-aware tracking

Total Reduction: 950 lines → 120 lines (87% reduction)

get_config_classes(project_id=None)[source]¶

Get config classes using step catalog integration.

Replaces ConfigClassStore functionality.

Parameters:: project_id (str | None) – Optional project ID for workspace-specific discovery
Returns:: Dictionary mapping class names to class types
Return type:: Dict[str, Type[BaseModel]]

get_field_tiers(config_instance)[source]¶

Get field tier information using config’s own methods.

Replaces TierRegistry functionality by using config classes’ own categorize_fields() methods.

Parameters:: config_instance (BaseModel) – Config instance to categorize
Returns:: Dictionary mapping tier names to field lists
Return type:: Dict[str, List[str]]

get_inheritance_aware_form_fields(config_class_name, config_class=None, inheritance_analysis=None, project_id=None)[source]¶

Get inheritance-aware form fields using the centralized field generator.

CONSOLIDATED: This method provides access to inheritance-aware field generation through the unified_config_manager, delegating to the specialized field generator.

Parameters:

config_class_name (str) – Name of the configuration class
config_class (Type[BaseModel] | None) – Optional config class (will be discovered if not provided)
inheritance_analysis (Dict[str, Any] | None) – Optional inheritance analysis from StepCatalog
project_id (str | None) – Optional project ID for workspace-specific processing

Returns:

List of enhanced field definitions with inheritance information

Return type:

List[Dict[str, Any]]

load(input_file, config_classes=None)[source]¶

Load a merged configuration from a file using UnifiedConfigManager.

Parameters:

input_file (str) – Path to input file
config_classes (Dict[str, type] | None) – Optional mapping of class names to class objects

Returns:

Loaded configuration structure

Return type:

dict

save(config_list, output_file, processing_step_config_base_class=None)[source]¶

Save merged configuration to a file using UnifiedConfigManager.

Includes optimized verification from Phase 1 Day 3-4 improvements.

Parameters:

config_list (List[Any]) – List of configuration objects to merge and save
output_file (str) – Path to output file
processing_step_config_base_class (type | None) – Optional base class for processing steps

Returns:

Merged configuration structure

Return type:

dict

serialize_with_tier_awareness(obj)[source]¶

Serialize object with simple tier-aware circular reference tracking.

Replaces complex CircularReferenceTracker with minimal tracking.

Parameters:: obj (Any) – Object to serialize
Returns:: Serialized object
Return type:: Any

property step_catalog¶: Lazy-load step catalog to avoid import issues.

ConfigClassStore¶: alias of ConfigClassStoreAdapter

register_config_class(cls)[source]¶

This is a convenient alias for ConfigClassStore.register decorator.

Parameters:: cls (Any) – The class to register
Returns:: The class, allowing this to be used as a decorator
Return type:: Any

class StepCatalogAwareConfigFieldCategorizer(config_list, processing_step_config_base_class=None, project_id=None, step_catalog=None, workspace_root=None)[source]¶

Bases: object

Enhanced categorizer with workspace and framework awareness.

Combines all base categorization functionality with enhanced capabilities: - Workspace-specific field categorization - Framework-specific field handling - Step catalog integration - All existing categorization rules preserved

categorize_with_enhanced_metadata()[source]¶

Perform categorization with enhanced metadata.

Returns:: Categorization result with enhanced metadata
Return type:: Dict[str, Any]

get_categorized_fields()[source]¶

Get the categorization result. (Merged from base class)

Returns:: Field categorization
Return type:: dict

get_category_for_field(field_name, config=None)[source]¶

Get the category for a specific field, optionally in a specific config. (Merged from base class)

Parameters:

field_name (str) – Name of the field
config (Any | None) – Optional config instance

Returns:

Category for the field or None if field not found

Return type:

CategoryType

get_enhanced_categorization_info()[source]¶

Get enhanced categorization information.

Returns:: Dictionary with enhanced categorization details
Return type:: Dict[str, Any]

get_field_sources()[source]¶

Get the field sources mapping (inverted index). (Merged from base class)

This creates an inverted index that maps each field name to the list of step names that contain that field.

Returns:: Mapping of field_name -> list of step names
Return type:: dict

print_categorization_stats()[source]¶

Print statistics about field categorization for the simplified structure. (Merged from base class)

class InheritanceAwareFieldGenerator(workspace_dirs=None, project_id=None)[source]¶

Bases: object

Centralized inheritance-aware field generation.

Provides systematic inheritance-aware field enhancement using the existing unified_config_manager infrastructure instead of manual inheritance logic.

get_enhanced_field_categorization(config_list, processing_step_config_base_class=None)[source]¶

Get enhanced field categorization using step catalog aware categorizer.

Parameters:

config_list (List[BaseModel]) – List of configuration objects to categorize
processing_step_config_base_class (Type | None) – Optional base class for processing steps

Returns:

Enhanced categorization with inheritance and workspace awareness

Return type:

Dict[str, Any]

get_inheritance_aware_form_fields(config_class_name, config_class=None, inheritance_analysis=None)[source]¶

Generate form fields with Smart Default Value Inheritance awareness.

CONSOLIDATED: This method replaces manual inheritance logic from config_ui with systematic tier-aware field enhancement using unified_config_manager.

Creates the enhanced 4-tier field system: - Tier 1 (essential): Required fields with no defaults (NEW to this config) - Tier 2 (system): Optional fields with defaults (NEW to this config) - Tier 3 (inherited): Fields inherited from parent configs (NEW TIER) - Tier 4 (derived): Computed fields (hidden from UI)

Parameters:

config_class_name (str) – Name of the configuration class
config_class (Type[BaseModel] | None) – Optional config class (will be discovered if not provided)
inheritance_analysis (Dict[str, Any] | None) – Optional inheritance analysis from StepCatalog

Returns:

List of enhanced field definitions with inheritance information

Return type:

List[Dict[str, Any]]

get_inheritance_aware_field_generator(workspace_dirs=None, project_id=None)[source]¶

Get an inheritance-aware field generator, cached per (workspace_dirs, project_id).

Parameters:

workspace_dirs (List[str] | None) – Optional workspace directories for step catalog integration
project_id (str | None) – Optional project ID for workspace-specific processing

Returns:

InheritanceAwareFieldGenerator instance (one per distinct context key)

Return type:

InheritanceAwareFieldGenerator

get_inheritance_aware_form_fields(config_class_name, config_class=None, inheritance_analysis=None, workspace_dirs=None, project_id=None)[source]¶

Convenience function to get inheritance-aware form fields.

CONSOLIDATED: This function replaces the manual inheritance logic from config_ui with systematic tier-aware field enhancement using unified_config_manager.

Parameters:

config_class_name (str) – Name of the configuration class
config_class (Type[BaseModel] | None) – Optional config class (will be discovered if not provided)
inheritance_analysis (Dict[str, Any] | None) – Optional inheritance analysis from StepCatalog
workspace_dirs (List[str] | None) – Optional workspace directories for step catalog integration
project_id (str | None) – Optional project ID for workspace-specific processing

Returns:

List of enhanced field definitions with inheritance information

Return type:

List[Dict[str, Any]]

ConfigClassDetector¶: alias of ConfigClassDetectorAdapter

detect_config_classes_from_json(config_path)[source]¶

Legacy function: detect config classes using catalog.

build_complete_config_classes(project_id=None)[source]¶

Legacy function: build complete config classes using catalog.

Modules

`constants`	Shared constants and enums for config field management.
`inheritance_aware_field_generator`	Inheritance-Aware Field Generator
`step_catalog_aware_categorizer`	Step Catalog Aware Config Field Categorizer.
`type_aware_config_serializer`	Optimized Type-aware serializer for configuration objects.
`unified_config_manager`	Unified Config Manager - Single integrated component replacing redundant data structures.