tjbot-ce 3.0.1

package/dist/utils/logging.js

@@ -0,0 +1,113 @@
+/**
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import winston from 'winston';
+import { fileURLToPath } from 'url';
+export var LogEmoji;
+(function (LogEmoji) {
+    LogEmoji["CAMERA"] = "\uD83D\uDCF7";
+    LogEmoji["COLOR"] = "\uD83C\uDFA8";
+    LogEmoji["CONFIG"] = "\u2699\uFE0F";
+    LogEmoji["GENERAL"] = "\uD83E\uDD16";
+    LogEmoji["HARDWARE"] = "\uD83D\uDD27";
+    LogEmoji["LED"] = "\uD83D\uDCA1";
+    LogEmoji["MIC"] = "\uD83C\uDFA4";
+    LogEmoji["MODEL"] = "\uD83D\uDCE6";
+    LogEmoji["RPI"] = "\uD83C\uDF53";
+    LogEmoji["SERVO"] = "\uD83E\uDDBE";
+    LogEmoji["SPEAKER"] = "\uD83D\uDD08";
+    LogEmoji["STT"] = "\uD83E\uDDBB";
+    LogEmoji["TTS"] = "\uD83D\uDCAC";
+    LogEmoji["VISION"] = "\uD83D\uDC41\uFE0F";
+})(LogEmoji || (LogEmoji = {}));
+let winstonInitialized = false;
+const LOGGER_NAME_EMOJI_RULES = [
+    ['/camera/', LogEmoji.CAMERA],
+    ['/config/', LogEmoji.CONFIG],
+    ['/led/', LogEmoji.LED],
+    ['/microphone/', LogEmoji.MIC],
+    ['/rpi-drivers/', LogEmoji.RPI],
+    ['/servo/', LogEmoji.SERVO],
+    ['/speaker/', LogEmoji.SPEAKER],
+    ['/stt/', LogEmoji.STT],
+    ['/tts/', LogEmoji.TTS],
+    ['/vision/', LogEmoji.VISION],
+    ['model-registry', LogEmoji.MODEL],
+    ['colors', LogEmoji.COLOR],
+];
+function normalizeModuleName(moduleName) {
+    if (!moduleName) {
+        return '';
+    }
+    const lower = moduleName.toLowerCase();
+    if (!lower.startsWith('file://')) {
+        return lower;
+    }
+    try {
+        return fileURLToPath(moduleName).toLowerCase();
+    }
+    catch {
+        return lower;
+    }
+}
+function emojiForModuleName(moduleName) {
+    const normalized = normalizeModuleName(moduleName);
+    for (const [pattern, emoji] of LOGGER_NAME_EMOJI_RULES) {
+        if (normalized.includes(pattern)) {
+            return emoji;
+        }
+    }
+    return LogEmoji.GENERAL;
+}
+const prettyErrorFormat = winston.format.printf(((info) => {
+    const emoji = emojiForModuleName(typeof info.moduleName === 'string' ? info.moduleName : undefined);
+    let message = `${info.level}: ${emoji} ${info.message}`;
+    const metadata = { ...info };
+    delete metadata.level;
+    delete metadata.message;
+    delete metadata.moduleName;
+    delete metadata[Symbol.for('level')];
+    delete metadata[Symbol.for('message')];
+    delete metadata[Symbol.for('splat')];
+    if (Object.keys(metadata).length > 0) {
+        const jsonString = JSON.stringify(metadata, null, 2);
+        message += ' \x1b[36m' + jsonString + '\x1b[0m';
+    }
+    return message;
+}));
+/**
+ * Initialize Winston with TJBot's default formatter.
+ * Safe to call repeatedly; only the first call configures transports/format.
+ * Later calls only update log level.
+ */
+export function initWinston(level = 'info') {
+    if (!winstonInitialized) {
+        winston.configure({
+            level,
+            format: winston.format.combine(winston.format.colorize(), prettyErrorFormat),
+            transports: [new winston.transports.Console()],
+        });
+        winstonInitialized = true;
+        return;
+    }
+    winston.level = level;
+}
+/**
+ * Get a module-scoped logger that lets the formatter infer a category emoji.
+ */
+export function getLogger(moduleName) {
+    return winston.child({ moduleName });
+}
+//# sourceMappingURL=logging.js.map

package/dist/utils/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../src/utils/logging.ts"],"names":[],"mappings":"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"}

package/dist/utils/model-registry.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Types of models managed by ModelManager
+ * Includes base types (stt, tts, vad) and vision subtypes
+ */
+export type ModelType = 'stt' | 'tts' | 'vad' | 'vision.object-recognition' | 'vision.classification' | 'vision.face-detection' | 'vision.image-description';
+/**
+ * Base model metadata
+ */
+export interface BaseModelMetadata {
+    type: ModelType;
+    key: string;
+    label: string;
+    url: string;
+    folder: string;
+    required: string[];
+}
+/**
+ * STT model metadata
+ */
+export interface STTModelMetadata extends BaseModelMetadata {
+    kind: 'offline' | 'offline-whisper' | 'streaming-zipformer' | 'streaming';
+}
+/**
+ * TTS model metadata
+ */
+export interface TTSModelMetadata extends BaseModelMetadata {
+    kind: 'vits-piper' | 'tacotron' | 'fastpitch' | 'streaming';
+}
+/**
+ * VAD model metadata
+ */
+export type VADModelMetadata = BaseModelMetadata;
+/**
+ * Vision model metadata
+ */
+export interface VisionModelMetadata extends BaseModelMetadata {
+    kind: 'detection' | 'classification' | 'face-detection' | 'image-description';
+    labelUrl?: string;
+    inputShape?: number[];
+}
+/**
+ * Unified singleton registry for all TJBot models (STT, TTS, VAD, Vision)
+ * Handles model metadata, registration, downloading, extraction, and caching
+ */
+export declare class ModelRegistry {
+    private static instance?;
+    private registeredModels;
+    private metadataLoaded;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): ModelRegistry;
+    /**
+     * Load model metadata from unified YAML file
+     * If no path provided, uses default model-registry.yaml in config directory
+     * @private
+     */
+    private loadMetadata;
+    /**
+     * Get model cache directory
+     */
+    getModelCacheDir(): string;
+    /**
+     * Get model cache directory for a specific type
+     * @param modelType The model type (stt, tts, vad, vision.*)
+     * @returns The cache directory path for the specified model type
+     */
+    getModelCacheDirForType(modelType: ModelType | 'vision'): string;
+    /**
+     * Register a model in the registry
+     * @param model The model metadata to register
+     */
+    registerModel(model: BaseModelMetadata): void;
+    /**
+     * Lookup model metadata by key
+     * @param modelKey The model key
+     * @returns The model metadata
+     * @throws Error if model not found
+     */
+    lookupModel<T extends BaseModelMetadata = BaseModelMetadata>(modelKey: string): T;
+    /**
+     * Lookup model metadata by type & installation status
+     * @param modelType The model type
+     * @param installedOnly If true, only return models that are downloaded
+     * @returns List of model metadata of the specified type
+     */
+    lookupModels<T extends BaseModelMetadata = BaseModelMetadata>(modelType?: ModelType, installedOnly?: boolean): T[];
+    /**
+     * Ensure a model is downloaded and return its path
+     * @param modelKey The model key
+     * @returns The model metadata
+     * @throws TJBotError if model not found or download fails
+     */
+    loadModel<T extends BaseModelMetadata = BaseModelMetadata>(modelKey: string): Promise<T>;
+    /**
+     * Check if a model is downloaded in the specified cache directory
+     * @param modelKey The model key
+     * @returns True if the model is downloaded, false otherwise
+     */
+    isModelDownloaded(modelKey: string): boolean;
+    /**
+     * Copy a file from local filesystem
+     * Supports file:// URLs
+     */
+    private copyFile;
+    /**
+     * Download a file from URL with progress bar and exponential backoff retry
+     * Retries up to 3 times with delays: 1s, 2s, 4s
+     * Supports both http/https URLs and file:// URLs
+     */
+    private downloadFile;
+    /**
+     * Extract tar.bz2 archive using system tar command
+     */
+    private extractTarBz2;
+    /**
+     * Download and extract a model
+     * @param modelKey The model key
+     * @throws Error if download or extraction fails
+     */
+    downloadModel(modelKey: string): Promise<{
+        primaryPath: string;
+        cachePath: string;
+    } | undefined>;
+}
+//# sourceMappingURL=model-registry.d.ts.map

package/dist/utils/model-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-registry.d.ts","sourceRoot":"","sources":["../../src/utils/model-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkBH;;;GAGG;AACH,MAAM,MAAM,SAAS,GACf,KAAK,GACL,KAAK,GACL,KAAK,GACL,2BAA2B,GAC3B,uBAAuB,GACvB,uBAAuB,GACvB,0BAA0B,CAAC;AAEjC;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACvD,IAAI,EAAE,SAAS,GAAG,iBAAiB,GAAG,qBAAqB,GAAG,WAAW,CAAC;CAC7E;AAED;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACvD,IAAI,EAAE,YAAY,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CAAC;CAC/D;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC1D,IAAI,EAAE,WAAW,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AASD;;;GAGG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAgB;IACxC,OAAO,CAAC,gBAAgB,CAA6C;IACrE,OAAO,CAAC,cAAc,CAAS;IAE/B,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,aAAa;IAOnC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAiDpB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;;;OAIG;IACH,uBAAuB,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM;IAUhE;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAK7C;;;;;OAKG;IACH,WAAW,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC;IAQjF;;;;;OAKG;IACH,YAAY,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,EACxD,SAAS,CAAC,EAAE,SAAS,EACrB,aAAa,GAAE,OAAe,GAC/B,CAAC,EAAE;IAcN;;;;;OAKG;IACG,SAAS,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAiB9F;;;;OAIG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAa5C;;;OAGG;YACW,QAAQ;IAoEtB;;;;OAIG;YACW,YAAY;IAyF1B;;OAEG;YACW,aAAa;IAM3B;;;;OAIG;IACG,aAAa,CAAC,QAAQ,EAAE,MAAM;;;;CAoDvC"}

package/dist/utils/model-registry.js

@@ -0,0 +1,391 @@
+/**
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { execFile } from 'child_process';
+import cliProgress from 'cli-progress';
+import fs from 'fs';
+import yaml from 'js-yaml';
+import os from 'os';
+import path from 'path';
+import { Readable } from 'stream';
+import { fileURLToPath } from 'url';
+import { promisify } from 'util';
+import { TJBotError } from './errors.js';
+import { getLogger } from './logging.js';
+const logger = getLogger(import.meta.url);
+const execFileAsync = promisify(execFile);
+/**
+ * Unified singleton registry for all TJBot models (STT, TTS, VAD, Vision)
+ * Handles model metadata, registration, downloading, extraction, and caching
+ */
+export class ModelRegistry {
+    static instance;
+    registeredModels = new Map();
+    metadataLoaded = false;
+    constructor() {
+        this.loadMetadata();
+    }
+    /**
+     * Get singleton instance
+     */
+    static getInstance() {
+        if (!this.instance) {
+            this.instance = new ModelRegistry();
+        }
+        return this.instance;
+    }
+    /**
+     * Load model metadata from unified YAML file
+     * If no path provided, uses default model-registry.yaml in config directory
+     * @private
+     */
+    loadMetadata(yamlPath) {
+        if (this.metadataLoaded) {
+            logger.debug('loadMetadata() called but model metadata already loaded');
+            return;
+        }
+        try {
+            // Default to model-registry.yaml in config directory
+            if (!yamlPath) {
+                const __filename = fileURLToPath(import.meta.url);
+                const __dirname = path.dirname(__filename);
+                yamlPath = path.join(__dirname, '..', 'config', 'vendor', 'model-registry.yaml');
+            }
+            logger.verbose(`Loading model metadata from: ${yamlPath}`);
+            const fileContents = fs.readFileSync(yamlPath, 'utf8');
+            const data = yaml.load(fileContents);
+            const models = (data.models || []).map((m) => {
+                const key = m.key;
+                if (!key) {
+                    throw new TJBotError('Model entry missing key');
+                }
+                return {
+                    ...m,
+                    key,
+                    folder: m.folder ?? key,
+                    required: m.required ?? [],
+                };
+            });
+            // Register all loaded models
+            for (const model of models) {
+                this.registerModel(model);
+            }
+            this.metadataLoaded = true;
+            logger.info(`Loaded metadata for ${this.registeredModels.size} ML models`);
+        }
+        catch (error) {
+            logger.error('Failed to load ML model metadata:', error);
+            throw new TJBotError('Failed to load ML model metadata', { cause: error });
+        }
+    }
+    // ============================================================================
+    // Cache Directory Paths
+    // ============================================================================
+    /**
+     * Get model cache directory
+     */
+    getModelCacheDir() {
+        return path.join(os.homedir(), '.tjbot', 'models');
+    }
+    /**
+     * Get model cache directory for a specific type
+     * @param modelType The model type (stt, tts, vad, vision.*)
+     * @returns The cache directory path for the specified model type
+     */
+    getModelCacheDirForType(modelType) {
+        // For vision subtypes, use 'vision' as the base directory
+        const cacheSubdir = modelType.startsWith('vision.') ? 'vision' : modelType;
+        return path.join(this.getModelCacheDir(), cacheSubdir);
+    }
+    // ============================================================================
+    // Query Methods
+    // ============================================================================
+    /**
+     * Register a model in the registry
+     * @param model The model metadata to register
+     */
+    registerModel(model) {
+        this.registeredModels.set(model.key, model);
+        logger.debug(`registered model: ${model.key} (type: ${model.type})`);
+    }
+    /**
+     * Lookup model metadata by key
+     * @param modelKey The model key
+     * @returns The model metadata
+     * @throws Error if model not found
+     */
+    lookupModel(modelKey) {
+        const model = this.registeredModels.get(modelKey);
+        if (!model) {
+            throw new TJBotError(`Model with key "${modelKey}" not found in registry`);
+        }
+        return model;
+    }
+    /**
+     * Lookup model metadata by type & installation status
+     * @param modelType The model type
+     * @param installedOnly If true, only return models that are downloaded
+     * @returns List of model metadata of the specified type
+     */
+    lookupModels(modelType, installedOnly = false) {
+        let models;
+        if (installedOnly) {
+            models = Array.from(this.registeredModels.values()).filter((m) => (modelType === undefined || m.type === modelType) && this.isModelDownloaded(m.key));
+        }
+        else {
+            models = Array.from(this.registeredModels.values()).filter((m) => modelType === undefined || m.type === modelType);
+        }
+        return models;
+    }
+    /**
+     * Ensure a model is downloaded and return its path
+     * @param modelKey The model key
+     * @returns The model metadata
+     * @throws TJBotError if model not found or download fails
+     */
+    async loadModel(modelKey) {
+        // Verify model exists in metadata
+        const model = this.lookupModel(modelKey);
+        // Download model if not already present
+        if (!this.isModelDownloaded(modelKey)) {
+            await this.downloadModel(modelKey);
+        }
+        // Return the model metadata
+        return model;
+    }
+    // ============================================================================
+    // Download/Extract Models
+    // ============================================================================
+    /**
+     * Check if a model is downloaded in the specified cache directory
+     * @param modelKey The model key
+     * @returns True if the model is downloaded, false otherwise
+     */
+    isModelDownloaded(modelKey) {
+        const model = this.lookupModel(modelKey);
+        const cacheDir = this.getModelCacheDirForType(model.type);
+        const modelPath = path.join(cacheDir, model.folder);
+        if (!fs.existsSync(modelPath)) {
+            return false;
+        }
+        // Check all required files exist
+        return model.required.every((file) => fs.existsSync(path.join(modelPath, file)));
+    }
+    /**
+     * Copy a file from local filesystem
+     * Supports file:// URLs
+     */
+    async copyFile(sourceUrl, destination) {
+        try {
+            // Convert file:// URL to path
+            const sourcePath = sourceUrl.startsWith('file://') ? new URL(sourceUrl).pathname : sourceUrl;
+            logger.debug(`copying file from ${sourcePath} to ${destination}`);
+            // Get file size for progress bar
+            const stats = await fs.promises.stat(sourcePath);
+            const totalSize = stats.size;
+            let copiedSize = 0;
+            // Create progress bar
+            const progressBar = new cliProgress.SingleBar({
+                format: 'Copying [{bar}] {percentage}% | {value}/{total} MB',
+                barCompleteChar: '\u2588',
+                barIncompleteChar: '\u2591',
+                hideCursor: true,
+            });
+            if (totalSize > 0) {
+                progressBar.start(Math.round(totalSize / 1024 / 1024), 0);
+            }
+            // Create destination directory
+            await fs.promises.mkdir(path.dirname(destination), { recursive: true });
+            // Copy file with progress tracking
+            const reader = fs.createReadStream(sourcePath);
+            const writer = fs.createWriteStream(destination);
+            await new Promise((resolve, reject) => {
+                reader.on('data', (chunk) => {
+                    copiedSize += chunk.length;
+                    if (totalSize > 0) {
+                        progressBar.update(Math.round(copiedSize / 1024 / 1024));
+                    }
+                });
+                reader.pipe(writer);
+                writer.on('finish', () => {
+                    if (totalSize > 0) {
+                        progressBar.stop();
+                    }
+                    logger.debug('file copy complete');
+                    resolve();
+                });
+                writer.on('error', (err) => {
+                    if (totalSize > 0) {
+                        progressBar.stop();
+                    }
+                    reject(err);
+                });
+                reader.on('error', (err) => {
+                    if (totalSize > 0) {
+                        progressBar.stop();
+                    }
+                    reject(err);
+                });
+            });
+        }
+        catch (err) {
+            logger.error('File copy failed:', err);
+            throw new TJBotError(`Failed to copy file from ${sourceUrl}`, {
+                cause: err,
+            });
+        }
+    }
+    /**
+     * Download a file from URL with progress bar and exponential backoff retry
+     * Retries up to 3 times with delays: 1s, 2s, 4s
+     * Supports both http/https URLs and file:// URLs
+     */
+    async downloadFile(url, destination, maxRetries = 3) {
+        // Handle file:// URLs (local files)
+        if (url.startsWith('file://')) {
+            return this.copyFile(url, destination);
+        }
+        let attempt = 0;
+        let lastError = null;
+        while (attempt < maxRetries) {
+            try {
+                if (attempt > 0) {
+                    const delay = Math.pow(2, attempt - 1) * 1000; // 1s, 2s, 4s
+                    logger.info(`Retrying download in ${delay / 1000}s... (attempt ${attempt + 1}/${maxRetries})`);
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+                logger.info(`Downloading from ${url} (attempt ${attempt + 1}/${maxRetries})`);
+                const response = await fetch(url);
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+                }
+                const totalSize = parseInt(response.headers.get('content-length') ?? '0', 10);
+                let downloadedSize = 0;
+                // Create progress bar
+                const progressBar = new cliProgress.SingleBar({
+                    format: 'Downloading [{bar}] {percentage}% | {value}/{total} MB',
+                    barCompleteChar: '\u2588',
+                    barIncompleteChar: '\u2591',
+                    hideCursor: true,
+                });
+                if (totalSize > 0) {
+                    progressBar.start(Math.round(totalSize / 1024 / 1024), 0);
+                }
+                await fs.promises.mkdir(path.dirname(destination), { recursive: true });
+                const writer = fs.createWriteStream(destination);
+                const nodeStream = Readable.from(response.body);
+                await new Promise((resolve, reject) => {
+                    nodeStream.on('data', (chunk) => {
+                        downloadedSize += chunk.length;
+                        if (totalSize > 0) {
+                            progressBar.update(Math.round(downloadedSize / 1024 / 1024));
+                        }
+                    });
+                    nodeStream.pipe(writer);
+                    writer.on('finish', () => {
+                        if (totalSize > 0) {
+                            progressBar.stop();
+                        }
+                        logger.info('Download complete');
+                        resolve();
+                    });
+                    writer.on('error', (err) => {
+                        if (totalSize > 0) {
+                            progressBar.stop();
+                        }
+                        reject(err);
+                    });
+                    nodeStream.on('error', (err) => {
+                        if (totalSize > 0) {
+                            progressBar.stop();
+                        }
+                        reject(err);
+                    });
+                });
+                // Success!
+                return;
+            }
+            catch (err) {
+                lastError = err;
+                logger.warn(`Download failed (attempt ${attempt + 1}/${maxRetries}):`, err);
+                attempt++;
+            }
+        }
+        // All retries exhausted
+        logger.error(`Download failed after ${maxRetries} attempts`);
+        throw new TJBotError(`Failed to download file after ${maxRetries} attempts`, {
+            cause: lastError || new Error('Unknown error'),
+        });
+    }
+    /**
+     * Extract tar.bz2 archive using system tar command
+     */
+    async extractTarBz2(archivePath, destinationDir) {
+        logger.info('Extracting archive...');
+        await execFileAsync('tar', ['-xjf', archivePath, '-C', destinationDir]);
+        logger.info('Extraction complete');
+    }
+    /**
+     * Download and extract a model
+     * @param modelKey The model key
+     * @throws Error if download or extraction fails
+     */
+    async downloadModel(modelKey) {
+        const model = this.lookupModel(modelKey);
+        const cacheDir = this.getModelCacheDirForType(model.type);
+        const modelPath = path.join(cacheDir, model.folder);
+        if (this.isModelDownloaded(modelKey)) {
+            return { primaryPath: path.join(modelPath, model.required[0]), cachePath: modelPath };
+        }
+        // Ensure cache directory exists
+        await fs.promises.mkdir(cacheDir, { recursive: true });
+        // Download to temporary file
+        const tempArchivePath = path.join(os.tmpdir(), `${model.key}-download`);
+        await this.downloadFile(model.url, tempArchivePath);
+        // Check if we need to extract based on file extension
+        const isTarBz2 = model.url.endsWith('.tar.bz2');
+        if (isTarBz2) {
+            // Extract tar.bz2 archive
+            await this.extractTarBz2(tempArchivePath, cacheDir);
+            // Remove temporary archive file
+            fs.unlinkSync(tempArchivePath);
+        }
+        else {
+            // Single file model - move directly to model path
+            await fs.promises.mkdir(modelPath, { recursive: true });
+            const fileName = path.basename(model.url).split('?')[0]; // Remove query params
+            const targetPath = path.join(modelPath, fileName);
+            // Use copy + unlink instead of rename to handle cross-filesystem moves (EXDEV error)
+            await fs.promises.copyFile(tempArchivePath, targetPath);
+            await fs.promises.unlink(tempArchivePath);
+        }
+        // Download labels file for vision models
+        if (typeof model.type === 'string' && model.type.startsWith('vision.')) {
+            const visionModel = model;
+            if (visionModel.labelUrl) {
+                const labelsFileName = path.basename(visionModel.labelUrl).split('?')[0]; // Extract filename, remove query params
+                const labelsFilePath = path.join(modelPath, labelsFileName);
+                await this.downloadFile(visionModel.labelUrl, labelsFilePath);
+            }
+        }
+        // Verify all required files exist
+        if (!this.isModelDownloaded(modelKey)) {
+            throw new TJBotError(`Model "${modelKey}" download incomplete: required files missing`);
+        }
+        logger.info(`Model "${modelKey}" downloaded and extracted to ${modelPath}`);
+        return;
+    }
+}
+//# sourceMappingURL=model-registry.js.map