locai 2.1.0

package/dist/core/pipeline/steps/ConfidenceCheckStep.js

@@ -0,0 +1,67 @@
+import PipelineStep from "../PipelineStep.js";
+import { log } from "../../../utils/logger.js";
+class ConfidenceCheckStep extends PipelineStep {
+    confidenceSettings;
+    debug;
+    constructor(confidenceSettings, debug = false) {
+        super();
+        this.confidenceSettings = confidenceSettings;
+        this.debug = debug;
+    }
+    async execute(context, next) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (!context.confidence || !this.confidenceSettings.enabled) {
+            await next();
+            return;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const confidence = context.confidence;
+        const result = context.result;
+        result.confidence = confidence;
+        // Auto-approve if above threshold
+        if (this.confidenceSettings.autoApproveThreshold !== undefined &&
+            confidence.score >= this.confidenceSettings.autoApproveThreshold) {
+            result.autoApproved = true;
+            if (this.confidenceSettings.autoApprovedCount !== undefined) {
+                this.confidenceSettings.autoApprovedCount++;
+            }
+            if (this.debug) {
+                log(`Auto-approved: ${context.key} (score: ${confidence.score.toFixed(3)})`, true);
+            }
+        }
+        // Auto-reject if below threshold
+        else if (this.confidenceSettings.rejectThreshold !== undefined &&
+            confidence.score < this.confidenceSettings.rejectThreshold) {
+            result.rejected = true;
+            result.rejectionReason = `Quality score too low: ${confidence.score.toFixed(3)}`;
+            if (this.confidenceSettings.rejectedCount !== undefined) {
+                this.confidenceSettings.rejectedCount++;
+            }
+            if (this.debug) {
+                log(`Auto-rejected: ${context.key} (score: ${confidence.score.toFixed(3)})`, true);
+            }
+            // Keep original text for rejected translations
+            result.translated = context.sourceText;
+        }
+        // Add to review queue if below review threshold
+        else if (this.confidenceSettings.saveReviewQueue &&
+            this.confidenceSettings.reviewThreshold !== undefined &&
+            confidence.score < this.confidenceSettings.reviewThreshold) {
+            result.needsReview = true;
+            if (this.confidenceSettings.reviewQueue) {
+                this.confidenceSettings.reviewQueue.push({
+                    key: context.key,
+                    source: context.sourceText,
+                    translation: context.translatedText,
+                    confidence,
+                    language: context.targetLang,
+                    sourceLang: context.options.source,
+                    category: context.meta?.category || "general",
+                    timestamp: new Date().toISOString(),
+                });
+            }
+        }
+        await next();
+    }
+}
+export default ConfidenceCheckStep;

package/dist/core/pipeline/steps/GlossaryPostStep.js

@@ -0,0 +1,17 @@
+import PipelineStep from "../PipelineStep.js";
+class GlossaryPostStep extends PipelineStep {
+    glossaryManager;
+    constructor(glossaryManager) {
+        super();
+        this.glossaryManager = glossaryManager;
+    }
+    async execute(context, next) {
+        if (!this.glossaryManager || !context.termMap || !context.translatedText) {
+            await next();
+            return;
+        }
+        context.translatedText = this.glossaryManager.restoreTerms(context.translatedText, context.termMap);
+        await next();
+    }
+}
+export default GlossaryPostStep;

package/dist/core/pipeline/steps/GlossaryPreStep.js

@@ -0,0 +1,20 @@
+import PipelineStep from "../PipelineStep.js";
+class GlossaryPreStep extends PipelineStep {
+    glossaryManager;
+    constructor(glossaryManager) {
+        super();
+        this.glossaryManager = glossaryManager;
+    }
+    async execute(context, next) {
+        if (!this.glossaryManager) {
+            context.protectedText = context.sourceText;
+            await next();
+            return;
+        }
+        const { protectedText, termMap } = this.glossaryManager.protectTerms(context.sourceText, context.sourceLang, context.targetLang);
+        context.protectedText = protectedText;
+        context.termMap = termMap;
+        await next();
+    }
+}
+export default GlossaryPreStep;

package/dist/core/pipeline/steps/InputValidationStep.js

@@ -0,0 +1,26 @@
+import PipelineStep from "../PipelineStep.js";
+class InputValidationStep extends PipelineStep {
+    maxKeyLength;
+    constructor(maxKeyLength = 10000) {
+        super();
+        this.maxKeyLength = maxKeyLength;
+    }
+    async execute(context, next) {
+        if (typeof context.sourceText !== "string") {
+            context.result.error = "Invalid input type: sourceText must be a string";
+            context.result.success = false;
+            // Stop pipeline, return error
+            return;
+        }
+        if (context.key.length > this.maxKeyLength) {
+            context.result.key = context.key.substring(0, 100) + "...";
+            context.result.translated = context.sourceText;
+            context.result.error = `Key exceeds maximum length of ${this.maxKeyLength} characters`;
+            context.result.success = false;
+            // Stop pipeline
+            return;
+        }
+        await next();
+    }
+}
+export default InputValidationStep;

package/dist/core/pipeline/steps/QualityCheckStep.js

@@ -0,0 +1,48 @@
+import PipelineStep from "../PipelineStep.js";
+import { FileManager } from "../../../utils/file-manager.js";
+class QualityCheckStep extends PipelineStep {
+    qualityChecker;
+    debug;
+    constructor(qualityChecker, debug = false) {
+        super();
+        this.qualityChecker = qualityChecker;
+        this.debug = debug;
+    }
+    async execute(context, next) {
+        if (!context.translatedText) {
+            await next();
+            return;
+        }
+        let translated = context.translatedText;
+        // 1. Quality Checks & Auto-fixing
+        if (this.qualityChecker && this.qualityChecker.rules?.enabled !== false) {
+            const qualityResult = this.qualityChecker.validateAndFix(context.sourceText, context.translatedText);
+            translated = qualityResult.fixedText;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            context.qualityResult = qualityResult;
+        }
+        // 2. JSON Validity Check
+        const jsonValidation = FileManager.validateTranslationValue(context.key, translated);
+        if (!jsonValidation.valid) {
+            if (this.debug) {
+                console.warn(`JSON validation warning for key "${context.key}": ${jsonValidation.error}`);
+            }
+            // Attempt simple quote fix if possible (logic moved from Orchestrator)
+            // Note: Since quoteBalanceChecker was inside Orchestrator, we might need to rely on QualityChecker if it has that logic.
+            // Assuming QualityChecker handles most, but Orchestrator had a specific extra check.
+            // For now, we trust QualityChecker which was passed in.
+        }
+        context.translatedText = translated;
+        // Populate the final result
+        context.result = {
+            key: context.key,
+            translated: context.translatedText,
+            context: context.meta,
+            success: true,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            qualityChecks: context.qualityResult,
+        };
+        await next();
+    }
+}
+export default QualityCheckStep;

package/dist/core/pipeline/steps/ToneCheckStep.js

@@ -0,0 +1,58 @@
+import PipelineStep from "../PipelineStep.js";
+import { ToneVerifier } from "../../../utils/quality/tone-verifier.js";
+export class ToneCheckStep extends PipelineStep {
+    verifier;
+    enabled;
+    debug;
+    constructor(config = {}) {
+        super();
+        this.verifier = new ToneVerifier();
+        this.enabled = config.enabled || false;
+        this.debug = config.debug || false;
+    }
+    async execute(context, next) {
+        // Only run if enabled and we have a translation
+        if (!this.enabled || !context.translatedText || !context.options?.styleGuide?.toneOfVoice) {
+            await next();
+            return;
+        }
+        try {
+            if (this.debug) {
+                console.log(`[ToneCheck] Verifying "${context.key}" against tone: ${context.options.styleGuide.toneOfVoice}`);
+            }
+            const styleGuide = context.options.styleGuide;
+            const provider = styleGuide.toneProvider;
+            const options = styleGuide.analysisOptions;
+            const result = await this.verifier.verify(context.sourceText, context.translatedText, context.sourceLang, context.targetLang, styleGuide.toneOfVoice, provider, options);
+            if (!result.passed) {
+                if (this.debug) {
+                    console.warn(`[ToneCheck] Failed: Score ${result.score}/10. Reason: ${result.reasoning}`);
+                }
+                // Mark in context that tone validation failed
+                // We can define a standard structure for quality warnings
+                const qualityResult = context.qualityResult || { issues: [] };
+                qualityResult.issues.push({
+                    type: "tone_mismatch",
+                    message: result.reasoning,
+                    severity: "warning",
+                    suggestion: result.suggestions,
+                    score: result.score,
+                });
+                context.qualityResult = qualityResult;
+                // Optionally, if we want to enforce REJECTION, we could clear translatedText
+                // For now, per plan, we are adding warnings/feedback loop potential.
+                // context.translatedText = null; // Uncomment to strict enforce
+            }
+            else {
+                if (this.debug) {
+                    console.log(`[ToneCheck] Passed: Score ${result.score}/10`);
+                }
+            }
+        }
+        catch (error) {
+            console.error("[ToneCheck] Error executing verification:", error);
+        }
+        await next();
+    }
+}
+export default ToneCheckStep;

package/dist/core/pipeline/steps/TranslationStep.js

@@ -0,0 +1,65 @@
+import PipelineStep from "../PipelineStep.js";
+import ProviderFactory from "../../provider-factory.js";
+class TranslationStep extends PipelineStep {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    options;
+    confidenceSettings;
+    constructor(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    options = {}, confidenceSettings = {}) {
+        super();
+        this.options = options;
+        this.confidenceSettings = confidenceSettings;
+    }
+    async execute(context, next) {
+        try {
+            const provider = this._getProvider();
+            // Setup translation options
+            const translationOpts = {
+                ...this.options,
+                detectedContext: {
+                    ...context.meta,
+                    existingTranslation: context.existingTranslation || null,
+                },
+            };
+            // Handling Confidence Scoring if enabled
+            if (this.confidenceSettings.enabled &&
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                typeof provider.extractTranslationWithConfidence === "function") {
+                const rawResponse = await provider.translate(context.protectedText || context.sourceText, context.sourceLang, context.targetLang, { ...translationOpts, returnRawResponse: true });
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const result = provider.extractTranslationWithConfidence(rawResponse, 
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                provider.name || "unknown", context.protectedText || context.sourceText, context.sourceLang, context.targetLang, context.meta?.category);
+                context.translatedText = result.translation;
+                context.confidence = result.confidence;
+            }
+            else {
+                // Standard translation
+                context.translatedText = await provider.translate(context.protectedText || context.sourceText, context.sourceLang, context.targetLang, translationOpts);
+                context.confidence = undefined; // Use undefined instead of null for optional typings often
+            }
+            // Continue to next steps (restore glossary, quality check, etc.)
+            await next();
+        }
+        catch (error) {
+            console.error(`Translation error - key "${context.key}":`, error);
+            context.result.error = error.message;
+            context.result.success = false;
+            context.result.translated = context.sourceText; // Fallback to source
+            // Stop pipeline or proceed?
+            // Usually if translation fails, we stop quality checks but we might want to return the error result.
+            // Since we set context.result, returning here is fine.
+            return;
+        }
+    }
+    _getProvider() {
+        const provider = ProviderFactory.getProvider(this.options.apiProvider, this.options.useFallback !== false, this.options);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (!provider || typeof provider.translate !== "function") {
+            throw new Error(`Translation provider not available or invalid: ${this.options.apiProvider}`);
+        }
+        return provider;
+    }
+}
+export default TranslationStep;

package/dist/core/pipeline/steps/VectorCacheReadStep.js

@@ -0,0 +1,84 @@
+import PipelineStep from "../PipelineStep.js";
+export class VectorCacheReadStep extends PipelineStep {
+    vectorStore;
+    embeddingProvider;
+    stats;
+    options;
+    constructor(vectorStore, embeddingProvider, stats, options = {}) {
+        super();
+        this.vectorStore = vectorStore;
+        this.embeddingProvider = embeddingProvider;
+        this.stats = stats;
+        this.options = options;
+    }
+    async execute(context, next) {
+        // Skip if disabled, or already has result (Exact Cache hit)
+        if (!this.options.enabled ||
+            context.result?.success ||
+            context.result?.fromCache ||
+            context.options?.skipCache) {
+            await next();
+            return;
+        }
+        try {
+            // Generate embedding for source text
+            // Optimization: If text is very short/garbage, maybe skip?
+            // For now, process everything reasonable.
+            const embedding = await this.embeddingProvider.getEmbedding(context.sourceText);
+            if (embedding.length === 0) {
+                await next();
+                return;
+            }
+            // Store embedding in context for Write step to reuse (save API call)
+            context.meta = context.meta || {};
+            context.meta.embedding = embedding;
+            const results = await this.vectorStore.search(embedding, context.targetLang, 1);
+            const bestMatch = results[0];
+            if (bestMatch) {
+                const similarity = bestMatch.score;
+                const exactThreshold = this.options.exactMatchThreshold || 0.98;
+                const contextThreshold = this.options.similarityThreshold || 0.85;
+                if (similarity >= exactThreshold) {
+                    // "Exact" Vector Match - Treat as cache hit
+                    this.stats.hits++;
+                    context.result = {
+                        key: context.key,
+                        translated: bestMatch.item.translation,
+                        success: true,
+                        fromCache: true, // From "Vector" cache
+                        context: {
+                            matchType: "vector-exact",
+                            similarity: similarity,
+                        },
+                        meta: {
+                            vectorMatch: true,
+                            similarity: similarity,
+                        },
+                    };
+                    // Short-circuit
+                    return;
+                }
+                else if (similarity >= contextThreshold) {
+                    // Context Match - Provide to LLM
+                    this.stats.contextUsed++;
+                    context.meta.similarTranslation = {
+                        source: bestMatch.item.text,
+                        target: bestMatch.item.translation,
+                        similarity: similarity,
+                    };
+                }
+                else {
+                    this.stats.misses++;
+                }
+            }
+            else {
+                this.stats.misses++;
+            }
+        }
+        catch (error) {
+            console.warn(`Vector cache read failed: ${error.message}`);
+            // Continue pipeline on error
+        }
+        await next();
+    }
+}

package/dist/core/pipeline/steps/VectorCacheWriteStep.js

@@ -0,0 +1,42 @@
+import PipelineStep from "../PipelineStep.js";
+export class VectorCacheWriteStep extends PipelineStep {
+    vectorStore;
+    embeddingProvider;
+    options;
+    constructor(vectorStore, embeddingProvider, options = {}) {
+        super();
+        this.vectorStore = vectorStore;
+        this.embeddingProvider = embeddingProvider;
+        this.options = options;
+    }
+    async execute(context, next) {
+        // Execute next steps first (which might be nothing as this is usually last)
+        await next();
+        // Check conditions to save:
+        // 1. Enabled
+        // 2. Translation successful
+        // 3. Not from cache (exact or vector)
+        if (!this.options.enabled ||
+            !context.result?.success ||
+            context.result?.fromCache ||
+            !context.translatedText) {
+            return;
+        }
+        try {
+            // Get embedding: reuse if generated in read step, else generate
+            let embedding = context.meta?.embedding;
+            if (!embedding) {
+                embedding = await this.embeddingProvider.getEmbedding(context.sourceText);
+            }
+            if (embedding && embedding.length > 0) {
+                await this.vectorStore.addItem(context.sourceText, context.translatedText, context.sourceLang, context.targetLang, embedding, {
+                    category: context.meta?.category,
+                    key: context.key,
+                });
+            }
+        }
+        catch (error) {
+            console.warn(`Vector cache write failed: ${error.message}`);
+        }
+    }
+}

package/dist/core/pipeline/steps/__tests__/ToneCheckStep.test.js

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ToneCheckStep } from "../ToneCheckStep.js";
+// Mock ToneVerifier
+vi.mock("../../../../utils/quality/tone-verifier.js", () => {
+    return {
+        ToneVerifier: class {
+            verify = vi.fn();
+        },
+    };
+});
+describe("ToneCheckStep", () => {
+    let step;
+    let mockContext;
+    let mockNext;
+    let mockVerifier;
+    beforeEach(() => {
+        // Reset mocks
+        vi.clearAllMocks();
+        step = new ToneCheckStep({ enabled: true });
+        mockContext = {
+            translatedText: "Sanal Makine",
+            sourceText: "Virtual Machine",
+            sourceLang: "en",
+            targetLang: "tr",
+            options: {
+                styleGuide: {
+                    toneOfVoice: "tech",
+                },
+            },
+            qualityResult: {
+                issues: [],
+            },
+        };
+        mockNext = vi.fn().mockResolvedValue(undefined);
+        // Get the mock instance
+        // @ts-ignore
+        mockVerifier = step.verifier;
+    });
+    it("should skip verification if disabled", async () => {
+        const disabledStep = new ToneCheckStep({ enabled: false });
+        await disabledStep.execute(mockContext, mockNext);
+        expect(mockVerifier.verify).not.toHaveBeenCalled();
+        expect(mockNext).toHaveBeenCalled();
+    });
+    it("should skip verification if no translated text", async () => {
+        mockContext.translatedText = "";
+        await step.execute(mockContext, mockNext);
+        expect(mockVerifier.verify).not.toHaveBeenCalled();
+        expect(mockNext).toHaveBeenCalled();
+    });
+    it("should skip verification if no tone defined", async () => {
+        mockContext.options.styleGuide.toneOfVoice = undefined;
+        await step.execute(mockContext, mockNext);
+        expect(mockVerifier.verify).not.toHaveBeenCalled();
+        expect(mockNext).toHaveBeenCalled();
+    });
+    it("should pass configured provider to verifier", async () => {
+        mockContext.options.styleGuide.toneProvider = "gemini";
+        mockVerifier.verify.mockResolvedValue({ passed: true, score: 10 });
+        await step.execute(mockContext, mockNext);
+        expect(mockVerifier.verify).toHaveBeenCalledWith(expect.any(String), expect.any(String), expect.any(String), expect.any(String), expect.any(String), "gemini", undefined);
+    });
+    it("should pass configured toneProvider and analysis options to verifier", async () => {
+        mockContext.options.styleGuide.toneProvider = "deepseek";
+        mockContext.options.styleGuide.analysisOptions = { temperature: 0.7 };
+        mockVerifier.verify.mockResolvedValue({ passed: true, score: 10 });
+        await step.execute(mockContext, mockNext);
+        expect(mockVerifier.verify).toHaveBeenCalledWith(expect.any(String), expect.any(String), expect.any(String), expect.any(String), expect.any(String), "deepseek", { temperature: 0.7 });
+    });
+    it("should verify and add warning on failure", async () => {
+        mockVerifier.verify.mockResolvedValue({
+            passed: false,
+            score: 5,
+            reasoning: "Too simple",
+        });
+        await step.execute(mockContext, mockNext);
+        expect(mockVerifier.verify).toHaveBeenCalledWith("Virtual Machine", "Sanal Makine", "en", "tr", "tech", undefined, // Default provider
+        undefined // Default options
+        );
+        expect(mockContext.qualityResult.issues.length).toBe(1);
+        expect(mockContext.qualityResult.issues[0].message).toContain("Too simple");
+        expect(mockNext).toHaveBeenCalled();
+    });
+    it("should not add warning on success", async () => {
+        mockVerifier.verify.mockResolvedValue({
+            passed: true,
+            score: 9,
+        });
+        await step.execute(mockContext, mockNext);
+        expect(mockContext.qualityResult.issues.length).toBe(0);
+        expect(mockNext).toHaveBeenCalled();
+    });
+    it("should handle verifier errors gracefully", async () => {
+        mockVerifier.verify.mockRejectedValue(new Error("Network error"));
+        const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        await step.execute(mockContext, mockNext);
+        expect(mockNext).toHaveBeenCalled();
+        consoleSpy.mockRestore();
+    });
+});

package/dist/core/provider-factory.js

@@ -0,0 +1,139 @@
+import * as deepseekProvider from "../providers/deepseek.js";
+import * as geminiProvider from "../providers/gemini.js";
+import * as openaiProvider from "../providers/openai.js";
+import * as dashscopeProvider from "../providers/dashscope.js";
+import * as xaiProvider from "../providers/xai.js";
+import FallbackProvider from "./fallback-provider.js";
+import rateLimiter from "../utils/rate-limiter.js";
+/**
+ * Factory for creating and managing AI providers.
+ * Handles provider instantiation, configuration, and fallback chains.
+ */
+class ProviderFactory {
+    /**
+     * Get provider instance with intelligent fallback support.
+     * @param {string} providerName - Name of the primary provider.
+     * @param {boolean} [useFallback=true] - Whether to use fallback chain on failure.
+     * @param {Object} [config=null] - Optional configuration overrides.
+     * @returns {AIProvider} - Provider instance or wrapped FallbackProvider.
+     * @throws {Error} If provider is not found or configured.
+     */
+    static getProvider(providerName, useFallback = true, config = null) {
+        const providers = {
+            dashscope: dashscopeProvider,
+            xai: xaiProvider,
+            openai: openaiProvider,
+            deepseek: deepseekProvider,
+            gemini: geminiProvider,
+        };
+        const normalizedProviderName = (providerName || "").toLowerCase();
+        if (!useFallback) {
+            const selected = providers[normalizedProviderName];
+            if (!selected) {
+                throw new Error(`Provider ${providerName} not found or not configured`);
+            }
+            if (!this.isProviderConfigured(normalizedProviderName)) {
+                throw new Error(`Provider ${providerName} is not configured. Missing API key.`);
+            }
+            const wrappedProvider = {
+                async translate(text, sourceLang, targetLang, options = {}) {
+                    const priority = text.length < 100 ? 1 : 0;
+                    return rateLimiter.enqueue(normalizedProviderName, () => selected.translate(text, sourceLang, targetLang, options), priority);
+                },
+            };
+            if (selected.analyze) {
+                wrappedProvider.analyze = (prompt, options = {}) => {
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                    return rateLimiter.enqueue(normalizedProviderName, () => selected.analyze(prompt, options));
+                };
+            }
+            if (selected.chat) {
+                wrappedProvider.chat = (messages, options = {}) => {
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                    return rateLimiter.enqueue(normalizedProviderName, () => selected.chat(messages, options));
+                };
+            }
+            return wrappedProvider;
+        }
+        const allProviders = [];
+        const availableProviderNames = this.getAvailableProviders();
+        if (normalizedProviderName &&
+            providers[normalizedProviderName] &&
+            availableProviderNames.includes(normalizedProviderName)) {
+            allProviders.push({
+                name: normalizedProviderName,
+                implementation: providers[normalizedProviderName],
+            });
+        }
+        else if (normalizedProviderName) {
+            console.warn(`Provider '${providerName}' not found or not configured, using default provider chain`);
+        }
+        let fallbackOrder = availableProviderNames;
+        if (config?.fallbackOrder && Array.isArray(config.fallbackOrder)) {
+            fallbackOrder = config.fallbackOrder
+                .filter((name) => availableProviderNames.includes(name.toLowerCase()))
+                .map((name) => name.toLowerCase());
+            const remainingProviders = availableProviderNames.filter((name) => !fallbackOrder.includes(name));
+            fallbackOrder = [...fallbackOrder, ...remainingProviders];
+        }
+        for (const name of fallbackOrder) {
+            if (!allProviders.some((p) => p.name === name) && providers[name]) {
+                allProviders.push({ name, implementation: providers[name] });
+            }
+        }
+        if (allProviders.length === 0) {
+            throw new Error("No valid providers found for fallback chain. Please check your API keys.");
+        }
+        if (process.env.DEBUG) {
+            const safeProviderNames = allProviders.map((p) => p.name // FallbackProvider logic expects name property on wrapped object? No, p is ProviderWrapper {name, implementation}
+            );
+            console.log(`Provider fallback chain: ${safeProviderNames.join(" → ")}`);
+        }
+        return new FallbackProvider(allProviders);
+    }
+    /**
+     * Get list of available (configured) providers.
+     * @returns {string[]} - Array of provider names with valid API keys.
+     */
+    static getAvailableProviders() {
+        const providers = {
+            dashscope: process.env.DASHSCOPE_API_KEY,
+            xai: process.env.XAI_API_KEY,
+            openai: process.env.OPENAI_API_KEY,
+            deepseek: process.env.DEEPSEEK_API_KEY,
+            gemini: process.env.GEMINI_API_KEY,
+        };
+        return Object.entries(providers)
+            .filter(([, key]) => !!key)
+            .map(([name]) => name);
+    }
+    /**
+     * Validate that at least one provider is configured.
+     * @returns {string[]} - Array of available providers.
+     * @throws {Error} If no providers are configured.
+     */
+    static validateProviders() {
+        const available = this.getAvailableProviders();
+        if (available.length === 0) {
+            throw new Error("No API providers configured. Please set at least one API key.");
+        }
+        return available;
+    }
+    /**
+     * Check if a specific provider is configured.
+     * @param {string} providerName - Name of the provider.
+     * @returns {boolean} - True if provider has an API key configured.
+     */
+    static isProviderConfigured(providerName) {
+        const envVarMap = {
+            dashscope: "DASHSCOPE_API_KEY",
+            xai: "XAI_API_KEY",
+            openai: "OPENAI_API_KEY",
+            deepseek: "DEEPSEEK_API_KEY",
+            gemini: "GEMINI_API_KEY",
+        };
+        const envKey = envVarMap[providerName.toLowerCase()];
+        return !!(envKey && process.env[envKey]);
+    }
+}
+export default ProviderFactory;