agent-nuvira 1.14.0

package/dist/learning/self-improver.js

@@ -0,0 +1,161 @@
+/**
+ * SelfImprover — The self-improvement loop that ties together scoring,
+ * agent performance tracking, pattern extraction, and model optimization.
+ *
+ * After each orchestration run (when `useMemory: true`), the SelfImprover:
+ * 1. Scores the trajectory (how well did we do?)
+ * 2. Records per-agent stats (which agents/models succeed/fail?)
+ * 3. Periodically extracts patterns from high-scoring trajectories
+ * 4. Provides optimization recommendations (best models per agent)
+ *
+ * The SelfImprover is called by the Orchestrator post-execution hook.
+ * Users can also interact with it via the `buff learn` CLI commands.
+ */
+import { getTrajectoryStore } from '../memory/trajectory-store.js';
+import { getPatternStore } from './pattern-extractor.js';
+import { getAgentStats } from './agent-stats.js';
+import { scoreOrchestrationResult } from './scorer.js';
+import { logger } from '../utils/logger.js';
+// ─── Constants ──────────────────────────────────────────────────────────────
+/** How many successful runs before auto-extracting patterns */
+const PATTERN_EXTRACTION_INTERVAL = 5;
+/** How many trajectories to pass for pattern extraction */
+const TRAJECTORIES_FOR_EXTRACTION = 3;
+/** Minimum score to consider a trajectory as "good" */
+const GOOD_SCORE_THRESHOLD = 0.6;
+// ─── SelfImprover ───────────────────────────────────────────────────────────
+export class SelfImprover {
+    runCountSinceLastExtraction = 0;
+    /**
+     * Process a completed orchestration run through the self-improvement loop.
+     * Scores the result, tracks agent stats, and conditionally extracts patterns.
+     *
+     * @param result       The completed orchestration result
+     * @param callLLM      LLM function for pattern extraction
+     * @param agentModels  The model map used for this run (for tracking model perf)
+     * @param verbose      Whether to log details
+     */
+    async processRun(result, callLLM, agentModels, verbose = false) {
+        // Step 1: Score the trajectory
+        const score = scoreOrchestrationResult(result);
+        if (verbose) {
+            logger.info(`   Self-improvement: trajectory score = ${(score * 100).toFixed(0)}%`);
+        }
+        // Step 2: Record per-agent stats
+        const stats = getAgentStats();
+        stats.recordRuns(result.agentResults, agentModels);
+        // Step 3: Conditionally extract patterns from good trajectories
+        if (score >= GOOD_SCORE_THRESHOLD) {
+            this.runCountSinceLastExtraction++;
+            if (this.runCountSinceLastExtraction >= PATTERN_EXTRACTION_INTERVAL) {
+                this.runCountSinceLastExtraction = 0;
+                if (verbose) {
+                    logger.info('   Extracting coding patterns from successful trajectories...');
+                }
+                await this.extractPatterns(callLLM, verbose);
+            }
+        }
+    }
+    /**
+     * Force pattern extraction from the best trajectories in the store.
+     */
+    async extractPatterns(callLLM, verbose = false) {
+        try {
+            const store = getTrajectoryStore();
+            const allTrajectories = store.getAll();
+            // Get the highest-scoring trajectories
+            const best = allTrajectories
+                .filter((t) => t.score !== undefined)
+                .sort((a, b) => (b.score || 0) - (a.score || 0))
+                .slice(0, TRAJECTORIES_FOR_EXTRACTION);
+            if (best.length < 2) {
+                if (verbose) {
+                    logger.info('   Not enough scored trajectories for pattern extraction');
+                }
+                return 0;
+            }
+            const patternStore = getPatternStore();
+            const count = await patternStore.extractFromTrajectories(best, callLLM);
+            if (verbose && count > 0) {
+                logger.success(`   Extracted ${count} new pattern(s) from ${best.length} trajectories`);
+            }
+            return count;
+        }
+        catch (err) {
+            if (verbose) {
+                logger.debug(`Pattern extraction failed: ${err}`);
+            }
+            return 0;
+        }
+    }
+    /**
+     * Get optimization recommendations based on collected stats.
+     * Returns a recommended model map for the Orchestrator.
+     */
+    getOptimizedModelMap() {
+        const stats = getAgentStats();
+        const allAgents = stats.getAllAgents();
+        const modelMap = {};
+        for (const agentType of Object.keys(allAgents)) {
+            const bestModel = stats.getBestModel(agentType);
+            if (bestModel) {
+                modelMap[agentType] = bestModel;
+            }
+        }
+        return modelMap;
+    }
+    /**
+     * Get a human-readable summary of the self-improvement status.
+     */
+    getStatus() {
+        const stats = getAgentStats();
+        const patternStore = getPatternStore();
+        const patterns = patternStore.getAll();
+        const store = getTrajectoryStore();
+        const allTrajectories = store.getAll();
+        const lines = [
+            '🔄 Self-Improvement Status',
+            '',
+            '── Trajectories ──',
+            `   Total stored: ${allTrajectories.length}`,
+            `   Scored: ${allTrajectories.filter((t) => t.score !== undefined).length}`,
+            `   Avg score: ${this.averageScore(allTrajectories)}`,
+            '',
+            '── Patterns ──',
+            `   Total patterns: ${patterns.length}`,
+            `   Domains covered: ${[...new Set(patterns.flatMap((p) => p.applicableDomains))].join(', ') || 'none'}`,
+            '',
+            `── Performance ──`,
+            `   Total runs tracked: ${stats.getRaw().totalRuns}`,
+            `   Agents tracked: ${Object.keys(stats.getAllAgents()).length}`,
+        ];
+        lines.push('');
+        lines.push(stats.formatStats());
+        lines.push('');
+        lines.push(stats.formatModelRecommendations());
+        return lines.join('\n');
+    }
+    /**
+     * Reset extraction counter (called when user manually extracts patterns).
+     */
+    resetExtractionCounter() {
+        this.runCountSinceLastExtraction = 0;
+    }
+    // ── Private ────────────────────────────────────────────────────────────
+    averageScore(trajectories) {
+        const scored = trajectories.filter((t) => t.score !== undefined);
+        if (scored.length === 0)
+            return 'N/A';
+        const avg = scored.reduce((sum, t) => sum + (t.score || 0), 0) / scored.length;
+        return `${(avg * 100).toFixed(0)}%`;
+    }
+}
+// Singleton
+let improverInstance = null;
+export function getSelfImprover() {
+    if (!improverInstance) {
+        improverInstance = new SelfImprover();
+    }
+    return improverInstance;
+}
+//# sourceMappingURL=self-improver.js.map

package/dist/learning/self-improver.js.map

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

package/dist/memory/embedder.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Embedder — Generates vector embeddings from text using a tiered approach.
+ *
+ * Embedding Tier Strategy:
+ *   Tier 1: @huggingface/transformers (fast, local, 384-dim) — DEFAULT
+ *   Tier 2: Python sentence-transformers via subprocess
+ *   Tier 3: LLM-based (any configured InferenceProvider) — FALLBACK
+ *
+ * The embedder auto-selects the best available tier, caches results to avoid
+ * redundant computation, and gracefully degrades when tiers are unavailable.
+ *
+ * Dimensionality: 384 (all-MiniLM-L6-v2 default) — 6x more expressive than
+ * the previous 64-dim LLM-based embeddings while being 10x faster and free.
+ */
+import type { LLMCallFn } from '../agents/agent.js';
+/** Dimensionality of the generated embeddings (all-MiniLM-L6-v2 default) */
+export declare const EMBEDDING_DIM = 384;
+/**
+ * Generate a vector embedding for the given text.
+ *
+ * Uses a tiered approach:
+ *   1. @huggingface/transformers (fast local embeddings) — preferred
+ *   2. Python sentence-transformers via subprocess
+ *   3. LLM-based embedding (requires callLLM function) — fallback
+ *
+ * @param text          The text to embed (e.g., a user goal or task description)
+ * @param callLLM       Optional LLM call function (only needed for Tier 3 fallback)
+ * @param forceLLM      If true, skip native tiers and use LLM directly (useful for testing)
+ * @returns             A promise that resolves to a number[] embedding vector (384-dim)
+ */
+export declare function embed(text: string, callLLM?: LLMCallFn, forceLLM?: boolean): Promise<number[]>;
+/**
+ * Reset the tier availability cache.
+ * Call this when the environment changes (e.g., user installs a package)
+ * or in test setup to force re-detection.
+ */
+export declare function resetEmbeddingTierCache(): void;
+/**
+ * Set the force-LLM mode for testing.
+ * When called with force=true, all native embedding tiers are disabled
+ * and only the LLM-based fallback (Tier 3) is used.
+ */
+export declare function setForceLLM(force: boolean): void;
+/**
+ * Check if @huggingface/transformers is available.
+ * This is a lightweight check that doesn't load the model.
+ */
+export declare function isXenovaAvailable(): Promise<boolean>;
+/**
+ * Check if Python sentence-transformers is available.
+ */
+export declare function isPythonAvailable(): Promise<boolean>;
+/**
+ * Get the name of the currently active embedding tier.
+ */
+export declare function getActiveEmbeddingTier(): Promise<string>;
+/**
+ * Clear the in-memory embedding cache.
+ */
+export declare function clearEmbeddingCache(): void;
+/**
+ * Get the current size of the embedding cache.
+ */
+export declare function embeddingCacheSize(): number;
+//# sourceMappingURL=embedder.d.ts.map

package/dist/memory/embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.d.ts","sourceRoot":"","sources":["../../src/memory/embedder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAKpD,4EAA4E;AAC5E,eAAO,MAAM,aAAa,MAAM,CAAC;AAyEjC;;;;;;;;;;;;GAYG;AACH,wBAAsB,KAAK,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,SAAS,EACnB,QAAQ,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CAiDnB;AAyND;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAQhD;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAY1D;AAED;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAmB1D;AAED;;GAEG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC,CAI9D;AAID;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}

package/dist/memory/embedder.js

@@ -0,0 +1,424 @@
+/**
+ * Embedder — Generates vector embeddings from text using a tiered approach.
+ *
+ * Embedding Tier Strategy:
+ *   Tier 1: @huggingface/transformers (fast, local, 384-dim) — DEFAULT
+ *   Tier 2: Python sentence-transformers via subprocess
+ *   Tier 3: LLM-based (any configured InferenceProvider) — FALLBACK
+ *
+ * The embedder auto-selects the best available tier, caches results to avoid
+ * redundant computation, and gracefully degrades when tiers are unavailable.
+ *
+ * Dimensionality: 384 (all-MiniLM-L6-v2 default) — 6x more expressive than
+ * the previous 64-dim LLM-based embeddings while being 10x faster and free.
+ */
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { logger } from '../utils/logger.js';
+// ─── Constants ──────────────────────────────────────────────────────────────
+/** Dimensionality of the generated embeddings (all-MiniLM-L6-v2 default) */
+export const EMBEDDING_DIM = 384;
+/** Max text length for embedding (characters) */
+const MAX_EMBEDDING_TEXT_LENGTH = 2000;
+/** Default model for @huggingface/transformers */
+const XENOVA_MODEL = 'Xenova/all-MiniLM-L6-v2';
+/** LLM-based embedding system prompt (Tier 3 fallback) */
+const EMBEDDING_PROMPT = `You are a semantic embedding generator. Given a piece of text, generate a dense vector representation that captures its semantic meaning.
+
+Return ONLY a valid JSON array of ${EMBEDDING_DIM} floating-point numbers between -1 and 1.
+No markdown, no explanations, no code blocks — just the raw JSON array.
+
+The vector should encode:
+- The main topic and domain (e.g., "authentication", "database", "CLI tool")
+- The action being requested (e.g., "add", "fix", "refactor", "create")
+- The technology stack or language if mentioned
+- Key entities and concepts
+
+Example output: [${Array(5).fill('0.0').join(', ')}, ...]`;
+// ─── Tier Availability Cache ────────────────────────────────────────────────
+let _xenovaAvailable = null;
+let _pythonAvailable = null;
+// ─── In-Memory Cache ────────────────────────────────────────────────────────
+class EmbeddingCache {
+    cache = new Map();
+    maxSize;
+    constructor(maxSize = 200) {
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const value = this.cache.get(key);
+        if (value !== undefined) {
+            this.cache.delete(key);
+            this.cache.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(key, value);
+    }
+    get size() {
+        return this.cache.size;
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+const cache = new EmbeddingCache();
+// ─── Embedder ───────────────────────────────────────────────────────────────
+function cacheKey(text) {
+    return createHash('md5').update(text.toLowerCase().trim()).digest('hex');
+}
+/**
+ * Generate a vector embedding for the given text.
+ *
+ * Uses a tiered approach:
+ *   1. @huggingface/transformers (fast local embeddings) — preferred
+ *   2. Python sentence-transformers via subprocess
+ *   3. LLM-based embedding (requires callLLM function) — fallback
+ *
+ * @param text          The text to embed (e.g., a user goal or task description)
+ * @param callLLM       Optional LLM call function (only needed for Tier 3 fallback)
+ * @param forceLLM      If true, skip native tiers and use LLM directly (useful for testing)
+ * @returns             A promise that resolves to a number[] embedding vector (384-dim)
+ */
+export async function embed(text, callLLM, forceLLM) {
+    const key = cacheKey(text);
+    // Check cache first
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const truncatedText = text.slice(0, MAX_EMBEDDING_TEXT_LENGTH);
+    // When forceLLM is true, skip native tiers and go directly to LLM
+    // This is useful in test environments where mock LLMs are used
+    if (!forceLLM) {
+        // Tier 1: @huggingface/transformers (fast, local, free)
+        try {
+            const vector = await embedWithXenova(truncatedText);
+            if (vector) {
+                cache.set(key, vector);
+                return vector;
+            }
+        }
+        catch (err) {
+            logger.debug(`Tier 1 embedding (Xenova) failed: ${err}`);
+        }
+        // Tier 2: Python sentence-transformers via subprocess
+        try {
+            const vector = await embedWithPython(truncatedText);
+            if (vector) {
+                cache.set(key, vector);
+                return vector;
+            }
+        }
+        catch (err) {
+            logger.debug(`Tier 2 embedding (Python) failed: ${err}`);
+        }
+    }
+    // Tier 3: LLM-based embedding (requires callLLM)
+    if (callLLM) {
+        try {
+            const vector = await embedWithLLM(truncatedText, callLLM);
+            cache.set(key, vector);
+            return vector;
+        }
+        catch (err) {
+            logger.debug(`Tier 3 embedding (LLM) failed: ${err}`);
+        }
+    }
+    // All tiers failed — return zero vector (no meaningful matches)
+    logger.debug('All embedding tiers failed, returning zero vector');
+    return new Array(EMBEDDING_DIM).fill(0);
+}
+// ─── Tier 1: @huggingface/transformers ──────────────────────────────────────
+/**
+ * Generate embedding using @huggingface/transformers (Xenova).
+ * This is the fastest and most reliable tier — runs locally with ONNX runtime.
+ * Returns null if the library is not installed or model fails to load.
+ */
+async function embedWithXenova(text) {
+    if (_xenovaAvailable === false)
+        return null;
+    try {
+        // Dynamic import — the package is optional (user may not have it installed)
+        const { pipeline } = await import('@huggingface/transformers');
+        // Use 'feature-extraction' pipeline with all-MiniLM-L6-v2
+        // This model produces 384-dimensional embeddings
+        const extractor = await pipeline('feature-extraction', XENOVA_MODEL);
+        const output = await extractor(text, {
+            pooling: 'mean',
+            normalize: true,
+        });
+        // Convert Tensor to plain JS array
+        const arr = output.tolist();
+        const vector = arr[0];
+        if (!vector || !Array.isArray(vector) || vector.length !== EMBEDDING_DIM) {
+            logger.debug(`Xenova embedding returned unexpected shape: ${vector?.length}`);
+            return null;
+        }
+        _xenovaAvailable = true;
+        return vector;
+    }
+    catch (err) {
+        _xenovaAvailable = false;
+        const msg = err instanceof Error ? err.message : String(err);
+        // Provide helpful messages for common issues
+        if (msg.includes('Cannot find package') || msg.includes('Cannot find module')) {
+            logger.debug('@huggingface/transformers not installed. Install with: npm install @huggingface/transformers');
+        }
+        else if (msg.includes('download')) {
+            logger.debug('Xenova model download failed. Will use fallback embedding.');
+        }
+        else {
+            logger.debug(`Xenova embedding error: ${msg}`);
+        }
+        return null;
+    }
+}
+// ─── Tier 2: Python sentence-transformers ───────────────────────────────────
+/**
+ * Generate embedding using Python's sentence-transformers via subprocess.
+ * Second fallback — slower than Xenova but doesn't require npm package.
+ * Returns null if Python or sentence-transformers is not available.
+ */
+async function embedWithPython(text) {
+    if (_pythonAvailable === false)
+        return null;
+    // Escape the text for safe embedding in Python script
+    const escapedText = text
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r');
+    const pythonScript = `
+import sys, json
+try:
+    from sentence_transformers import SentenceTransformer
+    model = SentenceTransformer('all-MiniLM-L6-v2')
+    embedding = model.encode('${escapedText}').tolist()
+    # Ensure 384 dimensions
+    while len(embedding) < ${EMBEDDING_DIM}:
+        embedding.append(0.0)
+    embedding = embedding[:${EMBEDDING_DIM}]
+    print(json.dumps({"embedding": embedding}))
+except ImportError:
+    print(json.dumps({"error": "sentence-transformers not installed. Run: pip install sentence-transformers"}))
+    sys.exit(1)
+except Exception as e:
+    print(json.dumps({"error": str(e)}))
+    sys.exit(1)
+`;
+    return new Promise((resolve) => {
+        const python = spawn('python3', ['-c', pythonScript], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 30000, // 30 second timeout
+        });
+        let output = '';
+        let errorOutput = '';
+        python.stdout?.on('data', (chunk) => {
+            output += chunk.toString();
+        });
+        python.stderr?.on('data', (chunk) => {
+            errorOutput += chunk.toString();
+        });
+        python.on('error', (err) => {
+            _pythonAvailable = false;
+            if (err.code === 'ENOENT') {
+                logger.debug('Python 3 not found. Install sentence-transformers with: pip install sentence-transformers');
+            }
+            else {
+                logger.debug(`Python subprocess error: ${err.message}`);
+            }
+            resolve(null);
+        });
+        python.on('close', (exitCode) => {
+            if (exitCode === 0) {
+                try {
+                    const parsed = JSON.parse(output);
+                    if (parsed.error) {
+                        logger.debug(`Python embedding error: ${parsed.error}`);
+                        _pythonAvailable = false;
+                        resolve(null);
+                    }
+                    else if (Array.isArray(parsed.embedding) && parsed.embedding.length === EMBEDDING_DIM) {
+                        _pythonAvailable = true;
+                        resolve(parsed.embedding);
+                    }
+                    else {
+                        resolve(null);
+                    }
+                }
+                catch {
+                    resolve(null);
+                }
+            }
+            else {
+                _pythonAvailable = false;
+                if (errorOutput)
+                    logger.debug(`Python embedding stderr: ${errorOutput.slice(0, 200)}`);
+                resolve(null);
+            }
+        });
+    });
+}
+// ─── Tier 3: LLM-based embedding ────────────────────────────────────────────
+/**
+ * Generate embedding using an LLM via the InferenceProvider.
+ * This is the slowest and most expensive tier — fallback only.
+ * Requires a callLLM function (provided by the Orchestrator).
+ */
+async function embedWithLLM(text, callLLM) {
+    const prompt = `${EMBEDDING_PROMPT}\n\nText to embed:\n${text}`;
+    const response = await callLLM(prompt, {
+        temperature: 0.1,
+        maxTokens: 2048,
+    });
+    const vector = parseLLMEmbedding(response);
+    return vector;
+}
+/**
+ * Parse an embedding vector from the LLM's text response.
+ * Tries multiple strategies to extract a valid array of numbers.
+ */
+function parseLLMEmbedding(response) {
+    const trimmed = response.trim();
+    // Strategy 1: Direct JSON parse
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (isValidEmbedding(parsed))
+            return parsed;
+    }
+    catch {
+        // Fall through
+    }
+    // Strategy 2: Extract from ```json code block
+    const jsonMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (jsonMatch) {
+        try {
+            const parsed = JSON.parse(jsonMatch[1].trim());
+            if (isValidEmbedding(parsed))
+                return parsed;
+        }
+        catch {
+            // Fall through
+        }
+    }
+    // Strategy 3: Find array pattern in text
+    const arrayMatch = trimmed.match(/\[[\s\S]*?\]/);
+    if (arrayMatch) {
+        try {
+            const parsed = JSON.parse(arrayMatch[0]);
+            if (isValidEmbedding(parsed))
+                return parsed;
+        }
+        catch {
+            // Fall through
+        }
+    }
+    // Fallback: return zero vector (no meaningful match)
+    logger.debug('Could not parse embedding from LLM response, using zero vector');
+    return new Array(EMBEDDING_DIM).fill(0);
+}
+/**
+ * Validate that a parsed value is a valid embedding vector.
+ */
+function isValidEmbedding(value) {
+    if (!Array.isArray(value))
+        return false;
+    if (value.length !== EMBEDDING_DIM)
+        return false;
+    return value.every((v) => typeof v === 'number' && isFinite(v));
+}
+// ─── Detection Helpers ──────────────────────────────────────────────────────
+/**
+ * Reset the tier availability cache.
+ * Call this when the environment changes (e.g., user installs a package)
+ * or in test setup to force re-detection.
+ */
+export function resetEmbeddingTierCache() {
+    _xenovaAvailable = null;
+    _pythonAvailable = null;
+}
+/**
+ * Set the force-LLM mode for testing.
+ * When called with force=true, all native embedding tiers are disabled
+ * and only the LLM-based fallback (Tier 3) is used.
+ */
+export function setForceLLM(force) {
+    if (force) {
+        _xenovaAvailable = false;
+        _pythonAvailable = false;
+    }
+    else {
+        _xenovaAvailable = null;
+        _pythonAvailable = null;
+    }
+}
+/**
+ * Check if @huggingface/transformers is available.
+ * This is a lightweight check that doesn't load the model.
+ */
+export async function isXenovaAvailable() {
+    if (_xenovaAvailable !== null)
+        return _xenovaAvailable;
+    try {
+        // Try to resolve the package without loading it
+        await import('@huggingface/transformers');
+        _xenovaAvailable = true;
+        return true;
+    }
+    catch {
+        _xenovaAvailable = false;
+        return false;
+    }
+}
+/**
+ * Check if Python sentence-transformers is available.
+ */
+export async function isPythonAvailable() {
+    if (_pythonAvailable !== null)
+        return _pythonAvailable;
+    return new Promise((resolve) => {
+        const python = spawn('python3', ['-c', 'from sentence_transformers import SentenceTransformer; print("ok")'], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 10000,
+        });
+        python.on('close', (code) => {
+            _pythonAvailable = code === 0;
+            resolve(code === 0);
+        });
+        python.on('error', () => {
+            _pythonAvailable = false;
+            resolve(false);
+        });
+    });
+}
+/**
+ * Get the name of the currently active embedding tier.
+ */
+export async function getActiveEmbeddingTier() {
+    if (await isXenovaAvailable())
+        return 'local (Xenova, 384-dim)';
+    if (await isPythonAvailable())
+        return 'python (sentence-transformers, 384-dim)';
+    return 'llm (fallback, 384-dim)';
+}
+// ─── Cache Management ───────────────────────────────────────────────────────
+/**
+ * Clear the in-memory embedding cache.
+ */
+export function clearEmbeddingCache() {
+    cache.clear();
+}
+/**
+ * Get the current size of the embedding cache.
+ */
+export function embeddingCacheSize() {
+    return cache.size;
+}
+//# sourceMappingURL=embedder.js.map