@aws/ml-container-creator 0.2.5 → 0.2.6

package/src/lib/bootstrap-command-handler.js

@@ -45,6 +45,12 @@ export default class BootstrapCommandHandler {
      * @param {object} options - Parsed CLI options
      */
     async handle(args, options) {
+        // Handle legacy --sync-schemas flag for backward compatibility
+        if (options['sync-schemas']) {
+            await this._handleSyncSchemas();
+            if (args.length === 0) return;
+        }
+
         if (args.length === 0) {
             await this._handleInteractiveSetup(options);
             return;
@@ -74,6 +80,9 @@ export default class BootstrapCommandHandler {
         case 'update':
             await this._handleUpdate(options);
             break;
+        case 'sync-schemas':
+            await this._handleSyncSchemas();
+            break;
         default:
             console.log(`Unknown bootstrap subcommand: ${subcommand}`);
             this._showHelp();
@@ -927,6 +936,35 @@ export default class BootstrapCommandHandler {
         console.log(`\n  Done. ${toRemove.length} removed, ${after.length} remaining.`);
     }
 
+    /**
+     * Handle sync-schemas subcommand: download service models and verify AWS CLI.
+     */
+    async _handleSyncSchemas() {
+        console.log('\n📦 Schema Sync — Downloading AWS service models...\n');
+
+        // Verify AWS CLI is installed
+        try {
+            const version = execSync('aws --version', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+            console.log(`  AWS CLI: ${version}`);
+        } catch {
+            console.log('  ⚠️  AWS CLI not found.');
+            console.log('  Install: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html');
+            console.log('  Continuing without AWS CLI verification...\n');
+        }
+
+        // Dynamic import to avoid circular dependencies
+        const { syncSchemas } = await import('./schema-sync.js');
+        const result = await syncSchemas();
+
+        if (result.success) {
+            console.log('\n  ✅ Schema sync complete.');
+        } else {
+            console.log('\n  ⚠️  Schema sync completed with errors (some services may be unavailable).');
+        }
+
+        console.log(`  Manifest written: lastSynced = ${result.manifest.lastSynced}\n`);
+    }
+
     /**
      * Re-deploy bootstrap infrastructure using the active profile.
      * No prompts — reads all config from the existing profile and re-applies

package/src/lib/cli-handler.js

@@ -280,9 +280,9 @@ TRANSFORMER MODEL EXAMPLES:
 
 REGISTRY CONTRIBUTION:
   To contribute to the catalogs:
-  - Framework Catalog: servers/base-image-picker/catalogs/model-servers.json
-  - Model Catalog: servers/model-picker/catalogs/popular-transformers.json
-  - Instance Catalog: servers/instance-recommender/catalogs/instances.json
+  - Framework Catalog: servers/lib/catalogs/model-servers.json
+  - Model Catalog: servers/lib/catalogs/popular-transformers.json
+  - Instance Catalog: servers/lib/catalogs/instances.json
   
   See docs/REGISTRY_CONTRIBUTION_GUIDE.md for detailed contribution guidelines.
 

package/src/lib/config-manager.js

@@ -29,7 +29,7 @@ import ParameterSchemaValidator from './parameter-schema-validator.js';
 
 const __configMgrFilename = fileURLToPath(import.meta.url);
 const __configMgrDir = dirname(__configMgrFilename);
-const tritonBackendsCatalogPath = resolve(__configMgrDir, '../../servers/base-image-picker/catalogs/triton-backends.json');
+const tritonBackendsCatalogPath = resolve(__configMgrDir, '../../servers/lib/catalogs/triton-backends.json');
 
 function loadTritonBackendsFromCatalog() {
     try {
@@ -1927,6 +1927,9 @@ export default class ConfigManager {
             // For required parameters: fill auto-generatable values
             if (this.config[param] === undefined || this.config[param] === null) {
                 if (param === 'instanceType') {
+                    // If instance-sizer is configured and model is known, defer to sizer
+                    // The sizer query happens in PromptRunner after model is selected
+                    // For now, set a heuristic default that may be overridden by the sizer
                     const arch = architecture || 'http';
                     this.config[param] = arch === 'http' ? 'ml.m5.large' : 'ml.g5.xlarge';
                 } else if (param === 'modelFormat') {

package/src/lib/configuration-manager.js

@@ -619,8 +619,8 @@ export default class ConfigurationManager {
      */
     _generateSubmissionInstructions(registryType, config, configEntry) {
         const registryFile = registryType === 'framework' 
-            ? 'servers/base-image-picker/catalogs/model-servers.json'
-            : 'servers/model-picker/catalogs/popular-transformers.json';
+            ? 'servers/lib/catalogs/model-servers.json'
+            : 'servers/lib/catalogs/popular-transformers.json';
         
         const registryName = registryType === 'framework' 
             ? 'Framework_Catalog'

package/src/lib/cross-cutting-checker.js

@@ -0,0 +1,341 @@
+/* eslint-disable eqeqeq */
+/**
+ * Validates consistency rules across multiple payloads and configuration sources.
+ * Checks GPU counts, tensor parallelism, model source requirements, role ARN format,
+ * CUDA compatibility, and model type / instance alignment.
+ *
+ * Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6, 7.7
+ */
+export default class CrossCuttingChecker {
+    /**
+     * Run all cross-cutting consistency checks.
+     * @param {Object} context - ValidationContext from PayloadBuilder
+     * @param {Object} instanceCatalog - Instance catalog (from servers/lib/catalogs/instances.json)
+     * @returns {Array} Array of Finding objects
+     */
+    check(context, instanceCatalog) {
+        const findings = [];
+
+        findings.push(...this.checkGpuConsistency(context, instanceCatalog));
+        findings.push(...this.checkTensorParallelism(context, instanceCatalog));
+        findings.push(...this.checkModelSourceRequirements(context));
+        findings.push(...this.checkRoleArnFormat(context));
+        findings.push(...this.checkCudaCompatibility(context, instanceCatalog));
+        findings.push(...this.checkModelTypeInstanceAlignment(context, instanceCatalog));
+
+        return findings;
+    }
+
+    /**
+     * Verify GPU count consistency: instance type ↔ IC spec.
+     * @param {Object} context - ValidationContext
+     * @param {Object} instanceCatalog - Instance catalog
+     * @returns {Array} Findings
+     */
+    checkGpuConsistency(context, instanceCatalog) {
+        const findings = [];
+        const config = context.config || {};
+        const catalog = instanceCatalog?.catalog || instanceCatalog || {};
+
+        const instanceType = config.INSTANCE_TYPE;
+        if (!instanceType) return findings;
+
+        const instanceInfo = catalog[instanceType];
+        if (!instanceInfo) return findings;
+
+        const instanceGpuCount = instanceInfo.gpus;
+        if (instanceGpuCount == null || instanceGpuCount === 0) return findings;
+
+        const icGpuCount = config.IC_GPU_COUNT;
+        if (icGpuCount == null) return findings;
+
+        if (Number(icGpuCount) !== Number(instanceGpuCount)) {
+            findings.push({
+                service: 'cross-cutting',
+                operation: 'configuration',
+                fieldPath: 'NumberOfAcceleratorDevicesRequired',
+                invalidValue: icGpuCount,
+                constraint: {
+                    type: 'gpu-consistency',
+                    expected: instanceGpuCount,
+                    instanceType
+                },
+                severity: 'error',
+                confidence: 'high',
+                source: 'cross-cutting',
+                remediationHint: `NumberOfAcceleratorDevicesRequired (${icGpuCount}) does not match GPU count (${instanceGpuCount}) for instance type ${instanceType}. Set IC_GPU_COUNT to ${instanceGpuCount}.`
+            });
+        }
+
+        return findings;
+    }
+
+    /**
+     * Verify tensor parallelism three-way check:
+     * VLLM_TENSOR_PARALLEL_SIZE == NumberOfAcceleratorDevicesRequired == instance GPU count.
+     * Only applies when model server is vLLM or SGLang.
+     * @param {Object} context - ValidationContext
+     * @param {Object} instanceCatalog - Instance catalog
+     * @returns {Array} Findings
+     */
+    checkTensorParallelism(context, instanceCatalog) {
+        const findings = [];
+        const config = context.config || {};
+        const catalog = instanceCatalog?.catalog || instanceCatalog || {};
+
+        const modelServer = config.MODEL_SERVER || config.modelServer || '';
+        const normalizedServer = modelServer.toLowerCase();
+
+        if (normalizedServer !== 'vllm' && normalizedServer !== 'sglang') {
+            return findings;
+        }
+
+        const tpSize = config.VLLM_TENSOR_PARALLEL_SIZE;
+        if (tpSize == null) return findings;
+
+        const instanceType = config.INSTANCE_TYPE;
+        const instanceInfo = instanceType ? catalog[instanceType] : null;
+        const instanceGpuCount = instanceInfo?.gpus;
+
+        const icGpuCount = config.IC_GPU_COUNT;
+
+        // Check TP size vs IC GPU count
+        if (icGpuCount != null && Number(tpSize) !== Number(icGpuCount)) {
+            findings.push({
+                service: 'cross-cutting',
+                operation: 'configuration',
+                fieldPath: 'VLLM_TENSOR_PARALLEL_SIZE',
+                invalidValue: tpSize,
+                constraint: {
+                    type: 'tensor-parallelism',
+                    expected: icGpuCount,
+                    field: 'NumberOfAcceleratorDevicesRequired'
+                },
+                severity: 'error',
+                confidence: 'high',
+                source: 'cross-cutting',
+                remediationHint: `VLLM_TENSOR_PARALLEL_SIZE (${tpSize}) must equal NumberOfAcceleratorDevicesRequired (${icGpuCount}) for ${modelServer}.`
+            });
+        }
+
+        // Check TP size vs instance GPU count
+        if (instanceGpuCount != null && Number(tpSize) !== Number(instanceGpuCount)) {
+            findings.push({
+                service: 'cross-cutting',
+                operation: 'configuration',
+                fieldPath: 'VLLM_TENSOR_PARALLEL_SIZE',
+                invalidValue: tpSize,
+                constraint: {
+                    type: 'tensor-parallelism',
+                    expected: instanceGpuCount,
+                    field: 'instanceGpuCount'
+                },
+                severity: 'error',
+                confidence: 'high',
+                source: 'cross-cutting',
+                remediationHint: `VLLM_TENSOR_PARALLEL_SIZE (${tpSize}) must equal instance GPU count (${instanceGpuCount}) for ${instanceType}.`
+            });
+        }
+
+        return findings;
+    }
+
+    /**
+     * Verify model source requirements (artifact URI, hub access config).
+     * @param {Object} context - ValidationContext
+     * @returns {Array} Findings
+     */
+    checkModelSourceRequirements(context) {
+        const findings = [];
+        const config = context.config || {};
+
+        const modelSource = config.modelSource || config.MODEL_SOURCE || '';
+
+        // When modelSource is 'jumpstart-hub', verify HubAccessConfig.HubContentArn is present
+        if (modelSource === 'jumpstart-hub') {
+            const payloads = context.payloads || {};
+            let hubContentArnFound = false;
+
+            for (const payload of Object.values(payloads)) {
+                if (payload?.HubAccessConfig?.HubContentArn) {
+                    hubContentArnFound = true;
+                    break;
+                }
+            }
+
+            if (!hubContentArnFound && !config.HUB_CONTENT_ARN) {
+                findings.push({
+                    service: 'cross-cutting',
+                    operation: 'configuration',
+                    fieldPath: 'HubAccessConfig.HubContentArn',
+                    invalidValue: null,
+                    constraint: {
+                        type: 'conditional-required',
+                        condition: 'modelSource === jumpstart-hub'
+                    },
+                    severity: 'error',
+                    confidence: 'high',
+                    source: 'cross-cutting',
+                    remediationHint: 'When modelSource is "jumpstart-hub", HubAccessConfig.HubContentArn must be present in the payload.'
+                });
+            }
+        }
+
+        // When modelSource in {s3, jumpstart, jumpstart-hub, registry}, verify MODEL_ARTIFACT_URI is non-empty
+        const sourcesRequiringArtifact = ['s3', 'jumpstart', 'jumpstart-hub', 'registry'];
+        if (sourcesRequiringArtifact.includes(modelSource)) {
+            const artifactUri = config.MODEL_ARTIFACT_URI || '';
+            if (!artifactUri || artifactUri.trim() === '') {
+                findings.push({
+                    service: 'cross-cutting',
+                    operation: 'configuration',
+                    fieldPath: 'MODEL_ARTIFACT_URI',
+                    invalidValue: artifactUri || null,
+                    constraint: {
+                        type: 'conditional-required',
+                        condition: `modelSource === ${modelSource}`
+                    },
+                    severity: 'error',
+                    confidence: 'high',
+                    source: 'cross-cutting',
+                    remediationHint: `When modelSource is "${modelSource}", MODEL_ARTIFACT_URI must be set and non-empty.`
+                });
+            }
+        }
+
+        return findings;
+    }
+
+    /**
+     * Verify role ARN format for realtime-inference.
+     * @param {Object} context - ValidationContext
+     * @returns {Array} Findings
+     */
+    checkRoleArnFormat(context) {
+        const findings = [];
+        const config = context.config || {};
+        const deploymentTarget = context.deploymentTarget || '';
+
+        if (deploymentTarget !== 'realtime-inference') return findings;
+
+        const roleArn = config.ROLE_ARN;
+        if (roleArn == null || roleArn === '') return findings;
+
+        const arnPattern = /^arn:aws:iam::\d{12}:role\/.+$/;
+        if (!arnPattern.test(roleArn)) {
+            findings.push({
+                service: 'cross-cutting',
+                operation: 'configuration',
+                fieldPath: 'ROLE_ARN',
+                invalidValue: roleArn,
+                constraint: {
+                    type: 'pattern',
+                    pattern: 'arn:aws:iam::\\d{12}:role/.+'
+                },
+                severity: 'error',
+                confidence: 'high',
+                source: 'cross-cutting',
+                remediationHint: `ROLE_ARN "${roleArn}" does not match IAM role ARN pattern. Expected format: arn:aws:iam::<12-digit-account-id>:role/<role-name>.`
+            });
+        }
+
+        return findings;
+    }
+
+    /**
+     * Verify CUDA version compatibility: base image CUDA ∩ instance CUDA versions is non-empty.
+     * @param {Object} context - ValidationContext
+     * @param {Object} instanceCatalog - Instance catalog
+     * @returns {Array} Findings
+     */
+    checkCudaCompatibility(context, instanceCatalog) {
+        const findings = [];
+        const config = context.config || {};
+        const catalog = instanceCatalog?.catalog || instanceCatalog || {};
+
+        const instanceType = config.INSTANCE_TYPE;
+        if (!instanceType) return findings;
+
+        const instanceInfo = catalog[instanceType];
+        if (!instanceInfo) return findings;
+
+        const instanceCudaVersions = instanceInfo.cudaVersions;
+        if (!instanceCudaVersions || !Array.isArray(instanceCudaVersions) || instanceCudaVersions.length === 0) {
+            return findings;
+        }
+
+        // Extract base image CUDA requirement from config
+        const cudaRequirement = config.acceleratorVersion || config.CUDA_VERSION || '';
+        if (!cudaRequirement) return findings;
+
+        // Check if any instance CUDA version matches the base image requirement
+        // Compare major version (e.g., "12" matches "12.1", "12.2")
+        const requiredMajor = String(cudaRequirement).split('.')[0];
+
+        const hasCompatible = instanceCudaVersions.some(v => {
+            const vMajor = String(v).split('.')[0];
+            return vMajor === requiredMajor;
+        });
+
+        if (!hasCompatible) {
+            findings.push({
+                service: 'cross-cutting',
+                operation: 'configuration',
+                fieldPath: 'acceleratorVersion',
+                invalidValue: cudaRequirement,
+                constraint: {
+                    type: 'cuda-compatibility',
+                    instanceCudaVersions,
+                    instanceType
+                },
+                severity: 'error',
+                confidence: 'high',
+                source: 'cross-cutting',
+                remediationHint: `Base image requires CUDA ${cudaRequirement} but instance ${instanceType} supports CUDA versions [${instanceCudaVersions.join(', ')}]. No compatible CUDA version found.`
+            });
+        }
+
+        return findings;
+    }
+
+    /**
+     * Verify predictor models are not assigned GPU instances.
+     * @param {Object} context - ValidationContext
+     * @param {Object} instanceCatalog - Instance catalog
+     * @returns {Array} Findings
+     */
+    checkModelTypeInstanceAlignment(context, instanceCatalog) {
+        const findings = [];
+        const config = context.config || {};
+        const catalog = instanceCatalog?.catalog || instanceCatalog || {};
+
+        const modelType = config.modelType || config.MODEL_TYPE || '';
+        if (modelType !== 'predictor') return findings;
+
+        const instanceType = config.INSTANCE_TYPE;
+        if (!instanceType) return findings;
+
+        const instanceInfo = catalog[instanceType];
+        if (!instanceInfo) return findings;
+
+        if (instanceInfo.gpus > 0 || instanceInfo.category === 'gpu') {
+            findings.push({
+                service: 'cross-cutting',
+                operation: 'configuration',
+                fieldPath: 'INSTANCE_TYPE',
+                invalidValue: instanceType,
+                constraint: {
+                    type: 'model-type-alignment',
+                    modelType: 'predictor',
+                    instanceCategory: instanceInfo.category
+                },
+                severity: 'warning',
+                confidence: 'high',
+                source: 'cross-cutting',
+                remediationHint: `Model type "predictor" typically does not require GPU acceleration. Consider using a CPU instance (e.g., ml.m5.xlarge) instead of ${instanceType}.`
+            });
+        }
+
+        return findings;
+    }
+}

package/src/lib/dry-run-validator.js

@@ -0,0 +1,78 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Dry-run validator — a module that can be called during do/deploy --dry-run.
+ * Runs schema validation and blocks deployment if schema errors are found.
+ *
+ * Returns { passed: boolean, report: ValidationReport }
+ *
+ * Requirements: 9.1
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import PayloadBuilder from './payload-builder.js';
+import SchemaValidationEngine from './schema-validation-engine.js';
+import ServiceModelParser from './service-model-parser.js';
+import { getRegistryPath } from './schema-sync.js';
+
+/**
+ * Run schema validation for dry-run mode.
+ * Blocks deployment if schema errors are found.
+ *
+ * @param {Object} config - Configuration values from do/config
+ * @param {string} deploymentTarget - 'realtime-inference' | 'async-inference' | 'batch-transform'
+ * @param {Object} [options]
+ * @param {boolean} [options.smart] - Enable smart-mode validators
+ * @param {string} [options.registryPath] - Override schema registry path
+ * @returns {Promise<{ passed: boolean, report: Object|null, skipped: boolean }>}
+ */
+export async function validateDryRun(config, deploymentTarget, options = {}) {
+    const smart = options.smart || false;
+    const registryPath = options.registryPath || getRegistryPath();
+
+    // Skip if schema registry is not present
+    if (!existsSync(registryPath) || !existsSync(path.join(registryPath, 'manifest.json'))) {
+        return { passed: true, report: null, skipped: true };
+    }
+
+    // Construct payloads
+    const builder = new PayloadBuilder();
+    const context = builder.build(config, deploymentTarget);
+
+    // Load and parse service models from registry
+    const parser = new ServiceModelParser();
+    const serviceModels = [];
+    try {
+        const entries = readdirSync(registryPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const modelPath = path.join(registryPath, entry.name, 'service-2.json');
+                if (existsSync(modelPath)) {
+                    const rawModel = JSON.parse(readFileSync(modelPath, 'utf8'));
+                    serviceModels.push(parser.parse(rawModel));
+                }
+            }
+        }
+    } catch {
+        return { passed: true, report: null, skipped: true };
+    }
+
+    // Run validation engine
+    const engine = new SchemaValidationEngine({
+        registryPath,
+        smartMode: smart,
+        serviceModels
+    });
+
+    const report = await engine.validate(context);
+    const summary = report.getSummary();
+
+    // Block deployment if errors found
+    const passed = summary.errors === 0;
+
+    return { passed, report, skipped: false };
+}
+
+export default { validateDryRun };

package/src/lib/generation-validator.js

@@ -0,0 +1,102 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Generation-time validation helper.
+ * Called after deploy scripts are generated to validate payloads against service models.
+ * Prints errors as warnings (non-blocking) with a summary line.
+ *
+ * - Skips silently if schema registry is not present
+ * - Skips entirely if --no-validate flag is passed (check via options parameter)
+ *
+ * This is a standalone module — does NOT modify the main generator file.
+ *
+ * Requirements: 8.1, 8.2, 8.3, 8.4, 8.5
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import PayloadBuilder from './payload-builder.js';
+import SchemaValidationEngine from './schema-validation-engine.js';
+import ServiceModelParser from './service-model-parser.js';
+import { getRegistryPath } from './schema-sync.js';
+
+/**
+ * Run schema validation at generation time (non-blocking).
+ *
+ * @param {Object} config - Configuration values (from generator answers or do/config)
+ * @param {string} deploymentTarget - 'realtime-inference' | 'async-inference' | 'batch-transform'
+ * @param {Object} [options]
+ * @param {boolean} [options.noValidate] - If true, skip validation entirely
+ * @param {string} [options.registryPath] - Override schema registry path
+ * @returns {Promise<{ skipped: boolean, report: Object|null }>}
+ */
+export async function runGenerationValidation(config, deploymentTarget, options = {}) {
+    // Skip entirely if --no-validate flag is passed
+    if (options.noValidate) {
+        return { skipped: true, report: null };
+    }
+
+    const registryPath = options.registryPath || getRegistryPath();
+
+    // Skip silently if schema registry is not present
+    if (!existsSync(registryPath) || !existsSync(path.join(registryPath, 'manifest.json'))) {
+        return { skipped: true, report: null };
+    }
+
+    // Construct payloads
+    const builder = new PayloadBuilder();
+    const context = builder.build(config, deploymentTarget);
+
+    // Load and parse service models from registry
+    const parser = new ServiceModelParser();
+    const serviceModels = [];
+    try {
+        const entries = readdirSync(registryPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const modelPath = path.join(registryPath, entry.name, 'service-2.json');
+                if (existsSync(modelPath)) {
+                    const rawModel = JSON.parse(readFileSync(modelPath, 'utf8'));
+                    serviceModels.push(parser.parse(rawModel));
+                }
+            }
+        }
+    } catch {
+        // If we can't load models, skip validation silently
+        return { skipped: true, report: null };
+    }
+
+    // Run validation
+    const engine = new SchemaValidationEngine({
+        registryPath,
+        ignoreStaleness: true,
+        serviceModels
+    });
+
+    const report = await engine.validate(context);
+    const summary = report.getSummary();
+
+    // Print errors as warnings (non-blocking)
+    if (summary.errors > 0) {
+        console.log('');
+        console.log('\x1b[33m⚠️  Schema validation found issues:\x1b[0m');
+
+        for (const error of report.schemaErrors) {
+            const location = [error.operation, error.fieldPath].filter(Boolean).join(' → ');
+            console.log(`  \x1b[33m⚠\x1b[0m ${location}: ${error.invalidValue || ''} ${error.remediationHint || ''}`);
+        }
+
+        for (const error of report.crossCuttingErrors) {
+            const location = [error.operation, error.fieldPath].filter(Boolean).join(' → ');
+            console.log(`  \x1b[33m⚠\x1b[0m ${location}: ${error.remediationHint || ''}`);
+        }
+
+        console.log('');
+        console.log(`  ${summary.errors} issue(s) found. Run \x1b[36mdo/validate\x1b[0m before deployment.`);
+    }
+
+    return { skipped: false, report };
+}
+
+export default { runGenerationValidation };