agentic-qe 3.7.21 → 3.8.0

package/dist/integrations/ruvector/filter-adapter.js

@@ -0,0 +1,285 @@
+/**
+ * Agentic QE v3 - RuVector Metadata Filtering Adapter
+ * Task 1.2: Metadata Filtering Layer (ruvector-filter)
+ *
+ * Provides composable filter expressions (AND/OR/NOT/FIELD) that can be
+ * applied to pattern search results for rich post-search filtering.
+ *
+ * TypeScript in-memory implementation (no native package exists).
+ * Backward compatible: no filter = no change to search results.
+ *
+ * @module integrations/ruvector/filter-adapter
+ */
+import { getRuVectorFeatureFlags } from './feature-flags.js';
+let nativeEngine = null;
+let nativeChecked = false;
+/**
+ * Check for native filter engine.
+ * No native package exists — always returns null.
+ * The TypeScript implementation is the production implementation.
+ */
+async function loadNativeEngine() {
+    if (nativeChecked)
+        return nativeEngine;
+    nativeChecked = true;
+    nativeEngine = null;
+    return null;
+}
+// ============================================================================
+// Filter Builder Helpers
+// ============================================================================
+/**
+ * Create an AND filter combining multiple sub-expressions
+ */
+export function and(...children) {
+    return { type: 'AND', children };
+}
+/**
+ * Create an OR filter combining multiple sub-expressions
+ */
+export function or(...children) {
+    return { type: 'OR', children };
+}
+/**
+ * Create a NOT filter inverting a sub-expression
+ */
+export function not(child) {
+    return { type: 'NOT', child };
+}
+/**
+ * Create a field-level filter expression
+ */
+export function field(fieldName, operator, value) {
+    return { type: 'FIELD', field: fieldName, operator, value };
+}
+// ============================================================================
+// TypeScript Fallback Filter Engine
+// ============================================================================
+/**
+ * Resolve a nested field path (e.g., "context.tags") on a PatternSearchResult.
+ * Looks first on the pattern object, then on the result itself.
+ */
+function resolveField(result, fieldPath) {
+    const pattern = result.pattern;
+    // Try pattern first, then result-level fields
+    const targets = [pattern, result];
+    for (const target of targets) {
+        const parts = fieldPath.split('.');
+        let current = target;
+        for (const part of parts) {
+            if (current === null || current === undefined)
+                break;
+            if (typeof current === 'object') {
+                current = current[part];
+            }
+            else {
+                current = undefined;
+                break;
+            }
+        }
+        if (current !== undefined)
+            return current;
+    }
+    return undefined;
+}
+/**
+ * Evaluate a single FIELD filter against a resolved value
+ */
+function evaluateFieldFilter(resolvedValue, operator, filterValue) {
+    switch (operator) {
+        case 'eq':
+            return resolvedValue === filterValue;
+        case 'gt':
+            return (typeof resolvedValue === 'number' &&
+                typeof filterValue === 'number' &&
+                resolvedValue > filterValue);
+        case 'lt':
+            return (typeof resolvedValue === 'number' &&
+                typeof filterValue === 'number' &&
+                resolvedValue < filterValue);
+        case 'gte':
+            return (typeof resolvedValue === 'number' &&
+                typeof filterValue === 'number' &&
+                resolvedValue >= filterValue);
+        case 'lte':
+            return (typeof resolvedValue === 'number' &&
+                typeof filterValue === 'number' &&
+                resolvedValue <= filterValue);
+        case 'in': {
+            if (!Array.isArray(filterValue))
+                return false;
+            return filterValue.includes(resolvedValue);
+        }
+        case 'contains': {
+            // Array.includes or string.includes
+            if (Array.isArray(resolvedValue)) {
+                return resolvedValue.includes(filterValue);
+            }
+            if (typeof resolvedValue === 'string' && typeof filterValue === 'string') {
+                return resolvedValue.includes(filterValue);
+            }
+            return false;
+        }
+        case 'between': {
+            if (typeof resolvedValue !== 'number' ||
+                !Array.isArray(filterValue) ||
+                filterValue.length !== 2) {
+                // Also support Date-based between
+                if (resolvedValue instanceof Date && Array.isArray(filterValue) && filterValue.length === 2) {
+                    const ts = resolvedValue.getTime();
+                    const lo = filterValue[0] instanceof Date ? filterValue[0].getTime() : Number(filterValue[0]);
+                    const hi = filterValue[1] instanceof Date ? filterValue[1].getTime() : Number(filterValue[1]);
+                    return ts >= lo && ts <= hi;
+                }
+                return false;
+            }
+            const [lo, hi] = filterValue;
+            return resolvedValue >= lo && resolvedValue <= hi;
+        }
+        default:
+            return false;
+    }
+}
+/**
+ * Evaluate a filter expression against a single search result.
+ * Returns true if the result passes the filter.
+ */
+export function evaluateFilter(result, filter) {
+    switch (filter.type) {
+        case 'AND': {
+            const children = filter.children ?? [];
+            return children.every((child) => evaluateFilter(result, child));
+        }
+        case 'OR': {
+            const children = filter.children ?? [];
+            if (children.length === 0)
+                return true;
+            return children.some((child) => evaluateFilter(result, child));
+        }
+        case 'NOT': {
+            if (!filter.child)
+                return true;
+            return !evaluateFilter(result, filter.child);
+        }
+        case 'FIELD': {
+            if (!filter.field || !filter.operator)
+                return true;
+            const resolved = resolveField(result, filter.field);
+            return evaluateFieldFilter(resolved, filter.operator, filter.value);
+        }
+        default:
+            return true;
+    }
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Apply a filter expression to pattern search results.
+ *
+ * If the `useMetadataFiltering` feature flag is disabled, returns results unchanged.
+ * If the native `ruvector-filter` engine is available, delegates to it.
+ * Otherwise, applies the TypeScript fallback engine.
+ *
+ * @param results - Pattern search results to filter
+ * @param filter - Composable filter expression
+ * @returns Filtered results (subset of input, order preserved)
+ */
+export async function applyFilter(results, filter) {
+    // No filter = passthrough
+    if (!filter)
+        return results;
+    // Check feature flag
+    const flags = getRuVectorFeatureFlags();
+    if (!flags.useMetadataFiltering)
+        return results;
+    // Try native engine first
+    const native = await loadNativeEngine();
+    if (native) {
+        return native.applyFilter(results, filter);
+    }
+    // TypeScript fallback: in-memory filtering
+    return applyFilterSync(results, filter);
+}
+/**
+ * Synchronous version of applyFilter using the TypeScript fallback engine.
+ * Useful when native engine availability is already known to be absent.
+ *
+ * @param results - Pattern search results to filter
+ * @param filter - Composable filter expression
+ * @returns Filtered results (subset of input, order preserved)
+ */
+export function applyFilterSync(results, filter) {
+    if (!filter)
+        return results;
+    return results.filter((result) => evaluateFilter(result, filter));
+}
+/**
+ * Validate a filter expression for structural correctness.
+ *
+ * @param filter - Filter expression to validate
+ * @returns Validation result with error messages
+ */
+export function validateFilter(filter) {
+    const errors = [];
+    if (!filter.type) {
+        errors.push('Filter must have a type');
+        return { valid: false, errors };
+    }
+    const validTypes = ['AND', 'OR', 'NOT', 'FIELD'];
+    if (!validTypes.includes(filter.type)) {
+        errors.push(`Invalid filter type: ${filter.type}. Must be one of: ${validTypes.join(', ')}`);
+    }
+    if (filter.type === 'AND' || filter.type === 'OR') {
+        if (!filter.children || !Array.isArray(filter.children)) {
+            errors.push(`${filter.type} filter must have a 'children' array`);
+        }
+        else {
+            for (let i = 0; i < filter.children.length; i++) {
+                const childResult = validateFilter(filter.children[i]);
+                if (!childResult.valid) {
+                    errors.push(...childResult.errors.map((e) => `${filter.type}.children[${i}]: ${e}`));
+                }
+            }
+        }
+    }
+    if (filter.type === 'NOT') {
+        if (!filter.child) {
+            errors.push("NOT filter must have a 'child' expression");
+        }
+        else {
+            const childResult = validateFilter(filter.child);
+            if (!childResult.valid) {
+                errors.push(...childResult.errors.map((e) => `NOT.child: ${e}`));
+            }
+        }
+    }
+    if (filter.type === 'FIELD') {
+        if (!filter.field) {
+            errors.push("FIELD filter must have a 'field' property");
+        }
+        if (!filter.operator) {
+            errors.push("FIELD filter must have an 'operator' property");
+        }
+        else {
+            const validOps = [
+                'eq', 'gt', 'lt', 'gte', 'lte', 'in', 'contains', 'between',
+            ];
+            if (!validOps.includes(filter.operator)) {
+                errors.push(`Invalid operator: ${filter.operator}. Must be one of: ${validOps.join(', ')}`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+// ============================================================================
+// Reset (for testing)
+// ============================================================================
+/**
+ * Reset native engine state (for testing only)
+ */
+export function resetNativeEngine() {
+    nativeEngine = null;
+    nativeChecked = false;
+}
+//# sourceMappingURL=filter-adapter.js.map

package/dist/integrations/ruvector/gnn-wrapper.d.ts

@@ -8,6 +8,7 @@
  * @module integrations/ruvector/gnn-wrapper
  */
 import type { IEmbedding, IHNSWConfig, EmbeddingNamespace, ISearchOptions } from '../embeddings/base/types';
+import type { DitheredResult, DitherOptions } from './dither-adapter.js';
 /** Check if native GNN module is available */
 export declare function isGNNAvailable(): boolean;
 /** CompressionLevelConfig type compatible with @ruvector/gnn */
@@ -239,6 +240,25 @@ export declare class TensorCompressionFactory {
      * Get compression level for frequency
      */
     static getLevel(accessFreq: number): QECompressionLevel;
+    /**
+     * Compress tensor with optional deterministic dithering (Task 1.4)
+     *
+     * When the `useDeterministicDither` feature flag is enabled, applies
+     * golden-ratio dithered quantization as a post-processing step before
+     * passing to the native compressor. This improves reconstruction quality
+     * at low bit depths while guaranteeing cross-platform reproducibility.
+     *
+     * When the flag is disabled, behaves identically to `compressWithLevel`.
+     *
+     * @param embedding - Raw embedding vector
+     * @param level - Compression level
+     * @param ditherOptions - Optional dither configuration (seed, bitDepth override)
+     * @returns Compressed data string, optionally with dither metadata
+     */
+    static compressWithDither(embedding: number[] | Float32Array, level: QECompressionLevel, ditherOptions?: Partial<DitherOptions>): {
+        compressed: string;
+        ditherResult?: DitheredResult;
+    };
 }
 export declare function getRuvectorLayer(): any;
 export declare function getTensorCompress(): any;

package/dist/integrations/ruvector/gnn-wrapper.js

@@ -8,6 +8,8 @@
  * @module integrations/ruvector/gnn-wrapper
  */
 import { safeJsonParse } from '../../shared/safe-json.js';
+import { isDeterministicDitherEnabled } from './feature-flags.js';
+import { applyDither } from './dither-adapter.js';
 // Lazy-load @ruvector/gnn native bindings (may not be available on all platforms)
 // Follows the pattern in kernel/unified-memory-hnsw.ts (lines 22-35)
 let _RuvectorLayer = null;
@@ -483,6 +485,44 @@ export class TensorCompressionFactory {
         requireGNN();
         return _getCompressionLevel(accessFreq);
     }
+    /**
+     * Compress tensor with optional deterministic dithering (Task 1.4)
+     *
+     * When the `useDeterministicDither` feature flag is enabled, applies
+     * golden-ratio dithered quantization as a post-processing step before
+     * passing to the native compressor. This improves reconstruction quality
+     * at low bit depths while guaranteeing cross-platform reproducibility.
+     *
+     * When the flag is disabled, behaves identically to `compressWithLevel`.
+     *
+     * @param embedding - Raw embedding vector
+     * @param level - Compression level
+     * @param ditherOptions - Optional dither configuration (seed, bitDepth override)
+     * @returns Compressed data string, optionally with dither metadata
+     */
+    static compressWithDither(embedding, level, ditherOptions) {
+        const embeddingFloat32 = embedding instanceof Float32Array
+            ? embedding
+            : new Float32Array(embedding);
+        // Apply dithering if feature flag is enabled
+        let ditherResult;
+        if (isDeterministicDitherEnabled()) {
+            // Map compression level to a default bit depth
+            const bitDepthMap = {
+                'none': 32,
+                'half': 16,
+                'pq8': 8,
+                'pq4': 4,
+                'binary': 1,
+            };
+            const bitDepth = ditherOptions?.bitDepth ?? bitDepthMap[level] ?? 8;
+            const seed = ditherOptions?.seed ?? 0;
+            ditherResult = applyDither(embeddingFloat32, bitDepth, seed);
+        }
+        // Compress using the standard path (native compressor)
+        const compressed = this.compressWithLevel(ditherResult ? ditherResult.dequantized : embedding, level);
+        return { compressed, ditherResult };
+    }
 }
 // ============================================================================
 // Re-exports from @ruvector/gnn for advanced users

package/dist/integrations/ruvector/hnsw-health-monitor.d.ts

@@ -0,0 +1,237 @@
+/**
+ * HNSW Health Monitor - Spectral Health Monitoring
+ *
+ * Monitors the structural health of HNSW indexes using spectral graph
+ * theory metrics. Computes Fiedler value (algebraic connectivity),
+ * spectral gap, effective resistance, and a combined coherence score.
+ *
+ * Uses TypeScript power iteration and sample-based estimation for
+ * spectral computation. No native package exists for this — the
+ * TypeScript implementation is the production implementation.
+ *
+ * @see Task 3.4: HNSW Health Monitoring
+ * @module integrations/ruvector/hnsw-health-monitor
+ */
+import type { IHnswIndexProvider } from '../../kernel/hnsw-index-provider.js';
+export { buildLaplacian, laplacianMultiply, vectorNorm, normalizeInPlace, deflateVector, approximateFiedlerValue, approximateSpectralGap, estimateEffectiveResistance, computeCoherenceScore, } from './spectral-math.js';
+/**
+ * Alert types generated when health metrics exceed thresholds.
+ */
+export type HealthAlertType = 'FragileIndex' | 'PoorExpansion' | 'HighResistance' | 'LowCoherence';
+/**
+ * A single health alert with context.
+ */
+export interface HealthAlert {
+    /** Alert classification */
+    readonly type: HealthAlertType;
+    /** Human-readable description */
+    readonly message: string;
+    /** The metric value that triggered the alert */
+    readonly value: number;
+    /** The threshold that was exceeded */
+    readonly threshold: number;
+    /** When the alert was generated */
+    readonly timestamp: Date;
+}
+/**
+ * Spectral health metrics for an HNSW index.
+ */
+export interface SpectralMetrics {
+    /** Second smallest eigenvalue of graph Laplacian (algebraic connectivity) */
+    readonly fiedlerValue: number;
+    /** Difference between 2nd and 1st eigenvalues (expansion quality) */
+    readonly spectralGap: number;
+    /** Average resistance distance between sampled node pairs */
+    readonly effectiveResistance: number;
+    /** Combined health metric (0-1, higher = healthier) */
+    readonly coherenceScore: number;
+}
+/**
+ * Full health report for an HNSW index.
+ */
+export interface HnswHealthReport {
+    /** Whether the index is considered healthy */
+    readonly healthy: boolean;
+    /** Spectral health metrics */
+    readonly metrics: SpectralMetrics;
+    /** Active alerts (empty if healthy) */
+    readonly alerts: HealthAlert[];
+    /** Number of vectors in the index */
+    readonly indexSize: number;
+    /** Whether native ruvector-coherence was used */
+    readonly usedNativeBackend: boolean;
+    /** Whether adjacency was built from actual search or circular approximation */
+    readonly adjacencySource: 'actual-search' | 'approximate';
+    /** Time taken for the health check in ms */
+    readonly checkDurationMs: number;
+    /** When the check was performed */
+    readonly checkedAt: Date;
+}
+/**
+ * A timestamped health metric point for history tracking.
+ */
+export interface HealthMetricPoint {
+    /** Coherence score at this point */
+    readonly coherenceScore: number;
+    /** Fiedler value at this point */
+    readonly fiedlerValue: number;
+    /** Index size at measurement time */
+    readonly indexSize: number;
+    /** Whether the index was healthy */
+    readonly healthy: boolean;
+    /** Timestamp of measurement */
+    readonly timestamp: Date;
+}
+/**
+ * Configuration for the HNSW health monitor.
+ */
+export interface HnswHealthMonitorConfig {
+    /** Fiedler value threshold for FragileIndex alert (default: 0.01) */
+    readonly fiedlerThreshold: number;
+    /** Spectral gap threshold for PoorExpansion alert (default: 0.1) */
+    readonly spectralGapThreshold: number;
+    /** Effective resistance threshold for HighResistance alert (default: 10.0) */
+    readonly resistanceThreshold: number;
+    /** Coherence score threshold for LowCoherence alert (default: 0.3) */
+    readonly coherenceThreshold: number;
+    /** Maximum iterations for power iteration (default: 100) */
+    readonly maxPowerIterations: number;
+    /** Convergence tolerance for power iteration (default: 1e-6) */
+    readonly convergenceTolerance: number;
+    /** Number of node pairs to sample for resistance estimation (default: 50) */
+    readonly resistanceSampleSize: number;
+    /** Maximum history entries to retain (default: 200) */
+    readonly maxHistoryEntries: number;
+    /** Minimum index size for meaningful spectral analysis (default: 3) */
+    readonly minIndexSize: number;
+}
+/**
+ * Default health monitor configuration.
+ */
+export declare const DEFAULT_HNSW_HEALTH_CONFIG: HnswHealthMonitorConfig;
+export declare const ALERT_THRESHOLDS: {
+    readonly FragileIndex: 0.01;
+    readonly PoorExpansion: 0.1;
+    readonly HighResistance: 10;
+    readonly LowCoherence: 0.3;
+};
+/** Reset native loader state (for testing) */
+export declare function _resetNativeLoader(): void;
+/**
+ * Result from building adjacency from an HNSW index.
+ */
+export interface AdjacencyResult {
+    /** Adjacency list for the graph */
+    adjacency: number[][];
+    /** Number of nodes in the graph */
+    nodeCount: number;
+    /** Whether adjacency was built from actual search or circular approximation */
+    adjacencySource: 'actual-search' | 'approximate';
+}
+/**
+ * Build an adjacency list from an HNSW-like index by using similarity
+ * between stored vectors. When stored vectors are provided, each vector
+ * is searched against the index to discover real neighbors. Otherwise,
+ * falls back to a circular approximation.
+ *
+ * @param index - The HNSW index provider
+ * @param maxNeighbors - Maximum neighbors per node to consider
+ * @param storedVectors - Optional map of id to vector for real neighbor discovery
+ * @returns Adjacency list, node count, and adjacency source
+ */
+export declare function buildAdjacencyFromIndex(index: IHnswIndexProvider, maxNeighbors?: number, storedVectors?: Map<number, Float32Array>): AdjacencyResult;
+/**
+ * HNSW Health Monitor
+ *
+ * Monitors the spectral health of HNSW indexes by computing graph-theoretic
+ * metrics. Uses ruvector-coherence for native computation when available,
+ * falling back to TypeScript approximations.
+ *
+ * Health checks are designed to be lightweight enough for periodic use
+ * without blocking search operations.
+ *
+ * @example
+ * ```typescript
+ * const monitor = new HnswHealthMonitor();
+ * const report = monitor.checkHealth(hnswIndex);
+ * if (!report.healthy) {
+ *   console.warn('HNSW index unhealthy:', report.alerts);
+ * }
+ * ```
+ */
+export declare class HnswHealthMonitor {
+    private readonly config;
+    private readonly alerts;
+    private readonly history;
+    private lastReport;
+    private useNative;
+    private nativeChecked;
+    constructor(config?: Partial<HnswHealthMonitorConfig>);
+    /**
+     * Perform a health check on an HNSW index.
+     *
+     * Computes spectral metrics and generates alerts if thresholds are
+     * exceeded. Results are recorded in the metrics history.
+     *
+     * @param index - The HNSW index to check
+     * @returns Health report with metrics and alerts
+     */
+    checkHealth(index: IHnswIndexProvider): HnswHealthReport;
+    /**
+     * Get current active alerts.
+     *
+     * @returns Array of active health alerts
+     */
+    getAlerts(): HealthAlert[];
+    /**
+     * Get health metrics history.
+     *
+     * @param limit - Maximum entries to return (most recent)
+     * @returns Array of metric points, most recent last
+     */
+    getMetricsHistory(limit?: number): HealthMetricPoint[];
+    /**
+     * Check whether the index is currently healthy (no alerts).
+     *
+     * If no health check has been performed yet, returns true (optimistic).
+     *
+     * @returns true if the last health check found no alerts
+     */
+    isHealthy(): boolean;
+    /**
+     * Get the last health report, or null if no check has been performed.
+     */
+    getLastReport(): HnswHealthReport | null;
+    /**
+     * Clear all history and alerts.
+     */
+    clearHistory(): void;
+    /**
+     * Compute metrics using the native ruvector-coherence module.
+     */
+    private computeNativeMetrics;
+    /**
+     * Compute metrics using TypeScript approximations.
+     */
+    private computeApproximateMetrics;
+    /**
+     * Generate alerts based on metric thresholds.
+     */
+    private generateAlerts;
+    /**
+     * Create a report for indexes too small for spectral analysis.
+     */
+    private createSmallIndexReport;
+    /**
+     * Add a history point, trimming if over limit.
+     */
+    private addHistoryPoint;
+}
+/**
+ * Create an HnswHealthMonitor instance.
+ *
+ * @param config - Optional configuration overrides
+ * @returns A new HnswHealthMonitor
+ */
+export declare function createHnswHealthMonitor(config?: Partial<HnswHealthMonitorConfig>): HnswHealthMonitor;
+//# sourceMappingURL=hnsw-health-monitor.d.ts.map