@aws/ml-container-creator 1.0.3 → 1.1.0

package/src/lib/schema-validator.js

@@ -1,157 +0,0 @@
-/**
- * Schema Validator
- * 
- * Validates registry data against JSON schemas without external dependencies.
- * Uses a simple validation approach suitable for the registry structure.
- */
-
-export default class SchemaValidator {
-    /**
-     * Validate data against a schema
-     * @param {Object} data - Data to validate
-     * @param {Object} schema - JSON schema
-     * @returns {Object} - { valid: boolean, errors: string[] }
-     */
-    validate(data, schema) {
-        const errors = [];
-        
-        try {
-            this._validateType(data, schema, '', errors);
-        } catch (error) {
-            errors.push(`Validation error: ${error.message}`);
-        }
-        
-        return {
-            valid: errors.length === 0,
-            errors
-        };
-    }
-    
-    _validateType(data, schema, path, errors) {
-        // Handle type validation
-        if (schema.type) {
-            const types = Array.isArray(schema.type) ? schema.type : [schema.type];
-            const dataType = this._getType(data);
-            
-            if (!types.includes(dataType)) {
-                errors.push(`${path || 'root'}: Expected type ${types.join(' or ')}, got ${dataType}`);
-                return;
-            }
-        }
-        
-        // Handle enum validation
-        if (schema.enum && !schema.enum.includes(data)) {
-            errors.push(`${path || 'root'}: Value must be one of ${schema.enum.join(', ')}`);
-            return;
-        }
-        
-        // Handle object validation
-        if (this._getType(data) === 'object' && schema.type === 'object') {
-            this._validateObject(data, schema, path, errors);
-        }
-        
-        // Handle array validation
-        if (this._getType(data) === 'array' && schema.type === 'array') {
-            this._validateArray(data, schema, path, errors);
-        }
-        
-        // Handle string validation
-        if (this._getType(data) === 'string' && schema.type === 'string') {
-            this._validateString(data, schema, path, errors);
-        }
-        
-        // Handle number validation
-        if (this._getType(data) === 'number' && schema.type === 'number') {
-            this._validateNumber(data, schema, path, errors);
-        }
-    }
-    
-    _validateObject(data, schema, path, errors) {
-        // Check required properties
-        if (schema.required) {
-            for (const requiredProp of schema.required) {
-                if (!(requiredProp in data)) {
-                    errors.push(`${path || 'root'}: Missing required property '${requiredProp}'`);
-                }
-            }
-        }
-        
-        // Validate properties
-        if (schema.properties) {
-            for (const [key, value] of Object.entries(data)) {
-                if (schema.properties[key]) {
-                    this._validateType(value, schema.properties[key], `${path}.${key}`, errors);
-                }
-            }
-        }
-        
-        // Validate patternProperties
-        if (schema.patternProperties) {
-            for (const [key, value] of Object.entries(data)) {
-                for (const [pattern, propSchema] of Object.entries(schema.patternProperties)) {
-                    const regex = new RegExp(pattern);
-                    if (regex.test(key)) {
-                        this._validateType(value, propSchema, `${path}.${key}`, errors);
-                    }
-                }
-            }
-        }
-    }
-    
-    _validateArray(data, schema, path, errors) {
-        // Check minItems
-        if (schema.minItems !== undefined && data.length < schema.minItems) {
-            errors.push(`${path || 'root'}: Array must have at least ${schema.minItems} items`);
-        }
-        
-        // Check maxItems
-        if (schema.maxItems !== undefined && data.length > schema.maxItems) {
-            errors.push(`${path || 'root'}: Array must have at most ${schema.maxItems} items`);
-        }
-        
-        // Validate items
-        if (schema.items) {
-            data.forEach((item, index) => {
-                this._validateType(item, schema.items, `${path}[${index}]`, errors);
-            });
-        }
-    }
-    
-    _validateString(data, schema, path, errors) {
-        // Check minLength
-        if (schema.minLength !== undefined && data.length < schema.minLength) {
-            errors.push(`${path || 'root'}: String must be at least ${schema.minLength} characters`);
-        }
-        
-        // Check maxLength
-        if (schema.maxLength !== undefined && data.length > schema.maxLength) {
-            errors.push(`${path || 'root'}: String must be at most ${schema.maxLength} characters`);
-        }
-        
-        // Check pattern
-        if (schema.pattern) {
-            const regex = new RegExp(schema.pattern);
-            if (!regex.test(data)) {
-                errors.push(`${path || 'root'}: String does not match pattern ${schema.pattern}`);
-            }
-        }
-    }
-    
-    _validateNumber(data, schema, path, errors) {
-        // Check minimum
-        if (schema.minimum !== undefined && data < schema.minimum) {
-            errors.push(`${path || 'root'}: Number must be at least ${schema.minimum}`);
-        }
-        
-        // Check maximum
-        if (schema.maximum !== undefined && data > schema.maximum) {
-            errors.push(`${path || 'root'}: Number must be at most ${schema.maximum}`);
-        }
-    }
-    
-    _getType(value) {
-        if (value === null) return 'null';
-        if (Array.isArray(value)) return 'array';
-        return typeof value;
-    }
-}

package/src/lib/train-config-parser.js

@@ -1,136 +0,0 @@
-// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * Train Config Parser
- *
- * JavaScript module that replicates the YAML config parsing logic from
- * do/train's _parse_config_python() function. Parses do/training/config.yaml
- * and extracts all supported fields into a structured object.
- *
- * This module mirrors the behavior of both the yq and Python fallback paths
- * in the bash script, providing a testable implementation of the parsing logic.
- */
-
-import { readFileSync } from 'node:fs';
-import yaml from 'js-yaml';
-
-/**
- * Default values for optional fields, matching the bash script defaults.
- */
-const DEFAULTS = {
-    instance_count: '1',
-    max_runtime_seconds: '86400',
-    volume_size_gb: '50',
-    enable_spot: 'false',
-    max_wait_seconds: '172800',
-    checkpoint_path: '',
-    hyperparameters: {},
-    metric_definitions: [],
-    environment: {},
-    tags: {}
-};
-
-/**
- * Convert a value to its string representation, matching the Python helper's
- * `s()` function behavior in _parse_config_python.
- *
- * @param {*} val - The value to convert
- * @param {string} defaultVal - Default value if val is null/undefined
- * @returns {string} String representation
- */
-function toStringValue(val, defaultVal = '') {
-    if (val === null || val === undefined) {
-        return defaultVal;
-    }
-    if (typeof val === 'boolean') {
-        return val ? 'true' : 'false';
-    }
-    return String(val);
-}
-
-/**
- * Parse a training config YAML file and extract all supported fields.
- *
- * This mirrors the behavior of _parse_config_python() in do/train:
- * - Scalar fields are converted to strings
- * - Boolean fields are converted to "true"/"false" strings
- * - Missing optional fields get default values
- * - Complex fields (hyperparameters, metric_definitions, environment, tags)
- *   are kept as their native types (objects/arrays)
- *
- * @param {string} configPath - Path to the YAML config file
- * @returns {object} Parsed config with all supported fields
- * @throws {Error} If the file cannot be read or parsed
- */
-export function parseTrainingConfig(configPath) {
-    const content = readFileSync(configPath, 'utf8');
-    return parseTrainingConfigFromString(content);
-}
-
-/**
- * Parse a training config from a YAML string.
- * Useful for testing without file I/O.
- *
- * @param {string} yamlContent - YAML content string
- * @returns {object} Parsed config with all supported fields
- * @throws {Error} If the YAML cannot be parsed
- */
-export function parseTrainingConfigFromString(yamlContent) {
-    const cfg = yaml.load(yamlContent) || {};
-
-    return {
-        // Required fields (empty string if missing)
-        image: toStringValue(cfg.image, ''),
-        script: toStringValue(cfg.script, ''),
-        instance_type: toStringValue(cfg.instance_type, ''),
-        instance_count: toStringValue(cfg.instance_count, DEFAULTS.instance_count),
-        dataset: toStringValue(cfg.dataset, ''),
-        output_path: toStringValue(cfg.output_path, ''),
-
-        // Optional scalar fields with defaults
-        max_runtime_seconds: toStringValue(cfg.max_runtime_seconds, DEFAULTS.max_runtime_seconds),
-        volume_size_gb: toStringValue(cfg.volume_size_gb, DEFAULTS.volume_size_gb),
-        enable_spot: toStringValue(cfg.enable_spot, DEFAULTS.enable_spot),
-        max_wait_seconds: toStringValue(cfg.max_wait_seconds, DEFAULTS.max_wait_seconds),
-        checkpoint_path: toStringValue(cfg.checkpoint_path, DEFAULTS.checkpoint_path),
-
-        // Complex fields (objects/arrays)
-        hyperparameters: cfg.hyperparameters || DEFAULTS.hyperparameters,
-        metric_definitions: cfg.metric_definitions || DEFAULTS.metric_definitions,
-        environment: cfg.environment || DEFAULTS.environment,
-        tags: cfg.tags || DEFAULTS.tags
-    };
-}
-
-/**
- * List of all supported fields in the training config.
- */
-export const SUPPORTED_FIELDS = [
-    'image',
-    'script',
-    'instance_type',
-    'instance_count',
-    'dataset',
-    'output_path',
-    'max_runtime_seconds',
-    'volume_size_gb',
-    'enable_spot',
-    'max_wait_seconds',
-    'checkpoint_path',
-    'hyperparameters',
-    'metric_definitions',
-    'environment',
-    'tags'
-];
-
-/**
- * List of required fields that must be non-empty.
- */
-export const REQUIRED_FIELDS = [
-    'image',
-    'script',
-    'instance_type',
-    'dataset',
-    'output_path'
-];

package/src/lib/train-config-persistence.js

@@ -1,143 +0,0 @@
-// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * Train Config Persistence
- *
- * JavaScript module that models the config persistence logic from the bash
- * `_update_config_var` function in `templates/do/train`. This module provides
- * a pure JavaScript implementation for property-based testing of the config
- * persistence behavior after job submission and completion.
- *
- * The config file uses the format:
- *   export VAR_NAME="value"
- *
- * Behavior:
- * - If the variable already exists: update its value in-place
- * - If the variable doesn't exist: append it to the end
- * - Existing variables in the config are preserved
- *
- * Requirements: 3.4, 5.1
- */
-
-import { readFileSync, writeFileSync } from 'node:fs';
-
-/**
- * Update or add a config variable in a do/config-style file.
- * Mimics the bash _update_config_var() function from templates/do/train:
- *
- *   if grep -q "^export ${var_name}=" "${config_file}"; then
- *       sed -i.bak "s|^export ${var_name}=.*|export ${var_name}=\"${var_value}\"|" "${config_file}"
- *       rm -f "${config_file}.bak"
- *   else
- *       echo "export ${var_name}=\"${var_value}\"" >> "${config_file}"
- *   fi
- *
- * @param {string} configContent - Current content of the config file
- * @param {string} varName - Variable name (e.g., TRAIN_JOB_NAME)
- * @param {string} varValue - Variable value
- * @returns {string} Updated config content
- */
-export function updateConfigVar(configContent, varName, varValue) {
-    const pattern = new RegExp(`^export ${varName}=.*$`, 'm');
-
-    if (pattern.test(configContent)) {
-        // Variable exists — update in-place
-        return configContent.replace(pattern, `export ${varName}="${varValue}"`);
-    } else {
-        // Variable doesn't exist — append
-        let result = configContent;
-        if (result.length > 0 && !result.endsWith('\n')) {
-            result += '\n';
-        }
-        result += `export ${varName}="${varValue}"\n`;
-        return result;
-    }
-}
-
-/**
- * Read a config variable value from a do/config-style file content.
- *
- * @param {string} configContent - Content of the config file
- * @param {string} varName - Variable name to read
- * @returns {string|null} The variable value, or null if not found
- */
-export function readConfigVar(configContent, varName) {
-    const pattern = new RegExp(`^export ${varName}="([^"]*)"`, 'm');
-    const match = configContent.match(pattern);
-    return match ? match[1] : null;
-}
-
-/**
- * Simulate the config writes that happen after a successful training job submission.
- * This mirrors the behavior in do/train's _submit_job() function which calls:
- *   _update_config_var "TRAIN_JOB_NAME" "${JOB_NAME}"
- *
- * @param {string} configContent - Current content of the config file
- * @param {object} params - Submission parameters
- * @param {string} params.jobName - Generated job name (pattern: ${PROJECT_NAME}-train-${TIMESTAMP})
- * @returns {string} Updated config content
- */
-export function persistTrainSubmission(configContent, { jobName }) {
-    return updateConfigVar(configContent, 'TRAIN_JOB_NAME', jobName);
-}
-
-/**
- * Simulate the config writes that happen after a training job completes.
- * This mirrors the behavior in do/train's _handle_completion() function which calls:
- *   _update_config_var "TRAIN_OUTPUT_PATH" "${output_path}"
- *
- * @param {string} configContent - Current content of the config file
- * @param {object} params - Completion parameters
- * @param {string} params.outputPath - S3 path to the output artifacts
- * @returns {string} Updated config content
- */
-export function persistTrainCompletion(configContent, { outputPath }) {
-    return updateConfigVar(configContent, 'TRAIN_OUTPUT_PATH', outputPath);
-}
-
-/**
- * Generate a training job name following the pattern used by do/train.
- * Pattern: ${projectName}-train-YYYYMMDD-HHMMSS
- *
- * @param {string} projectName - Project name
- * @param {Date} [timestamp] - Optional timestamp (defaults to now)
- * @returns {string} Generated job name
- */
-export function generateTrainJobName(projectName, timestamp = new Date()) {
-    const year = timestamp.getFullYear().toString();
-    const month = (timestamp.getMonth() + 1).toString().padStart(2, '0');
-    const day = timestamp.getDate().toString().padStart(2, '0');
-    const hours = timestamp.getHours().toString().padStart(2, '0');
-    const minutes = timestamp.getMinutes().toString().padStart(2, '0');
-    const seconds = timestamp.getSeconds().toString().padStart(2, '0');
-    const dateStr = `${year}${month}${day}`;
-    const timeStr = `${hours}${minutes}${seconds}`;
-    return `${projectName}-train-${dateStr}-${timeStr}`;
-}
-
-/**
- * File-based version of updateConfigVar that reads/writes to disk.
- * Used for integration-style tests that need actual file I/O.
- *
- * @param {string} configPath - Path to the config file
- * @param {string} varName - Variable name
- * @param {string} varValue - Variable value
- */
-export function updateConfigVarFile(configPath, varName, varValue) {
-    const content = readFileSync(configPath, 'utf8');
-    const updated = updateConfigVar(content, varName, varValue);
-    writeFileSync(configPath, updated, 'utf8');
-}
-
-/**
- * File-based version of readConfigVar that reads from disk.
- *
- * @param {string} configPath - Path to the config file
- * @param {string} varName - Variable name to read
- * @returns {string|null} The variable value, or null if not found
- */
-export function readConfigVarFile(configPath, varName) {
-    const content = readFileSync(configPath, 'utf8');
-    return readConfigVar(content, varName);
-}

package/src/lib/train-config-validator.js

@@ -1,112 +0,0 @@
-// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * Train Config Validator
- *
- * Validates training configuration objects parsed from do/training/config.yaml.
- * Checks that all required fields are present and provides descriptive error
- * messages naming the specific missing field.
- *
- * This module mirrors the validation logic in the bash `_validate_config`
- * function in templates/do/train, enabling property-based testing of the
- * validation rules in isolation.
- *
- * Requirements: 2.12, 10.1
- */
-
-/**
- * Required fields for a valid training configuration.
- * Each entry maps the field name to a human-readable description and expected format.
- */
-export const REQUIRED_FIELDS = {
-    image: {
-        description: 'The container image URI',
-        format: 'image: "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-training:latest"'
-    },
-    script: {
-        description: 'The training script S3 path',
-        format: 'script: "s3://my-bucket/scripts/train.py"'
-    },
-    instance_type: {
-        description: 'The SageMaker instance type',
-        format: 'instance_type: "ml.g5.xlarge"'
-    },
-    dataset: {
-        description: 'The S3 dataset path',
-        format: 'dataset: "s3://my-bucket/data/train/"'
-    },
-    output_path: {
-        description: 'The S3 output path',
-        format: 'output_path: "s3://my-bucket/output/"'
-    }
-};
-
-/**
- * Validate that all required fields are present in a training config.
- *
- * @param {Object} config - The parsed training configuration object
- * @returns {{ valid: boolean, errors: Array<{ field: string, message: string }> }}
- *   - valid: true if all required fields are present and non-empty
- *   - errors: array of error objects, each naming the missing field
- */
-export function validateRequiredFields(config) {
-    const errors = [];
-
-    for (const [field, meta] of Object.entries(REQUIRED_FIELDS)) {
-        const value = config ? config[field] : undefined;
-
-        if (value === undefined || value === null || value === '') {
-            errors.push({
-                field,
-                message: `Missing required field: ${field}\n   ${meta.description} is required in do/training/config.yaml\n\n   Expected format: ${meta.format}`
-            });
-        }
-    }
-
-    return {
-        valid: errors.length === 0,
-        errors
-    };
-}
-
-/**
- * Validate spot training checkpoint requirement.
- * When enable_spot is true, checkpoint_path must be specified.
- *
- * @param {Object} config - The parsed training configuration object
- * @returns {{ valid: boolean, errors: Array<{ field: string, message: string }> }}
- */
-export function validateSpotConfig(config) {
-    const errors = [];
-
-    if (config && config.enable_spot === true && (!config.checkpoint_path || config.checkpoint_path === '')) {
-        errors.push({
-            field: 'checkpoint_path',
-            message: 'Checkpoint path required for spot training\n   When enable_spot is true, a checkpoint S3 path must be specified\n   so training can resume after spot interruptions.'
-        });
-    }
-
-    return {
-        valid: errors.length === 0,
-        errors
-    };
-}
-
-/**
- * Full validation of a training config — checks required fields and spot config.
- *
- * @param {Object} config - The parsed training configuration object
- * @returns {{ valid: boolean, errors: Array<{ field: string, message: string }> }}
- */
-export function validateTrainingConfig(config) {
-    const requiredResult = validateRequiredFields(config);
-    const spotResult = validateSpotConfig(config);
-
-    const allErrors = [...requiredResult.errors, ...spotResult.errors];
-
-    return {
-        valid: allErrors.length === 0,
-        errors: allErrors
-    };
-}

package/src/lib/train-feedback.js

@@ -1,46 +0,0 @@
-// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * Train Feedback Loop — JavaScript equivalent of do/lib/feedback.sh
- *
- * Generates post-completion feedback output with artifact locations
- * and deployment suggestions based on artifact type.
- */
-
-/**
- * Generate completion feedback output for a training/tuning job.
- *
- * Replicates the logic of print_completion_feedback() in do/lib/feedback.sh.
- *
- * @param {object} params
- * @param {string} params.outputPath - S3 URI to the output artifacts
- * @param {string} params.outputType - "adapter" or "full-model"
- * @param {string} params.jobName - Job name for reference
- * @param {string} [params.modelPackageArn] - Optional model package ARN
- * @returns {string} The formatted feedback output
- */
-export function generateCompletionFeedback({ outputPath, outputType, jobName, modelPackageArn = '' }) {
-    const lines = [];
-
-    lines.push('');
-    lines.push(`✅ Training complete: ${jobName}`);
-    lines.push('');
-    lines.push(`   Artifacts: ${outputPath}`);
-    if (modelPackageArn) {
-        lines.push(`   Model Package: ${modelPackageArn}`);
-    }
-    lines.push('');
-    lines.push('   Next steps:');
-
-    if (outputType === 'adapter') {
-        lines.push(`     • Deploy as LoRA adapter:  ./do/adapter add my-adapter --weights ${outputPath}`);
-        lines.push('     • (Requires running endpoint with LoRA enabled)');
-    } else if (outputType === 'full-model') {
-        lines.push(`     • Deploy as new IC:        ./do/add-ic my-model --model-data ${outputPath}`);
-        lines.push(`     • Replace current base:    ./do/deploy --force-ic --model-data ${outputPath}`);
-    }
-    lines.push('');
-
-    return lines.join('\n');
-}

package/src/lib/train-idempotency.js

@@ -1,97 +0,0 @@
-// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * Train Idempotency Decision Logic
- *
- * Models the idempotency check logic from the bash `_check_idempotency` function
- * in `templates/do/train` as a pure JavaScript function for property-based testing.
- *
- * The idempotency pattern:
- * - If --force is set, always create a new job regardless of existing status
- * - If no existing job, create a new job
- * - If existing job is InProgress, poll it
- * - If existing job is Completed, display results
- * - If existing job is Failed or Stopped, display failure and suggest --force
- *
- * Requirements: 5.1–5.5
- */
-
-/**
- * Valid existing job statuses that SageMaker can report.
- */
-export const JOB_STATUSES = ['InProgress', 'Completed', 'Failed', 'Stopped'];
-
-/**
- * Possible actions the train script can take after the idempotency check.
- */
-export const ACTIONS = {
-    CREATE_NEW_JOB: 'create_new_job',
-    POLL_EXISTING: 'poll_existing',
-    DISPLAY_RESULTS: 'display_results',
-    DISPLAY_FAILURE: 'display_failure'
-};
-
-/**
- * Determine the action to take based on existing job status and force flag.
- *
- * This mirrors the bash `_check_idempotency` logic in a testable form:
- * - force=true → always create_new_job
- * - no existing status (null/empty) → create_new_job
- * - InProgress → poll_existing
- * - Completed → display_results
- * - Failed → display_failure
- * - Stopped → display_failure
- *
- * @param {string|null|undefined} existingStatus - The current job status from DescribeTrainingJob
- * @param {boolean} forceFlag - Whether --force was specified
- * @returns {{ action: string, reason: string }}
- *   - action: one of ACTIONS values
- *   - reason: human-readable explanation of why this action was chosen
- */
-export function determineAction(existingStatus, forceFlag) {
-    // Force flag always overrides — create a new job regardless of existing status
-    if (forceFlag === true) {
-        return {
-            action: ACTIONS.CREATE_NEW_JOB,
-            reason: '--force specified, creating new job regardless of existing status'
-        };
-    }
-
-    // No existing job — create a new one
-    if (!existingStatus || existingStatus === '') {
-        return {
-            action: ACTIONS.CREATE_NEW_JOB,
-            reason: 'No existing job found, creating new job'
-        };
-    }
-
-    // Existing job found — action depends on status
-    switch (existingStatus) {
-    case 'InProgress':
-        return {
-            action: ACTIONS.POLL_EXISTING,
-            reason: `Existing job is ${existingStatus}, resuming polling`
-        };
-
-    case 'Completed':
-        return {
-            action: ACTIONS.DISPLAY_RESULTS,
-            reason: `Existing job is ${existingStatus}, displaying results`
-        };
-
-    case 'Failed':
-    case 'Stopped':
-        return {
-            action: ACTIONS.DISPLAY_FAILURE,
-            reason: `Existing job is ${existingStatus}, suggest --force to create new job`
-        };
-
-    default:
-        // Unknown status — treat as failure, suggest --force
-        return {
-            action: ACTIONS.DISPLAY_FAILURE,
-            reason: `Unexpected job status: ${existingStatus}, suggest --force`
-        };
-    }
-}