cursus.core.base

Core base classes for the cursus framework.

This module provides the foundational base classes that are used throughout the cursus framework for configuration, contracts, specifications, and builders.

class DependencyType(*values)

Bases: Enum

Types of dependencies in the pipeline.

MODEL_ARTIFACTS = 'model_artifacts'

PROCESSING_OUTPUT = 'processing_output'

TRAINING_DATA = 'training_data'

HYPERPARAMETERS = 'hyperparameters'

PAYLOAD_SAMPLES = 'payload_samples'

CUSTOM_PROPERTY = 'custom_property'

class NodeType(*values)

Bases: Enum

Types of nodes in the pipeline based on their dependency/output characteristics.

SOURCE = 'source'

INTERNAL = 'internal'

SINK = 'sink'

SINGULAR = 'singular'

class ValidationResult(*, is_valid, errors=<factory>, warnings=<factory>)

Bases: BaseModel

Result of script contract validation

add_error(error)

Add an error to the result and mark as invalid

add_warning(warning)

Add a warning to the result

classmethod combine(results)

Combine multiple validation results

classmethod error(errors)

Create a failed validation result

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod success(message='Validation passed')

Create a successful validation result

is_valid: bool

errors: List[str]

warnings: List[str]

class ScriptAnalyzer(script_path)

Bases: object

Analyzes Python scripts to extract I/O patterns and environment variable usage

property ast_tree: Any

Lazy load and parse the script AST

get_argument_usage()

Extract command-line arguments used by the script

get_env_var_usage()

Extract environment variables accessed by the script

get_input_paths()

Extract input paths used by the script

get_output_paths()

Extract output paths used by the script

class StepInterface(*, step_type, node_type=NodeType.INTERNAL, registry=<factory>, compute=<factory>, patterns=<factory>, contract, spec=<factory>, variants=<factory>)

Bases: BaseModel

Validated representation of a .step.yaml file.

This is the single message passed among dep resolver, builder, and assembler. Replaces the previous (ScriptContract|StepContract, StepSpecification) tuple.

Build it from a parsed YAML dict via from_yaml(), which applies any requested job_type variant before validation.

classmethod coerce_node_type(v)

property dependencies: Dict[str, DependencyDecl]

property description: str

property entry_point: str | None

property expected_arguments: Dict[str, str]

property expected_input_paths: Dict[str, str]

property expected_output_paths: Dict[str, str]

property framework_requirements: Dict[str, str]

classmethod from_yaml(data, job_type=None)

Build a StepInterface from a parsed .step.yaml dict, resolving variants.

When job_type names a variant, that variant’s spec/contract overrides are deep-merged over the base sections before validation. The merge is recursive: a variant that lists only a subset of spec.dependencies (or outputs / contract inputs) overrides just those ports’ fields and leaves the rest of the base set intact — it does not replace the whole nested dict. Steps without a matching variant fall back to the base sections unchanged.

A shallow merge here was a latent bug: because variants routinely restate only the ports they tweak, {**base, **variant} at the section level dropped every base port the variant happened to omit (e.g. it dropped hyperparameters_s3_uri from RiskTableMapping’s variants, which then violated the contract↔spec alignment invariant and raised at construction).

get_dependency(logical_name)

get_output(logical_name)

get_output_by_name_or_alias(name)

list_all_output_names()

list_optional_dependencies()

list_required_dependencies()

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property optional_env_vars: Dict[str, str]

property outputs: Dict[str, OutputDecl]

property required_env_vars: List[str]

property script_contract: ContractSection

Legacy StepSpecification.script_contract accessor.

validate_contract_alignment()

Validate that the contract aligns with the spec.

Mirrors legacy StepSpecification.validate_contract_alignment: every contract input must have a matching spec dependency, and every contract output a matching spec output (extra spec deps/outputs and output aliases allowed). Returns a ValidationResult (is_valid / errors).

validate_specification()

step_type: str

node_type: NodeType

registry: RegistrySection

compute: ComputeSpec

Declarative COMPUTE descriptor (FZ 31e1d3k) — a TOP-LEVEL section (peer of contract/spec) because it describes the BUILDER’s compute object (processor/estimator/model/transformer), not the script contract: script-less steps (CreateModel/Transform) carry a near-empty contract but a full compute. _sync_and_align mirrors it onto contract.compute for back-compat. Empty (kind=None) ⇒ the step keeps its own factory.

patterns: PatternsSection

Per-axis STRATEGY-SELECTION knobs (FZ 31e1d3f1) — the blueprint that wires pattern injection (step_assembly / include_job_type_in_path / direct_input_keys), read into the bound handler by _auto_bind_handler so the YAML steers the build, not a builder shell.

contract: ContractSection

spec: SpecSection

variants: Dict[str, VariantDecl]

class ModelHyperparameters(*, full_field_list, cat_field_list, tab_field_list, id_name, label_name, multiclass_categories, categorical_features_to_encode=<factory>, model_class='base_model', device=-1, header=0, lr=3e-05, batch_size=2, eval_batch_size_multiplier=2.0, max_epochs=3, metric_choices=['f1_score', 'auroc'], optimizer='SGD', class_weights=None, **extra_data)

Bases: BaseModel

Base model hyperparameters for training tasks.

Fields are organized into three tiers: 1. Tier 1: Essential User Inputs - fields that users must explicitly provide 2. Tier 2: System Inputs with Defaults - fields with reasonable defaults that can be overridden 3. Tier 3: Derived Fields - fields calculated from other fields (private attributes with properties)

categorize_fields()

Categorize all fields into three tiers: 1. Tier 1: Essential User Inputs - fields with no defaults (required) 2. Tier 2: System Inputs - fields with defaults (optional) 3. Tier 3: Derived Fields - properties that access private attributes

Returns:

Dict with keys ‘essential’, ‘system’, and ‘derived’ mapping to lists of field names

Return type:

Dict[str, List[str]]

classmethod from_base_hyperparam(base_hyperparam, **kwargs)

Create a new hyperparameter instance from a base hyperparameter. This is a virtual method that all derived classes can use to inherit from a parent config.

Parameters:

• base_hyperparam (ModelHyperparameters) – Parent ModelHyperparameters instance

• **kwargs (Any) – Additional arguments specific to the derived class

Returns:

A new instance of the derived class initialized with parent fields and additional kwargs

Return type:

ModelHyperparameters

get_config()

Get the complete configuration dictionary.

get_public_init_fields()

Get a dictionary of public fields suitable for initializing a child hyperparameter. Only includes fields that should be passed to child class constructors. Both essential user inputs and system inputs with defaults or user-overridden values are included to ensure all user customizations are properly propagated.

Returns:

Dictionary of field names to values for child initialization

Return type:

Dict[str, Any]

property input_tab_dim: int

Get input tabular dimension derived from tab_field_list.

property is_binary: bool

Determine if this is a binary classification task based on num_classes.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'protected_namespaces': (), 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

• self (BaseModel) – The BaseModel instance.

• context (Any) – The context.

property num_classes: int

Get number of classes derived from multiclass_categories.

print_hyperparam()

Print complete hyperparameter information organized by tiers. This method automatically categorizes fields by examining their characteristics.

serialize_config()

Serialize configuration for SageMaker.

validate_dimensions()

Validate model dimensions and configurations

full_field_list: List[str]

cat_field_list: List[str]

tab_field_list: List[str]

id_name: str

label_name: str

multiclass_categories: List[str | int]

categorical_features_to_encode: List[str]

model_class: str

device: int

header: int

lr: float

batch_size: int

eval_batch_size_multiplier: float

max_epochs: int

metric_choices: List[str]

optimizer: str

class_weights: List[float] | None

get_base_pipeline_config()

Lazy import for BasePipelineConfig to avoid circular imports.

get_step_builder_base()

Lazy import for StepBuilderBase to avoid circular imports.

Modules

builder_base
builder_templates	Template-based step builder + construction-verb handlers (Phase 0c of the simplification).
config_base	Base Pipeline Configuration with Self-Contained Derivation Logic
contract_base	Base Script Validation Classes
enums	Shared enums for the cursus core base classes.
hyperparameters_base
step_contract	StepContract — immutable data loaded from .step.yaml.
step_interface	StepInterface — the single Pydantic-validated data structure for a .step.yaml.