@aws/ml-container-creator 0.2.0

package/src/lib/registry-loader.js

@@ -0,0 +1,198 @@
+/**
+ * Registry Loader
+ *
+ * Loads configuration data from catalog JSON files and transforms them
+ * into the shapes expected by consumer modules (Configuration_Manager,
+ * Configuration_Matcher, Prompt_Runner, Validation_Engine, Template_Engine).
+ *
+ * This is the adapter layer between catalog JSON (single source of truth)
+ * and the generator's internal data shapes. No MCP runtime dependency.
+ */
+
+import { readFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// Catalog file paths relative to this module
+const CATALOG_PATHS = {
+    modelServers: resolve(__dirname, '../../servers/base-image-picker/catalogs/model-servers.json'),
+    tritonBackends: resolve(__dirname, '../../servers/base-image-picker/catalogs/triton-backends.json'),
+    instances: resolve(__dirname, '../../servers/instance-recommender/catalogs/instances.json'),
+    popularTransformers: resolve(__dirname, '../../servers/model-picker/catalogs/popular-transformers.json'),
+    popularDiffusors: resolve(__dirname, '../../servers/model-picker/catalogs/popular-diffusors.json'),
+}
+
+class RegistryLoader {
+    constructor() {
+        this._catalogCache = {}
+    }
+
+    /**
+     * Load and parse a JSON catalog file with caching.
+     * Returns null on failure (missing file, invalid JSON).
+     */
+    _loadCatalog(catalogPath) {
+        if (this._catalogCache[catalogPath] !== undefined) {
+            return this._catalogCache[catalogPath]
+        }
+        try {
+            const raw = readFileSync(catalogPath, 'utf8')
+            const data = JSON.parse(raw)
+            this._catalogCache[catalogPath] = data
+            return data
+        } catch (error) {
+            console.warn(`Failed to load catalog ${catalogPath}: ${error.message}`)
+            this._catalogCache[catalogPath] = null
+            return null
+        }
+    }
+
+    /**
+     * Load framework registry from model-servers.json catalog.
+     *
+     * Transforms catalog Image_Entry arrays into the shape:
+     *   { frameworkName: { version: FrameworkConfig } }
+     *
+     * Where FrameworkConfig = {
+     *   baseImage, accelerator, envVars, inferenceAmiVersion,
+     *   recommendedInstanceTypes, validationLevel, profiles, notes
+     * }
+     *
+     * @returns {Object} Framework registry or empty object on failure
+     */
+    async loadFrameworkRegistry() {
+        try {
+            const catalog = this._loadCatalog(CATALOG_PATHS.modelServers)
+            if (!catalog) return {}
+
+            const registry = {}
+            for (const [frameworkName, entries] of Object.entries(catalog)) {
+                if (!Array.isArray(entries)) continue
+                registry[frameworkName] = {}
+
+                for (const entry of entries) {
+                    const version = entry.labels?.framework_version
+                    if (!version) continue
+
+                    registry[frameworkName][version] = {
+                        baseImage: entry.image,
+                        accelerator: entry.accelerator || { type: 'cpu', version: null, versionRange: { min: null, max: null } },
+                        envVars: entry.defaults?.envVars || {},
+                        inferenceAmiVersion: entry.defaults?.inferenceAmiVersion || '',
+                        recommendedInstanceTypes: entry.defaults?.recommendedInstanceTypes || [],
+                        validationLevel: entry.validationLevel || 'untested',
+                        profiles: entry.profiles || {},
+                        notes: entry.notes || '',
+                    }
+                }
+            }
+            return registry
+        } catch (error) {
+            console.warn(`Failed to load framework registry: ${error.message}`)
+            return {}
+        }
+    }
+
+    /**
+     * Load model registry from popular-transformers.json and popular-diffusors.json.
+     *
+     * Merges both catalogs into a single object with the shape:
+     *   { modelIdOrPattern: ModelConfig }
+     *
+     * Where ModelConfig = {
+     *   family, chatTemplate, requiresTemplate, validationLevel,
+     *   frameworkCompatibility, profiles, notes
+     * }
+     *
+     * Maps catalog snake_case keys to camelCase:
+     *   chat_template → chatTemplate
+     *   framework_compatibility → frameworkCompatibility
+     *   validation_level → validationLevel
+     *
+     * @returns {Object} Model registry or empty object on failure
+     */
+    async loadModelRegistry() {
+        try {
+            const transformers = this._loadCatalog(CATALOG_PATHS.popularTransformers) || {}
+            const diffusors = this._loadCatalog(CATALOG_PATHS.popularDiffusors) || {}
+
+            const registry = {}
+            const allModels = { ...transformers, ...diffusors }
+
+            for (const [modelId, entry] of Object.entries(allModels)) {
+                registry[modelId] = {
+                    family: entry.family || '',
+                    chatTemplate: entry.chat_template ?? null,
+                    requiresTemplate: entry.chat_template != null && entry.chat_template !== '',
+                    validationLevel: entry.validation_level || 'experimental',
+                    frameworkCompatibility: entry.framework_compatibility || {},
+                    profiles: entry.profiles || {},
+                    notes: entry.notes || '',
+                }
+            }
+            return registry
+        } catch (error) {
+            console.warn(`Failed to load model registry: ${error.message}`)
+            return {}
+        }
+    }
+
+    /**
+     * Load instance accelerator mapping from instances.json catalog.
+     *
+     * Transforms catalog entries into the shape:
+     *   { instanceType: { family, accelerator: { type, hardware, architecture, versions, default }, memory, vcpus, notes } }
+     *
+     * @returns {Object} Instance accelerator mapping or empty object on failure
+     */
+    async loadInstanceAcceleratorMapping() {
+        try {
+            const catalog = this._loadCatalog(CATALOG_PATHS.instances)
+            if (!catalog || !catalog.catalog) return {}
+
+            const mapping = {}
+            for (const [instanceType, entry] of Object.entries(catalog.catalog)) {
+                mapping[instanceType] = {
+                    family: entry.family || '',
+                    accelerator: {
+                        type: entry.acceleratorType || 'cpu',
+                        hardware: entry.hardware || 'None',
+                        architecture: entry.gpuArchitecture || 'None',
+                        versions: entry.cudaVersions || null,
+                        default: entry.defaultCudaVersion || null,
+                    },
+                    memory: entry.memGb ? `${entry.memGb} GB` : '0 GB',
+                    vcpus: entry.vcpus || 0,
+                    notes: entry.notes || '',
+                }
+            }
+            return mapping
+        } catch (error) {
+            console.warn(`Failed to load instance accelerator mapping: ${error.message}`)
+            return {}
+        }
+    }
+
+    /**
+     * Load Triton backend metadata from triton-backends.json catalog.
+     *
+     * Returns the catalog data directly since its shape already matches
+     * what consumers expect.
+     *
+     * @returns {Object} Triton backends or empty object on failure
+     */
+    async loadTritonBackends() {
+        try {
+            const catalog = this._loadCatalog(CATALOG_PATHS.tritonBackends)
+            return catalog || {}
+        } catch (error) {
+            console.warn(`Failed to load triton backends: ${error.message}`)
+            return {}
+        }
+    }
+}
+
+export default RegistryLoader

package/src/lib/rocm-validator.js

@@ -0,0 +1,80 @@
+import AcceleratorValidator from './accelerator-validator.js';
+
+/**
+ * ROCm accelerator validator for AMD GPUs.
+ * Implements ROCm semantic versioning.
+ * 
+ * Requirements: 4.9, 4.22
+ */
+export default class RocmValidator extends AcceleratorValidator {
+    /**
+     * Validate ROCm version compatibility.
+     * ROCm uses semantic versioning (e.g., 5.4.0, 5.5.0).
+     * Major version must match, minor version must be >= required.
+     * 
+     * @param {Object} frameworkConfig - Framework accelerator requirements
+     * @param {Object} instanceConfig - Instance accelerator capabilities
+     * @returns {Object} ValidationResult
+     */
+    validate(frameworkConfig, instanceConfig) {
+        const required = frameworkConfig.accelerator;
+        const provided = instanceConfig.accelerator;
+        
+        // Parse required ROCm version
+        const requiredVersion = this.parseVersion(required.version);
+        
+        // Check if instance supports required ROCm version
+        const compatibleVersions = provided.versions.filter(v => {
+            const providedVersion = this.parseVersion(v);
+            return this.isCompatible(requiredVersion, providedVersion);
+        });
+        
+        if (compatibleVersions.length === 0) {
+            return {
+                compatible: false,
+                error: this.getVersionMismatchMessage(required.version, provided.versions)
+            };
+        }
+        
+        return {
+            compatible: true,
+            info: `Using ROCm ${compatibleVersions[0]} (compatible with required ${required.version})`
+        };
+    }
+    
+    /**
+     * Parse semantic version string into components.
+     * 
+     * @param {string} versionString - Version string (e.g., "5.4.0")
+     * @returns {Object} Parsed version with major, minor, patch
+     */
+    parseVersion(versionString) {
+        const [major, minor, patch] = versionString.split('.').map(Number);
+        return { major, minor, patch };
+    }
+    
+    /**
+     * Check if provided version is compatible with required version.
+     * ROCm: major must match, minor must be >= required.
+     * 
+     * @param {Object} required - Required version
+     * @param {Object} provided - Provided version
+     * @returns {boolean} True if compatible
+     */
+    isCompatible(required, provided) {
+        return provided.major === required.major && 
+               provided.minor >= required.minor;
+    }
+    
+    /**
+     * Get user-friendly error message for ROCm version mismatch.
+     * 
+     * @param {string} required - Required ROCm version
+     * @param {Array<string>} provided - Provided ROCm versions
+     * @returns {string} User-friendly error message
+     */
+    getVersionMismatchMessage(required, provided) {
+        return `Framework requires ROCm ${required}, but instance only supports ${provided.join(', ')}. ` +
+               'AMD GPU instances with ROCm support may be limited in SageMaker.';
+    }
+}

package/src/lib/schema-validator.js

@@ -0,0 +1,157 @@
+/**
+ * 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/sensitive-redactor.js

@@ -0,0 +1,59 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Sensitive Value Redactor
+ *
+ * Detects keys matching sensitive patterns and replaces their values
+ * with a redaction marker. Used by the do/register template to sanitize
+ * parameters before writing to DynamoDB.
+ *
+ * Requirements: 6.5
+ */
+
+/**
+ * Redaction marker used to replace sensitive values.
+ */
+export const REDACTION_MARKER = '***REDACTED***'
+
+/**
+ * Exact key names that are always considered sensitive.
+ */
+export const SENSITIVE_EXACT_KEYS = ['HF_TOKEN', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN']
+
+/**
+ * Substrings that, when found in a key (case-insensitive), mark it as sensitive.
+ */
+export const SENSITIVE_SUBSTRINGS = ['SECRET', 'TOKEN']
+
+/**
+ * Determine whether a given key matches sensitive patterns.
+ *
+ * A key is sensitive if:
+ * - It exactly matches one of SENSITIVE_EXACT_KEYS
+ * - Its uppercase form contains any of SENSITIVE_SUBSTRINGS
+ *
+ * @param {string} key - The environment variable key to check
+ * @returns {boolean} True if the key is sensitive
+ */
+export function isSensitiveKey(key) {
+    if (SENSITIVE_EXACT_KEYS.includes(key)) return true
+    const upper = key.toUpperCase()
+    return SENSITIVE_SUBSTRINGS.some(sub => upper.includes(sub))
+}
+
+/**
+ * Redact sensitive values in a parameters object.
+ * Returns a new object with sensitive values replaced by the redaction marker.
+ * Non-sensitive values are preserved unchanged.
+ *
+ * @param {Object<string, string>} params - Key-value map of parameters
+ * @returns {Object<string, string>} New object with sensitive values redacted
+ */
+export function redactSensitiveValues(params) {
+    const result = {}
+    for (const [key, value] of Object.entries(params)) {
+        result[key] = isSensitiveKey(key) ? REDACTION_MARKER : value
+    }
+    return result
+}

package/src/lib/template-engine.js

@@ -0,0 +1,156 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from 'fs';
+import path from 'path';
+import ejs from 'ejs';
+import CommentGenerator from './comment-generator.js';
+
+/**
+ * TemplateEngine - Generates files with injected configurations
+ * 
+ * Responsible for generating Dockerfiles and deployment scripts with
+ * configuration data from catalogs, HuggingFace API, and user input.
+ * Integrates CommentGenerator for comprehensive documentation.
+ */
+export default class TemplateEngine {
+    /**
+     * @param {Object} options - Configuration options
+     * @param {string} options.templateDir - Root directory containing template files
+     * @param {string} options.destDir - Root directory for generated output
+     */
+    constructor({ templateDir, destDir }) {
+        this.templateDir = templateDir;
+        this.destDir = destDir;
+        this.commentGenerator = new CommentGenerator();
+    }
+
+    /**
+     * Generate Dockerfile with configuration injection
+     * @param {Object} config - Configuration profile
+     * @returns {void}
+     */
+    generateDockerfile(config) {
+        // Generate comments for documentation
+        const comments = this.commentGenerator.generateDockerfileComments(config);
+
+        // Prepare template variables with configuration and comments
+        const templateVars = {
+            ...config,
+            comments,
+            // Preserve environment variable ordering
+            orderedEnvVars: this._getOrderedEnvVars(config.envVars || {})
+        };
+
+        // Render and write Dockerfile template
+        this._renderTemplate('Dockerfile', 'Dockerfile', templateVars);
+    }
+
+    /**
+     * Generate deployment script with configuration injection
+     * @param {Object} config - Configuration profile
+     * @returns {void}
+     */
+    generateDeploymentScript(config) {
+        // No-op: legacy deploy/ scripts have been removed.
+        // Deployment is handled by do/deploy in the do-framework.
+    }
+
+    /**
+     * Render a single EJS template file to the destination directory.
+     * @private
+     * @param {string} templateRelPath - Relative path within templateDir
+     * @param {string} destRelPath - Relative path within destDir
+     * @param {Object} vars - Template variables for EJS rendering
+     */
+    _renderTemplate(templateRelPath, destRelPath, vars) {
+        const src = path.resolve(this.templateDir, templateRelPath);
+        const dest = path.resolve(this.destDir, destRelPath);
+
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+
+        const content = fs.readFileSync(src, 'utf8');
+        const rendered = ejs.render(content, vars, { filename: src });
+        fs.writeFileSync(dest, rendered);
+    }
+
+    /**
+     * Get environment variables in correct order
+     * Preserves dependency order (e.g., CUDA paths before framework variables)
+     * @private
+     * @param {Object} envVars - Environment variables object
+     * @returns {Array<{key: string, value: string}>} Ordered array of env vars
+     */
+    _getOrderedEnvVars(envVars) {
+        const entries = Object.entries(envVars);
+        
+        // Define priority order for environment variable categories
+        const priorities = {
+            // System paths (highest priority)
+            'LD_LIBRARY_PATH': 1,
+            'PATH': 1,
+            'CUDA_HOME': 1,
+            'CUDA_PATH': 1,
+            
+            // CUDA configuration
+            'CUDA_VISIBLE_DEVICES': 2,
+            'NVIDIA_VISIBLE_DEVICES': 2,
+            'NVIDIA_DRIVER_CAPABILITIES': 2,
+            
+            // Framework-specific (medium priority)
+            'VLLM': 3,
+            'TENSORRT': 3,
+            'SGLANG': 3,
+            'TRANSFORMERS': 3,
+            
+            // Application configuration (lower priority)
+            'MAX': 4,
+            'BATCH': 4,
+            'WORKER': 4,
+            'THREAD': 4,
+            
+            // Other variables (lowest priority)
+            'default': 5
+        };
+
+        // Sort entries by priority
+        const sorted = entries.sort(([keyA], [keyB]) => {
+            const priorityA = this._getEnvVarPriority(keyA, priorities);
+            const priorityB = this._getEnvVarPriority(keyB, priorities);
+            
+            if (priorityA !== priorityB) {
+                return priorityA - priorityB;
+            }
+            
+            // If same priority, sort alphabetically
+            return keyA.localeCompare(keyB);
+        });
+
+        // Convert to array of objects for template
+        return sorted.map(([key, value]) => ({ key, value }));
+    }
+
+    /**
+     * Get priority for an environment variable
+     * @private
+     * @param {string} key - Environment variable name
+     * @param {Object} priorities - Priority mapping
+     * @returns {number} Priority value (lower = higher priority)
+     */
+    _getEnvVarPriority(key, priorities) {
+        // Check for exact match first
+        if (priorities[key]) {
+            return priorities[key];
+        }
+
+        // Check for partial matches
+        for (const [pattern, priority] of Object.entries(priorities)) {
+            if (pattern !== 'default' && key.includes(pattern)) {
+                return priority;
+            }
+        }
+
+        // Default priority
+        return priorities.default;
+    }
+}