cursus.step_catalog.adapters

Step catalog adapters package.

This package provides backward compatibility adapters that maintain existing APIs during the migration from legacy discovery systems to the unified StepCatalog system.

The adapters are organized by functionality: - contract_discovery: Contract discovery and management adapters - file_resolver: File resolution and discovery adapters - workspace_discovery: Workspace discovery and management adapters - config_resolver: Configuration resolution adapters - config_class_detector: Configuration class detection adapters

class ContractDiscoveryResult(contract=None, contract_name=None, discovery_method='step_catalog', error_message=None)

Bases: object

Legacy result class for contract discovery operations.

Maintains backward compatibility with existing tests and code.

class ContractDiscoveryEngineAdapter(workspace_root)

Bases: object

Modernized adapter using unified StepCatalog for all discovery operations.

Replaces: src/cursus/validation/alignment/discovery/contract_discovery.py All methods now use the step catalog’s built-in discovery capabilities.

build_entry_point_mapping()

MODERNIZED: Build entry point mapping from step names to script paths.

Used by tests and legacy systems that expect entry point mappings.

Returns:

Dictionary mapping step names to script file paths

Return type:

Dict[str, str]

discover_all_contracts()

MODERNIZED: Discover all steps that have contracts using step catalog.

Used by alignment validation system.

discover_contracts_with_scripts()

MODERNIZED: Use step catalog’s built-in method.

Historically the primary contract-discovery entry for the Level-2 alignment tester (now removed — contract<->spec alignment is a construction-time invariant; FZ 31e1d3h/D5); the method stays as a general script-backed-contract discovery helper.

extract_contract_reference_from_spec(spec_file)

MODERNIZED: Extract contract reference from spec file using step catalog.

Used by alignment validation system to find which step corresponds to a spec file.

Parameters:

spec_file (str) – Name of the spec file (e.g., “xgboost_training_spec.py”)

Returns:

Step name if found, None otherwise

Return type:

str | None

class ContractDiscoveryManagerAdapter(test_data_dir=None, workspace_root=None)

Bases: object

Modernized adapter using unified StepCatalog with minimal business logic.

Replaces: src/cursus/validation/script_testing (formerly runtime/contract_discovery.py) Focuses on test-specific functionality while leveraging step catalog for discovery.

discover_contract(step_name, canonical_name=None)

MODERNIZED: Use StepCatalog’s load_contract_class for discovery.

Parameters:

• step_name (str) – Name of the step/script

• canonical_name (str | None) – Optional canonical name for the step

Returns:

String path for backward compatibility, or None if not found

Return type:

str | None

get_contract_environ_vars(contract)

Get environment variables from contract.

get_contract_input_paths(contract, step_name)

Get contract input paths with local adaptation.

get_contract_job_args(contract, step_name)

Get job arguments from contract.

get_contract_output_paths(contract, step_name)

Get contract output paths with local adaptation.

class FlexibleFileResolverAdapter(workspace_root)

Bases: object

Modernized file resolver using unified step catalog system.

Replaces: src/cursus/validation/alignment/file_resolver.py

This adapter leverages the step catalog’s superior discovery capabilities while maintaining backward compatibility with legacy FlexibleFileResolver APIs.

extract_base_name_from_spec(spec_path)

Extract base name from spec path.

find_all_component_files(step_name)

Legacy method: find all component files for step.

find_builder_file(step_name)

Legacy method: find builder file for step.

find_config_file(step_name)

Legacy method: find config file for step.

find_contract_file(step_name)

Legacy method: find contract file for step.

find_spec_constant_name(script_name, job_type='training')

Find spec constant name using catalog.

find_spec_file(step_name)

Legacy method: find spec file for step.

find_specification_file(script_name)

Legacy alias for find_spec_file.

get_available_files_report()

Generate report using catalog data.

refresh_cache()

Legacy method: refresh cache using catalog.

class DeveloperWorkspaceFileResolverAdapter(workspace_root=None, project_id=None, developer_id=None, enable_shared_fallback=True, **kwargs)

Bases: FlexibleFileResolverAdapter

Adapter maintaining backward compatibility with DeveloperWorkspaceFileResolver.

Replaces: src/cursus/workspace/validation/workspace_file_resolver.py

find_builder_file(step_name)

Workspace-aware builder file discovery. Returns string path like legacy method.

find_config_file(step_name)

Workspace-aware config file discovery. Returns string path like legacy method.

find_contract_file(step_name)

Workspace-aware contract file discovery. Returns string path like legacy method.

find_script_file(step_name, script_name=None)

Workspace-aware script file discovery. Returns string path like legacy method.

find_spec_file(step_name)

Workspace-aware spec file discovery. Returns string path like legacy method.

get_workspace_info()

Get workspace information using step catalog.

list_available_developers()

List available developers using workspace discovery.

switch_developer(developer_id)

Switch to a different developer workspace.

class HybridFileResolverAdapter(workspace_root)

Bases: object

Adapter maintaining backward compatibility with HybridFileResolver.

Replaces: src/cursus/validation/alignment/patterns/file_resolver.py

resolve_file_pattern(pattern, component_type)

Legacy method: resolve files matching pattern.

class WorkspaceDiscoveryManagerAdapter(workspace_root)

Bases: object

Adapter maintaining backward compatibility with WorkspaceDiscoveryManager.

Replaces: src/cursus/workspace/core/discovery.py

discover_components(workspace_ids=None, developer_id=None)

Enhanced method: discover ALL component types with workspace-specific functionality.

When workspace_ids is None: focuses on shared package (cursus/steps - “core” workspace) When workspace_ids specified: discovers from those specific workspaces

Returns comprehensive inventory of all 5 component types: - builders, configs, contracts, specs, scripts

discover_workspaces(workspace_root)

Legacy method: discover available workspaces with simplified structure.

get_discovery_summary()

Legacy method: get discovery summary.

get_file_resolver(developer_id=None, **kwargs)

Legacy method: get file resolver.

get_module_loader(developer_id=None, **kwargs)

Legacy method: get module loader.

get_statistics()

Legacy method: get statistics.

get_workspace_info(workspace_id=None, developer_id=None)

Legacy method: get workspace info with simplified structure.

list_available_developers()

Legacy method: list available developers with simplified structure.

refresh_cache()

Legacy method: refresh cache.

class StepConfigResolverAdapter(workspace_root=None, confidence_threshold=0.7)

Bases: object

Enhanced adapter maintaining backward compatibility with StepConfigResolver.

Replaces: src/cursus/core/compiler/config_resolver.py

This enhanced version includes essential legacy methods needed for production while leveraging the unified step catalog for superior discovery capabilities.

JOB_TYPE_KEYWORDS = {'calibration': ['calibration', 'calib'], 'evaluation': ['evaluation', 'eval', 'test'], 'inference': ['inference', 'infer', 'predict'], 'training': ['training', 'train']}

STEP_TYPE_PATTERNS = {'.*calibrat.*': ['ModelCalibration'], '.*currency.*': ['CurrencyConversion'], '.*data_load.*': ['CradleDataLoading'], '.*eval.*': ['XGBoostModelEval'], '.*hyperparam.*': ['HyperparameterPrep'], '.*model.*': ['XGBoostModel', 'PyTorchModel'], '.*packag.*': ['MIMSPackaging'], '.*payload.*': ['MIMSPayload'], '.*preprocess.*': ['TabularPreprocessing'], '.*regist.*': ['ModelRegistration'], '.*risk.*': ['RiskTableMapping'], '.*train.*': ['XGBoostTraining', 'PyTorchTraining', 'DummyTraining'], '.*transform.*': ['BatchTransform']}

preview_resolution(dag_nodes, available_configs, metadata=None)

Enhanced preview resolution with metadata support.

resolve_config_for_step(step_name, configs)

Resolve configuration for a single step (used by generator.py).

Parameters:

• step_name (str) – Name of the step

• configs (Dict[str, Any]) – Available configurations

Returns:

Resolved configuration or None

Return type:

Any | None

resolve_config_map(dag_nodes, available_configs, metadata=None)

Resolve every DAG node to a config, or RAISE listing every node that cannot be resolved.

This is the compile-path entry point. It delegates each node to _resolve_single_node() — the same safe matcher resolve_config_for_step / preview_resolution use — which raises ResolutionError on a no-match and warns below the confidence threshold. Previously this method had its own weaker 3-tier loop whose tier-3 “first available config” silently bound any unmatched node to next(iter(available_configs.values())) — compiling a structurally WRONG pipeline from an incomplete config (deep dive 2026-07-03). The fix unifies the two entry points on _resolve_single_node and turns “can’t resolve” into a loud failure that names EVERY unsatisfiable node, never a plausible-but-wrong binding.

class ConfigClassDetectorAdapter(workspace_root=None)

Bases: object

Adapter maintaining backward compatibility with ConfigClassDetector.

Replaces: src/cursus/core/config_fields/config_class_detector.py

MODERN APPROACH: Uses step catalog’s superior AST-based config discovery instead of legacy JSON parsing. This provides more accurate and comprehensive config class detection.

CONFIGURATION_FIELD = 'configuration'

CONFIG_TYPES_FIELD = 'config_types'

METADATA_FIELD = 'metadata'

MODEL_TYPE_FIELD = '__model_type__'

SPECIFIC_FIELD = 'specific'

static detect_from_json(config_path)

MODERN APPROACH: Use step catalog’s AST-based discovery instead of JSON parsing.

This method now uses the superior AST-based discovery from the unified step catalog rather than the legacy JSON parsing approach. This provides more accurate and comprehensive config class detection by analyzing actual source code.

Real usage pattern (from dynamic_template.py): detected_classes = detect_config_classes_from_json(self.config_path)

Parameters:

config_path (str) – Path to configuration file (used to determine workspace root)

Returns:

Dictionary mapping config class names to config class types

Return type:

Dict[str, Any]

classmethod from_config_store(config_path)

MODERN APPROACH: Use step catalog’s integrated discovery.

This method uses the step catalog’s build_complete_config_classes which integrates both AST-based discovery and ConfigClassStore registration, providing the most comprehensive config class detection.

class ConfigClassStoreAdapter

Bases: object

Adapter maintaining backward compatibility with ConfigClassStore.

Replaces: src/cursus/core/config_fields/config_class_store.py (partial)

classmethod clear()

Legacy method: clear the registry.

classmethod get_all_classes()

Legacy method: get all registered classes.

classmethod get_class(class_name)

Legacy method: get a registered class by name.

classmethod register(config_class=None)

Legacy method: register a config class.

classmethod register_many(*config_classes)

Legacy method: register multiple config classes at once.

classmethod registered_names()

Legacy method: get all registered class names.

class LegacyDiscoveryWrapper(workspace_root)

Bases: object

Wrapper providing legacy discovery interfaces during migration period.

This class provides a unified interface that can be used as a drop-in replacement for legacy discovery systems during the migration phase. It delegates all StepCatalog methods to the underlying catalog while also providing access to legacy adapters.

build_complete_config_classes(project_id=None)

Delegate to underlying StepCatalog.

detect_framework(step_name)

Delegate to underlying StepCatalog.

discover_config_classes(project_id=None)

Delegate to underlying StepCatalog.

discover_contracts_with_scripts()

Delegate to underlying StepCatalog.

discover_cross_workspace_components(workspace_ids=None)

Delegate to underlying StepCatalog.

extract_base_name_from_spec(spec_path)

Extract base name from spec path.

find_all_component_files(step_name)

Legacy method: find all component files for step.

find_builder_file(step_name)

Legacy method: find builder file for step.

find_config_file(step_name)

Legacy method: find config file for step.

find_contract_file(step_name)

Legacy method: find contract file for step.

find_spec_constant_name(script_name, job_type='training')

Find spec constant name using catalog.

find_spec_file(step_name)

Legacy method: find spec file for step.

find_specification_file(script_name)

Legacy alias for find_spec_file.

find_step_by_component(component_path)

Delegate to underlying StepCatalog.

get_adapter(adapter_type)

Get specific legacy adapter by type.

get_available_files_report()

Generate report using catalog data.

get_builder_class_path(step_name)

Delegate to underlying StepCatalog.

get_job_type_variants(step_name)

Delegate to underlying StepCatalog.

get_metrics_report()

Delegate to underlying StepCatalog.

get_step_info(step_name, job_type=None)

Delegate to underlying StepCatalog.

get_unified_catalog()

Get the underlying unified catalog.

list_available_steps(workspace_id=None, job_type=None)

Delegate to underlying StepCatalog.

load_builder_class(step_name)

Delegate to underlying StepCatalog.

refresh_cache()

Legacy method: refresh cache using catalog.

search_steps(query, job_type=None)

Delegate to underlying StepCatalog.

build_complete_config_classes(project_id=None)

Legacy function: build complete config classes using catalog.

detect_config_classes_from_json(config_path)

Legacy function: detect config classes using catalog.

Modules

config_class_detector	Config class detector adapters for backward compatibility.
config_resolver	Config resolver adapters for backward compatibility.
contract_adapter	Modernized contract discovery adapters using unified StepCatalog system.
file_resolver	File resolver adapters for backward compatibility.
legacy_wrappers	Legacy wrapper adapters for backward compatibility.
workspace_discovery	Workspace discovery adapters for backward compatibility.