@ninebix/nmt-system 1.0.0

package/dist/cli/utils/validators.js

@@ -0,0 +1,351 @@
+/**
+ * CLI Input Validation Utilities
+ *
+ * Provides schema-based validation for CLI command arguments.
+ * Ensures type safety and provides clear error messages.
+ *
+ * @module cli/utils/validators
+ */
+// ==================== Built-in Validators ====================
+/**
+ * UUID format validator
+ */
+export const isValidUUID = (value, fieldName) => {
+    if (typeof value !== 'string') {
+        return { valid: false, error: `${fieldName} must be a string` };
+    }
+    // Accept standard UUID or short ID format (e.g., attr_abc123)
+    const uuidPattern = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+    const shortIdPattern = /^[a-zA-Z0-9_-]{3,50}$/;
+    if (uuidPattern.test(value) || shortIdPattern.test(value)) {
+        return { valid: true, value };
+    }
+    return { valid: false, error: `${fieldName} must be a valid ID` };
+};
+/**
+ * Neuron ID validator (more permissive than UUID)
+ */
+export const isValidNeuronId = (value, fieldName) => {
+    if (typeof value !== 'string') {
+        return { valid: false, error: `${fieldName} must be a string` };
+    }
+    if (value.length < 1 || value.length > 100) {
+        return { valid: false, error: `${fieldName} must be 1-100 characters` };
+    }
+    // Allow alphanumeric, underscores, hyphens
+    if (!/^[a-zA-Z0-9_-]+$/.test(value)) {
+        return { valid: false, error: `${fieldName} contains invalid characters` };
+    }
+    return { valid: true, value };
+};
+/**
+ * Numeric range validator factory
+ */
+export function numberInRange(min, max) {
+    return (value, fieldName) => {
+        const num = typeof value === 'string' ? parseFloat(value) : value;
+        if (typeof num !== 'number' || isNaN(num)) {
+            return { valid: false, error: `${fieldName} must be a number` };
+        }
+        if (num < min || num > max) {
+            return { valid: false, error: `${fieldName} must be between ${min} and ${max}` };
+        }
+        return { valid: true, value: num };
+    };
+}
+/**
+ * Probability validator (0-1)
+ */
+export const isValidProbability = numberInRange(0, 1);
+/**
+ * Strength validator (0-1)
+ */
+export const isValidStrength = numberInRange(0, 1);
+/**
+ * Priority validator (1-10)
+ */
+export const isValidPriority = numberInRange(1, 10);
+/**
+ * Positive integer validator
+ */
+export const isPositiveInt = (value, fieldName) => {
+    const num = typeof value === 'string' ? parseInt(value, 10) : value;
+    if (typeof num !== 'number' || isNaN(num)) {
+        return { valid: false, error: `${fieldName} must be a number` };
+    }
+    if (!Number.isInteger(num) || num < 1) {
+        return { valid: false, error: `${fieldName} must be a positive integer` };
+    }
+    return { valid: true, value: num };
+};
+/**
+ * Non-empty string validator
+ */
+export const isNonEmptyString = (value, fieldName) => {
+    if (typeof value !== 'string') {
+        return { valid: false, error: `${fieldName} must be a string` };
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return { valid: false, error: `${fieldName} cannot be empty` };
+    }
+    return { valid: true, value: trimmed };
+};
+/**
+ * ISO8601 date validator
+ */
+export const isValidDate = (value, fieldName) => {
+    if (typeof value !== 'string') {
+        return { valid: false, error: `${fieldName} must be a string` };
+    }
+    const date = new Date(value);
+    if (isNaN(date.getTime())) {
+        return { valid: false, error: `${fieldName} must be a valid date (ISO8601)` };
+    }
+    return { valid: true, value: date.toISOString() };
+};
+// ==================== Schema Validation ====================
+/**
+ * Validate a single field against its schema
+ */
+function validateField(value, fieldName, schema) {
+    // Handle missing values
+    if (value === undefined || value === null || value === '') {
+        if (schema.required) {
+            return { valid: false, error: `${fieldName} is required` };
+        }
+        if (schema.default !== undefined) {
+            return { valid: true, value: schema.default };
+        }
+        return { valid: true, value: undefined };
+    }
+    // Custom validator takes precedence
+    if (schema.validator) {
+        return schema.validator(value, fieldName);
+    }
+    // Type-based validation
+    switch (schema.type) {
+        case 'string': {
+            if (typeof value !== 'string') {
+                return { valid: false, error: `${fieldName} must be a string` };
+            }
+            if (schema.minLength && value.length < schema.minLength) {
+                return { valid: false, error: `${fieldName} must be at least ${schema.minLength} characters` };
+            }
+            if (schema.maxLength && value.length > schema.maxLength) {
+                return { valid: false, error: `${fieldName} must be at most ${schema.maxLength} characters` };
+            }
+            if (schema.pattern && !schema.pattern.test(value)) {
+                return { valid: false, error: `${fieldName} has invalid format` };
+            }
+            if (schema.enum && !schema.enum.includes(value)) {
+                return { valid: false, error: `${fieldName} must be one of: ${schema.enum.join(', ')}` };
+            }
+            return { valid: true, value };
+        }
+        case 'number': {
+            const num = typeof value === 'string' ? parseFloat(value) : value;
+            if (typeof num !== 'number' || isNaN(num)) {
+                return { valid: false, error: `${fieldName} must be a number` };
+            }
+            if (schema.min !== undefined && num < schema.min) {
+                return { valid: false, error: `${fieldName} must be at least ${schema.min}` };
+            }
+            if (schema.max !== undefined && num > schema.max) {
+                return { valid: false, error: `${fieldName} must be at most ${schema.max}` };
+            }
+            return { valid: true, value: num };
+        }
+        case 'boolean': {
+            if (typeof value === 'boolean') {
+                return { valid: true, value };
+            }
+            if (value === 'true' || value === '1') {
+                return { valid: true, value: true };
+            }
+            if (value === 'false' || value === '0') {
+                return { valid: true, value: false };
+            }
+            return { valid: false, error: `${fieldName} must be a boolean` };
+        }
+        case 'uuid': {
+            return isValidUUID(value, fieldName);
+        }
+        case 'array': {
+            if (!Array.isArray(value)) {
+                return { valid: false, error: `${fieldName} must be an array` };
+            }
+            if (schema.minLength && value.length < schema.minLength) {
+                return { valid: false, error: `${fieldName} must have at least ${schema.minLength} items` };
+            }
+            if (schema.maxLength && value.length > schema.maxLength) {
+                return { valid: false, error: `${fieldName} must have at most ${schema.maxLength} items` };
+            }
+            return { valid: true, value };
+        }
+        default:
+            return { valid: true, value };
+    }
+}
+/**
+ * Validate an object against a schema
+ *
+ * @param data - Object to validate
+ * @param schema - Schema to validate against
+ * @returns Validation result with errors or validated data
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   neuronId: { type: 'uuid', required: true },
+ *   strength: { type: 'number', min: 0, max: 1, default: 0.5 },
+ *   name: { type: 'string', minLength: 1, maxLength: 100 }
+ * };
+ *
+ * const result = validateSchema({ neuronId: 'abc123', strength: '0.8' }, schema);
+ * if (result.valid) {
+ *   console.log(result.data); // { neuronId: 'abc123', strength: 0.8 }
+ * } else {
+ *   console.log(result.errors);
+ * }
+ * ```
+ */
+export function validateSchema(data, schema) {
+    const errors = [];
+    const validatedData = {};
+    for (const [fieldName, fieldSchema] of Object.entries(schema)) {
+        const result = validateField(data[fieldName], fieldName, fieldSchema);
+        if (!result.valid) {
+            errors.push({
+                field: fieldName,
+                message: result.error || `Invalid ${fieldName}`,
+                value: data[fieldName]
+            });
+        }
+        else if (result.value !== undefined) {
+            validatedData[fieldName] = result.value;
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        data: errors.length === 0 ? validatedData : undefined
+    };
+}
+/**
+ * Extract and validate arguments from CLI args array
+ *
+ * @param args - CLI argument array
+ * @param schema - Schema defining expected arguments
+ * @param positionalFields - Fields to extract positionally (in order)
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   neuronId: { type: 'uuid', required: true },
+ *   depth: { type: 'number', min: 1, max: 20, default: 5 }
+ * };
+ *
+ * const result = validateArgs(['neuron-123', '--depth', '10'], schema, ['neuronId']);
+ * // result.data = { neuronId: 'neuron-123', depth: 10 }
+ * ```
+ */
+export function validateArgs(args, schema, positionalFields = []) {
+    const data = {};
+    // Extract positional arguments
+    let positionalIndex = 0;
+    for (let i = 0; i < args.length && positionalIndex < positionalFields.length; i++) {
+        if (!args[i].startsWith('--')) {
+            data[positionalFields[positionalIndex]] = args[i];
+            positionalIndex++;
+        }
+    }
+    // Extract flag arguments
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith('--')) {
+            const flagName = args[i].slice(2);
+            const camelName = flagName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+            // Check if it's a boolean flag (no value) or has a value
+            const nextArg = args[i + 1];
+            if (nextArg === undefined || nextArg.startsWith('--')) {
+                data[camelName] = true;
+            }
+            else {
+                data[camelName] = nextArg;
+                i++; // Skip the value
+            }
+        }
+    }
+    return validateSchema(data, schema);
+}
+/**
+ * Create a validation error CommandResult
+ */
+export function validationError(errors) {
+    const errorMessages = errors.map(e => `  - ${e.field}: ${e.message}`).join('\n');
+    return {
+        success: false,
+        error: `Validation failed:\n${errorMessages}`
+    };
+}
+/**
+ * Create a CommandResult for missing required argument
+ */
+export function missingArgError(argName, usage) {
+    return {
+        success: false,
+        error: `Missing required argument: ${argName}\nUsage: ${usage}`
+    };
+}
+// ==================== Common Schemas ====================
+/**
+ * Common schema for neuron ID argument
+ */
+export const neuronIdSchema = {
+    type: 'uuid',
+    required: true,
+    validator: isValidNeuronId,
+    description: 'Neuron identifier'
+};
+/**
+ * Common schema for strength parameter
+ */
+export const strengthSchema = {
+    type: 'number',
+    min: 0,
+    max: 1,
+    default: 0.5,
+    description: 'Strength value (0-1)'
+};
+/**
+ * Common schema for priority parameter
+ */
+export const prioritySchema = {
+    type: 'number',
+    min: 1,
+    max: 10,
+    default: 5,
+    description: 'Priority level (1-10)'
+};
+/**
+ * Common schema for depth parameter
+ */
+export const depthSchema = {
+    type: 'number',
+    min: 1,
+    max: 100,
+    default: 5,
+    description: 'Search depth'
+};
+/**
+ * Common schema for limit parameter
+ */
+export const limitSchema = {
+    type: 'number',
+    min: 1,
+    max: 1000,
+    default: 10,
+    description: 'Result limit'
+};
+//# sourceMappingURL=validators.js.map

package/dist/cli/utils/validators.js.map

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

package/dist/core/advanced-embedding.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Advanced Embedding Service
+ * bge-m3 (1024d) + 양자화 + 2단계 검색
+ *
+ * @module core/advanced-embedding
+ */
+/**
+ * 임베딩 설정
+ */
+interface EmbeddingConfig {
+    model: 'bge-m3' | 'bge-large' | 'e5-large' | 'minilm';
+    dimension: 384 | 768 | 1024;
+    quantize: boolean;
+    usePCA: boolean;
+    pcaDimension?: number;
+}
+/**
+ * 양자화된 임베딩
+ */
+interface QuantizedEmbedding {
+    values: Int8Array;
+    min: number;
+    max: number;
+    scale: number;
+}
+/**
+ * 임베딩 결과 (확장)
+ */
+interface AdvancedEmbeddingResult {
+    text: string;
+    embedding: number[];
+    quantized?: QuantizedEmbedding;
+    pcaEmbedding?: number[];
+    model: string;
+    dimension: number;
+    processingTime: number;
+}
+/**
+ * Advanced Embedding Service
+ */
+export declare class AdvancedEmbeddingService {
+    private extractor;
+    private fallbackExtractor;
+    private config;
+    private isLoading;
+    private loadPromise;
+    private pcaMatrix;
+    private pcaMean;
+    private l1Cache;
+    private l1MaxSize;
+    private stats;
+    constructor(config?: Partial<EmbeddingConfig>);
+    /**
+     * 모델 로드 (지연 로딩 지원)
+     */
+    init(loadFallback?: boolean): Promise<void>;
+    /**
+     * 임베딩 생성 (전체 파이프라인)
+     */
+    embed(text: string, options?: {
+        quantize?: boolean;
+        pca?: boolean;
+        useCache?: boolean;
+    }): Promise<AdvancedEmbeddingResult>;
+    /**
+     * 배치 임베딩
+     */
+    embedBatch(texts: string[], options?: {
+        batchSize?: number;
+        quantize?: boolean;
+        pca?: boolean;
+    }): Promise<AdvancedEmbeddingResult[]>;
+    /**
+     * 양자화 (Float32 → Int8)
+     */
+    quantize(embedding: number[]): QuantizedEmbedding;
+    /**
+     * 역양자화 (Int8 → Float32)
+     */
+    dequantize(quantized: QuantizedEmbedding): number[];
+    /**
+     * PCA 변환 적용
+     */
+    private applyPCA;
+    /**
+     * PCA 학습 (임베딩 샘플로부터)
+     */
+    trainPCA(samples: number[][], targetDim?: number): Promise<void>;
+    /**
+     * 랜덤 프로젝션 (PCA 근사)
+     */
+    private randomProjection;
+    /**
+     * 2단계 검색: 빠른 후보 선정
+     */
+    coarseSearch(query: string, candidates: Array<{
+        id: string;
+        embedding: number[] | QuantizedEmbedding;
+    }>, topK?: number): Promise<Array<{
+        id: string;
+        score: number;
+    }>>;
+    /**
+     * 2단계 검색: 정밀 재순위
+     */
+    fineRerank(query: string, candidates: Array<{
+        id: string;
+        embedding: number[];
+    }>, topK?: number): Promise<Array<{
+        id: string;
+        score: number;
+    }>>;
+    /**
+     * 양자화된 벡터 내적 (빠름)
+     */
+    private quantizedDotProduct;
+    /**
+     * 코사인 유사도
+     */
+    cosineSimilarity(a: number[], b: number[]): number;
+    /**
+     * 캐시 추가
+     */
+    private addToCache;
+    /**
+     * 통계
+     */
+    getStats(): {
+        config: EmbeddingConfig;
+        cacheSize: number;
+        cacheHitRate: number;
+        avgEmbeddingTime: number;
+        isLoaded: boolean;
+        hasFallback: boolean;
+        hasPCA: boolean;
+        totalEmbeddings: number;
+        cacheHits: number;
+        totalTime: number;
+        modelLoadTime: number;
+        quantizationTime: number;
+        pcaTime: number;
+    };
+    /**
+     * 차원 반환
+     */
+    getDimension(): number;
+    /**
+     * PCA 차원 반환
+     */
+    getPCADimension(): number;
+}
+export declare const advancedEmbedding: AdvancedEmbeddingService;
+export {};
+//# sourceMappingURL=advanced-embedding.d.ts.map

package/dist/core/advanced-embedding.d.ts.map

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