@aws/ml-container-creator 0.2.0

package/src/lib/configuration-matcher.js

@@ -0,0 +1,221 @@
+/**
+ * Configuration Matcher
+ * 
+ * Finds best matching configurations for user selections.
+ * Supports exact matching, fuzzy version matching, and pattern matching.
+ */
+
+class ConfigurationMatcher {
+    constructor(frameworkRegistry = {}, modelRegistry = {}) {
+        this.frameworkRegistry = frameworkRegistry;
+        this.modelRegistry = modelRegistry;
+    }
+
+    /**
+     * Match framework configuration
+     * Tries exact match first, then finds closest compatible version
+     * @param {string} framework - Framework name
+     * @param {string} version - Framework version
+     * @returns {Object|null} Framework configuration or null if not found
+     */
+    matchFramework(framework, version) {
+        if (!Object.hasOwn(this.frameworkRegistry, framework)) {
+            return null;
+        }
+        const frameworkVersions = this.frameworkRegistry[framework];
+
+        // Exact match first
+        if (Object.hasOwn(frameworkVersions, version)) {
+            return {
+                ...frameworkVersions[version],
+                matchType: 'exact',
+                matchedVersion: version
+            };
+        }
+
+        // Find closest compatible version
+        const closestMatch = this.findClosestVersion(frameworkVersions, version);
+        if (closestMatch) {
+            return {
+                ...closestMatch.config,
+                matchType: 'fuzzy',
+                matchedVersion: closestMatch.version,
+                requestedVersion: version
+            };
+        }
+
+        return null;
+    }
+
+    /**
+     * Find closest compatible version using semantic versioning
+     * @param {Object} versions - Available versions object
+     * @param {string} targetVersion - Target version to match
+     * @returns {Object|null} Object with {version, config} or null
+     */
+    findClosestVersion(versions, targetVersion) {
+        const availableVersions = Object.keys(versions);
+        if (availableVersions.length === 0) {
+            return null;
+        }
+
+        const target = this.parseVersion(targetVersion);
+        if (!target) {
+            return null;
+        }
+
+        let bestMatch = null;
+        let smallestDiff = Infinity;
+
+        for (const version of availableVersions) {
+            const current = this.parseVersion(version);
+            if (!current) continue;
+
+            // Calculate version distance
+            const diff = this.calculateVersionDistance(target, current);
+
+            // Prefer versions that are >= target (forward compatible)
+            // But also consider older versions if no newer ones exist
+            if (diff < smallestDiff) {
+                smallestDiff = diff;
+                bestMatch = { version, config: versions[version] };
+            }
+        }
+
+        return bestMatch;
+    }
+
+    /**
+     * Parse semantic version string into components
+     * @param {string} versionString - Version string (e.g., "1.2.3")
+     * @returns {Object|null} Object with {major, minor, patch} or null
+     */
+    parseVersion(versionString) {
+        if (!versionString || typeof versionString !== 'string') {
+            return null;
+        }
+
+        // Remove 'v' prefix if present
+        const cleaned = versionString.replace(/^v/, '');
+        
+        // Match semantic version pattern
+        const match = cleaned.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+        if (!match) {
+            return null;
+        }
+
+        return {
+            major: parseInt(match[1], 10),
+            minor: parseInt(match[2] || '0', 10),
+            patch: parseInt(match[3] || '0', 10)
+        };
+    }
+
+    /**
+     * Calculate distance between two versions
+     * Lower distance means closer match
+     * @param {Object} target - Target version {major, minor, patch}
+     * @param {Object} current - Current version {major, minor, patch}
+     * @returns {number} Distance value
+     */
+    calculateVersionDistance(target, current) {
+        // Major version difference is most significant
+        const majorDiff = Math.abs(current.major - target.major) * 10000;
+        
+        // Minor version difference
+        const minorDiff = Math.abs(current.minor - target.minor) * 100;
+        
+        // Patch version difference
+        const patchDiff = Math.abs(current.patch - target.patch);
+
+        // Prefer newer versions slightly (small penalty for older versions)
+        const directionPenalty = current.major < target.major ? 1 :
+            current.major === target.major && current.minor < target.minor ? 0.5 :
+                current.major === target.major && current.minor === target.minor && current.patch < target.patch ? 0.1 :
+                    0;
+
+        return majorDiff + minorDiff + patchDiff + directionPenalty;
+    }
+
+    /**
+     * Match model configuration
+     * Checks exact match first, then pattern matching
+     * @param {string} modelId - Model ID (e.g., "meta-llama/Llama-2-7b-chat-hf")
+     * @returns {Object|null} Model configuration or null if not found
+     */
+    matchModel(modelId) {
+        if (!modelId) {
+            return null;
+        }
+
+        // Check exact match first
+        if (Object.hasOwn(this.modelRegistry, modelId)) {
+            return {
+                ...this.modelRegistry[modelId],
+                matchType: 'exact',
+                matchedPattern: modelId
+            };
+        }
+
+        // Try pattern matching
+        const patternMatch = this.matchModelPattern(modelId);
+        if (patternMatch) {
+            return {
+                ...patternMatch.config,
+                matchType: 'pattern',
+                matchedPattern: patternMatch.pattern,
+                modelId
+            };
+        }
+
+        return null;
+    }
+
+    /**
+     * Match model by pattern (e.g., "mistral*" matches "mistralai/Mistral-7B-v0.1")
+     * @param {string} modelId - Model ID to match
+     * @returns {Object|null} Object with {pattern, config} or null
+     */
+    matchModelPattern(modelId) {
+        if (!modelId) {
+            return null;
+        }
+
+        for (const [pattern, config] of Object.entries(this.modelRegistry)) {
+            if (this.matchesPattern(modelId, pattern)) {
+                return { pattern, config };
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Check if a model ID matches a pattern
+     * Supports wildcards (*) and case-insensitive matching
+     * @param {string} modelId - Model ID to test
+     * @param {string} pattern - Pattern to match against
+     * @returns {boolean} True if matches
+     */
+    matchesPattern(modelId, pattern) {
+        if (!modelId || !pattern) {
+            return false;
+        }
+
+        // Exact match (no wildcards)
+        if (!pattern.includes('*')) {
+            return modelId.toLowerCase() === pattern.toLowerCase();
+        }
+
+        // Convert pattern to regex
+        // Escape special regex characters except *
+        const regexPattern = pattern
+            .replace(/[.+?^${}()|[\]\\]/g, '\\$&')  // Escape special chars
+            .replace(/\*/g, '.*');  // Convert * to .*
+
+        const regex = new RegExp(`^${regexPattern}$`, 'i');  // Case-insensitive
+        return regex.test(modelId);
+    }
+}
+
+export default ConfigurationMatcher;

package/src/lib/cpu-validator.js

@@ -0,0 +1,36 @@
+import AcceleratorValidator from './accelerator-validator.js';
+
+/**
+ * CPU accelerator validator.
+ * CPU-based inference is always compatible (no version requirements).
+ * 
+ * Requirements: 4.9
+ */
+export default class CpuValidator extends AcceleratorValidator {
+    /**
+     * Validate CPU compatibility.
+     * CPU is always compatible - no version checking needed.
+     * 
+     * @param {Object} frameworkConfig - Framework accelerator requirements
+     * @param {Object} instanceConfig - Instance accelerator capabilities
+     * @returns {Object} ValidationResult
+     */
+    validate(_frameworkConfig, _instanceConfig) {
+        return {
+            compatible: true,
+            info: 'CPU-based inference (no accelerator version requirements)'
+        };
+    }
+    
+    /**
+     * Get version mismatch message.
+     * Not used for CPU since it's always compatible.
+     * 
+     * @param {string} required - Required version
+     * @param {Array<string>|string} provided - Provided version(s)
+     * @returns {string} Empty string (not used for CPU)
+     */
+    getVersionMismatchMessage(_required, _provided) {
+        return ''; // Not used for CPU
+    }
+}

package/src/lib/cuda-validator.js

@@ -0,0 +1,57 @@
+import AcceleratorValidator from './accelerator-validator.js';
+
+/**
+ * CUDA-specific accelerator validator.
+ * Implements CUDA major.minor version comparison.
+ * 
+ * Requirements: 4.11, 4.12, 4.13, 4.14, 4.22
+ */
+export default class CudaValidator extends AcceleratorValidator {
+    /**
+     * Validate CUDA version compatibility.
+     * CUDA uses major.minor versioning (e.g., 12.1, 11.8).
+     * 
+     * @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 CUDA version (major.minor)
+        const requiredMajor = parseInt(required.version.split('.')[0]);
+        const requiredMinor = parseInt(required.version.split('.')[1]);
+        
+        // Check if instance supports required CUDA version
+        // Instance must have same major version and >= minor version
+        const compatibleVersions = provided.versions.filter(v => {
+            const [major, minor] = v.split('.').map(Number);
+            return major === requiredMajor && minor >= requiredMinor;
+        });
+        
+        if (compatibleVersions.length === 0) {
+            return {
+                compatible: false,
+                error: this.getVersionMismatchMessage(required.version, provided.versions)
+            };
+        }
+        
+        return {
+            compatible: true,
+            info: `Using CUDA ${compatibleVersions[0]} (compatible with required ${required.version})`
+        };
+    }
+    
+    /**
+     * Get user-friendly error message for CUDA version mismatch.
+     * 
+     * @param {string} required - Required CUDA version
+     * @param {Array<string>} provided - Provided CUDA versions
+     * @returns {string} User-friendly error message
+     */
+    getVersionMismatchMessage(required, provided) {
+        return `Framework requires CUDA ${required}, but instance only supports ${provided.join(', ')}. ` +
+               'Consider using ml.g5 or ml.g6 instances for CUDA 12.x support.';
+    }
+}

package/src/lib/deployment-config-resolver.js

@@ -0,0 +1,103 @@
+/**
+ * DeploymentConfigResolver
+ *
+ * Decomposes a flat deployment-config string into a structured
+ * { architecture, backend, engine } triple. This is the single source
+ * of truth for all valid deployment-config values, replacing the
+ * scattered split('-') logic that was previously in ConfigManager,
+ * PromptRunner, and index.js.
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
+ */
+
+/**
+ * Canonical mapping from deployment-config strings to structured parts.
+ * 2 http + 5 transformers + 7 triton + 1 diffusors = 15 total configs.
+ */
+const CANONICAL_CONFIGS = new Map([
+    // HTTP architecture (2)
+    ['http-flask',              { architecture: 'http',         backend: 'flask',         engine: null }],
+    ['http-fastapi',            { architecture: 'http',         backend: 'fastapi',       engine: null }],
+
+    // Transformers architecture (5)
+    ['transformers-vllm',       { architecture: 'transformers', backend: 'vllm',          engine: null }],
+    ['transformers-sglang',     { architecture: 'transformers', backend: 'sglang',        engine: null }],
+    ['transformers-tensorrt-llm', { architecture: 'transformers', backend: 'tensorrt-llm', engine: null }],
+    ['transformers-lmi',        { architecture: 'transformers', backend: 'lmi',           engine: null }],
+    ['transformers-djl',        { architecture: 'transformers', backend: 'djl',           engine: null }],
+
+    // Triton architecture (7)
+    ['triton-fil',              { architecture: 'triton',       backend: 'fil',           engine: null }],
+    ['triton-onnxruntime',      { architecture: 'triton',       backend: 'onnxruntime',   engine: null }],
+    ['triton-tensorflow',       { architecture: 'triton',       backend: 'tensorflow',    engine: null }],
+    ['triton-pytorch',          { architecture: 'triton',       backend: 'pytorch',       engine: null }],
+    ['triton-vllm',             { architecture: 'triton',       backend: 'vllm',          engine: null }],
+    ['triton-tensorrtllm',      { architecture: 'triton',       backend: 'tensorrtllm',   engine: null }],
+    ['triton-python',           { architecture: 'triton',       backend: 'python',        engine: null }],
+
+    // Diffusors architecture (1)
+    ['diffusors-vllm-omni',     { architecture: 'diffusors',    backend: 'vllm-omni',     engine: null }],
+])
+
+export default class DeploymentConfigResolver {
+    /**
+     * Decompose a deployment-config string into its constituent parts.
+     *
+     * @param {string} deploymentConfig - e.g. 'http-flask', 'transformers-vllm', 'triton-fil'
+     * @returns {{ architecture: string, backend: string, engine: string|null }}
+     * @throws {Error} if the deployment-config is not one of the 15 canonical values
+     */
+    decompose(deploymentConfig) {
+        const parts = CANONICAL_CONFIGS.get(deploymentConfig)
+        if (!parts) {
+            const valid = this.getAllConfigs().join(', ')
+            throw new Error(
+                `Unsupported deployment-config: ${deploymentConfig}. Valid configs: ${valid}`
+            )
+        }
+        return { ...parts }
+    }
+
+    /**
+     * Compose a deployment-config string from structured parts.
+     * Inverse of decompose().
+     *
+     * @param {{ architecture: string, backend: string, engine?: string }} parts
+     * @returns {string}
+     */
+    compose(parts) {
+        return `${parts.architecture}-${parts.backend}`
+    }
+
+    /**
+     * Get all 15 valid deployment-config strings.
+     *
+     * @returns {string[]}
+     */
+    getAllConfigs() {
+        return [...CANONICAL_CONFIGS.keys()]
+    }
+
+    /**
+     * Get valid deployment-config strings for a given architecture.
+     *
+     * @param {string} architecture - 'http' | 'transformers' | 'triton' | 'diffusors'
+     * @returns {string[]}
+     */
+    getConfigsForArchitecture(architecture) {
+        return this.getAllConfigs().filter(
+            (dc) => CANONICAL_CONFIGS.get(dc).architecture === architecture
+        )
+    }
+
+    /**
+     * Check if a deployment-config string is valid.
+     * Old-format strings (e.g. 'sklearn-flask') return false.
+     *
+     * @param {string} deploymentConfig
+     * @returns {boolean}
+     */
+    isValid(deploymentConfig) {
+        return CANONICAL_CONFIGS.has(deploymentConfig)
+    }
+}

package/src/lib/deployment-entry-schema.js

@@ -0,0 +1,125 @@
+/**
+ * JSON Schema for Deployment Entry
+ *
+ * Defines the structure and validation rules for deployment registry entries.
+ * Each entry captures the full configuration state and outcome of a single
+ * ML model deployment.
+ */
+
+export default {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'object',
+    required: [
+        'id',
+        'timestamp',
+        'status',
+        'deployment',
+        'model',
+        'infrastructure',
+        'configuration',
+        'outcome',
+        'metadata'
+    ],
+    properties: {
+        id: {
+            type: 'string',
+            pattern: '^[0-9a-f]{8}$'
+        },
+        timestamp: {
+            type: 'string',
+            pattern: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$'
+        },
+        status: {
+            type: 'string',
+            enum: ['success', 'partial', 'failed']
+        },
+        deployment: {
+            type: 'object',
+            required: ['deploymentConfig', 'architecture', 'backend'],
+            properties: {
+                deploymentConfig: {
+                    type: 'string',
+                    minLength: 1
+                },
+                architecture: {
+                    type: 'string',
+                    enum: ['http', 'transformers', 'triton', 'diffusors']
+                },
+                backend: {
+                    type: 'string',
+                    minLength: 1
+                },
+                baseImage: {
+                    type: ['string', 'null']
+                },
+                deploymentTarget: {
+                    type: ['string', 'null']
+                },
+                buildTarget: {
+                    type: ['string', 'null']
+                }
+            }
+        },
+        model: {
+            type: 'object',
+            required: ['modelName'],
+            properties: {
+                modelName: {
+                    type: 'string',
+                    minLength: 1
+                },
+                modelFormat: {
+                    type: ['string', 'null']
+                }
+            }
+        },
+        infrastructure: {
+            type: 'object',
+            properties: {
+                instanceType: {
+                    type: ['string', 'null']
+                },
+                region: {
+                    type: ['string', 'null']
+                },
+                roleArn: {
+                    type: ['string', 'null']
+                }
+            }
+        },
+        configuration: {
+            type: 'object',
+            required: ['parameters'],
+            properties: {
+                parameters: {
+                    type: 'object'
+                }
+            }
+        },
+        outcome: {
+            type: 'object',
+            properties: {
+                notes: {
+                    type: ['string', 'null']
+                }
+            }
+        },
+        metadata: {
+            type: 'object',
+            required: ['generatorVersion', 'source'],
+            properties: {
+                generatorVersion: {
+                    type: 'string',
+                    minLength: 1
+                },
+                source: {
+                    type: 'string',
+                    enum: ['local', 'imported', 'community']
+                },
+                importedFrom: {
+                    type: ['string', 'null']
+                }
+            }
+        }
+    }
+};