@weavelogic/knowledge-graph-agent 0.2.0 → 0.4.0

package/dist/utils/logger.js

@@ -0,0 +1,311 @@
+import chalk from "chalk";
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["TRACE"] = 0] = "TRACE";
+  LogLevel2[LogLevel2["DEBUG"] = 1] = "DEBUG";
+  LogLevel2[LogLevel2["INFO"] = 2] = "INFO";
+  LogLevel2[LogLevel2["WARN"] = 3] = "WARN";
+  LogLevel2[LogLevel2["ERROR"] = 4] = "ERROR";
+  LogLevel2[LogLevel2["FATAL"] = 5] = "FATAL";
+  LogLevel2[LogLevel2["SILENT"] = 6] = "SILENT";
+  return LogLevel2;
+})(LogLevel || {});
+const LOG_LEVEL_NAMES = {
+  [
+    0
+    /* TRACE */
+  ]: "TRACE",
+  [
+    1
+    /* DEBUG */
+  ]: "DEBUG",
+  [
+    2
+    /* INFO */
+  ]: "INFO",
+  [
+    3
+    /* WARN */
+  ]: "WARN",
+  [
+    4
+    /* ERROR */
+  ]: "ERROR",
+  [
+    5
+    /* FATAL */
+  ]: "FATAL",
+  [
+    6
+    /* SILENT */
+  ]: "SILENT"
+};
+const LOG_LEVEL_COLORS = {
+  [
+    0
+    /* TRACE */
+  ]: chalk.gray,
+  [
+    1
+    /* DEBUG */
+  ]: chalk.blue,
+  [
+    2
+    /* INFO */
+  ]: chalk.green,
+  [
+    3
+    /* WARN */
+  ]: chalk.yellow,
+  [
+    4
+    /* ERROR */
+  ]: chalk.red,
+  [
+    5
+    /* FATAL */
+  ]: chalk.bgRed.white,
+  [
+    6
+    /* SILENT */
+  ]: (s) => s
+};
+function sanitizeStackTrace(stack) {
+  if (!stack) return void 0;
+  if (process.env.NODE_ENV !== "production") return stack;
+  return stack.replace(/\(\/[^)]+\/([^/]+:\d+:\d+)\)/g, "($1)");
+}
+function parseLogLevel(level) {
+  const upper = level.toUpperCase();
+  switch (upper) {
+    case "TRACE":
+      return 0;
+    case "DEBUG":
+      return 1;
+    case "INFO":
+      return 2;
+    case "WARN":
+    case "WARNING":
+      return 3;
+    case "ERROR":
+      return 4;
+    case "FATAL":
+      return 5;
+    case "SILENT":
+    case "NONE":
+      return 6;
+    default:
+      return 2;
+  }
+}
+class Logger {
+  level;
+  name;
+  timestamps;
+  json;
+  colors;
+  output;
+  constructor(options = {}) {
+    this.level = options.level ?? 2;
+    this.name = options.name;
+    this.timestamps = options.timestamps ?? true;
+    this.json = options.json ?? false;
+    this.colors = options.colors ?? true;
+    this.output = options.output ?? this.defaultOutput.bind(this);
+  }
+  /**
+   * Default output implementation
+   */
+  defaultOutput(entry) {
+    if (this.json) {
+      console.log(JSON.stringify({
+        level: LOG_LEVEL_NAMES[entry.level],
+        message: entry.message,
+        timestamp: entry.timestamp.toISOString(),
+        name: entry.name,
+        ...entry.context,
+        error: entry.error ? {
+          name: entry.error.name,
+          message: entry.error.message,
+          stack: sanitizeStackTrace(entry.error.stack)
+        } : void 0
+      }));
+      return;
+    }
+    const parts = [];
+    if (this.timestamps) {
+      const time = entry.timestamp.toISOString().slice(11, 23);
+      parts.push(this.colors ? chalk.gray(`[${time}]`) : `[${time}]`);
+    }
+    const levelName = LOG_LEVEL_NAMES[entry.level].padEnd(5);
+    const colorFn = LOG_LEVEL_COLORS[entry.level];
+    parts.push(this.colors ? colorFn(levelName) : levelName);
+    if (entry.name) {
+      parts.push(this.colors ? chalk.cyan(`[${entry.name}]`) : `[${entry.name}]`);
+    }
+    parts.push(entry.message);
+    if (entry.context && Object.keys(entry.context).length > 0) {
+      const contextStr = JSON.stringify(entry.context);
+      parts.push(this.colors ? chalk.gray(contextStr) : contextStr);
+    }
+    const line = parts.join(" ");
+    if (entry.level >= 4) {
+      console.error(line);
+      if (entry.error?.stack) {
+        console.error(this.colors ? chalk.gray(entry.error.stack) : entry.error.stack);
+      }
+    } else {
+      console.log(line);
+    }
+  }
+  /**
+   * Log at specified level
+   */
+  log(level, message, context) {
+    if (level < this.level) return;
+    const entry = {
+      level,
+      message,
+      timestamp: /* @__PURE__ */ new Date(),
+      name: this.name,
+      context
+    };
+    this.output(entry);
+  }
+  /**
+   * Log trace message
+   */
+  trace(message, context) {
+    this.log(0, message, context);
+  }
+  /**
+   * Log debug message
+   */
+  debug(message, context) {
+    this.log(1, message, context);
+  }
+  /**
+   * Log info message
+   */
+  info(message, context) {
+    this.log(2, message, context);
+  }
+  /**
+   * Log warning message
+   */
+  warn(message, context) {
+    this.log(3, message, context);
+  }
+  /**
+   * Log error message
+   */
+  error(message, error, context) {
+    const entry = {
+      level: 4,
+      message,
+      timestamp: /* @__PURE__ */ new Date(),
+      name: this.name,
+      context,
+      error
+    };
+    if (4 >= this.level) {
+      this.output(entry);
+    }
+  }
+  /**
+   * Log fatal message
+   */
+  fatal(message, error, context) {
+    const entry = {
+      level: 5,
+      message,
+      timestamp: /* @__PURE__ */ new Date(),
+      name: this.name,
+      context,
+      error
+    };
+    if (5 >= this.level) {
+      this.output(entry);
+    }
+  }
+  /**
+   * Create a child logger with additional context
+   */
+  child(name) {
+    const childName = this.name ? `${this.name}:${name}` : name;
+    return new Logger({
+      level: this.level,
+      name: childName,
+      timestamps: this.timestamps,
+      json: this.json,
+      colors: this.colors,
+      output: this.output
+    });
+  }
+  /**
+   * Set log level
+   */
+  setLevel(level) {
+    this.level = level;
+  }
+  /**
+   * Get current log level
+   */
+  getLevel() {
+    return this.level;
+  }
+  /**
+   * Check if level is enabled
+   */
+  isLevelEnabled(level) {
+    return level >= this.level;
+  }
+}
+let defaultLogger = null;
+function getLogger() {
+  if (!defaultLogger) {
+    const level = parseLogLevel(process.env.LOG_LEVEL ?? "info");
+    defaultLogger = new Logger({
+      level,
+      name: "kg",
+      colors: process.stdout.isTTY ?? true
+    });
+  }
+  return defaultLogger;
+}
+function createLogger(name, options = {}) {
+  return new Logger({ ...options, name });
+}
+function setDefaultLogger(logger) {
+  defaultLogger = logger;
+}
+function createProgressLogger(logger = getLogger()) {
+  let currentMessage = "";
+  return {
+    start(message) {
+      currentMessage = message;
+      logger.info(`⏳ ${message}`);
+    },
+    update(message) {
+      currentMessage = message;
+      logger.debug(`   ${message}`);
+    },
+    succeed(message) {
+      logger.info(`✅ ${message ?? currentMessage}`);
+    },
+    fail(message) {
+      logger.error(`❌ ${message ?? currentMessage}`);
+    },
+    stop() {
+    }
+  };
+}
+export {
+  LogLevel,
+  Logger,
+  createLogger,
+  createProgressLogger,
+  getLogger,
+  parseLogLevel,
+  setDefaultLogger
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sources":["../../src/utils/logger.ts"],"sourcesContent":["/**\n * Structured Logger\n *\n * Provides consistent logging with levels, context, and structured output.\n * Based on weaver logging patterns.\n *\n * @module utils/logger\n */\n\nimport chalk from 'chalk';\n\n/**\n * Log levels\n */\nexport enum LogLevel {\n  TRACE = 0,\n  DEBUG = 1,\n  INFO = 2,\n  WARN = 3,\n  ERROR = 4,\n  FATAL = 5,\n  SILENT = 6,\n}\n\n/**\n * Log level names\n */\nconst LOG_LEVEL_NAMES: Record<LogLevel, string> = {\n  [LogLevel.TRACE]: 'TRACE',\n  [LogLevel.DEBUG]: 'DEBUG',\n  [LogLevel.INFO]: 'INFO',\n  [LogLevel.WARN]: 'WARN',\n  [LogLevel.ERROR]: 'ERROR',\n  [LogLevel.FATAL]: 'FATAL',\n  [LogLevel.SILENT]: 'SILENT',\n};\n\n/**\n * Log level colors\n */\nconst LOG_LEVEL_COLORS: Record<LogLevel, (text: string) => string> = {\n  [LogLevel.TRACE]: chalk.gray,\n  [LogLevel.DEBUG]: chalk.blue,\n  [LogLevel.INFO]: chalk.green,\n  [LogLevel.WARN]: chalk.yellow,\n  [LogLevel.ERROR]: chalk.red,\n  [LogLevel.FATAL]: chalk.bgRed.white,\n  [LogLevel.SILENT]: (s: string) => s,\n};\n\n/**\n * Sanitize stack traces for production to remove/anonymize full file paths.\n * In development, returns the stack unchanged for debugging convenience.\n *\n * @param stack - The stack trace string to sanitize\n * @returns Sanitized stack trace (production) or original (development)\n */\nfunction sanitizeStackTrace(stack: string | undefined): string | undefined {\n  if (!stack) return undefined;\n  if (process.env.NODE_ENV !== 'production') return stack;\n  // Replace full paths with just file:line:column for security\n  return stack.replace(/\\(\\/[^)]+\\/([^/]+:\\d+:\\d+)\\)/g, '($1)');\n}\n\n/**\n * Log entry structure\n */\nexport interface LogEntry {\n  level: LogLevel;\n  message: string;\n  timestamp: Date;\n  context?: Record<string, unknown>;\n  name?: string;\n  error?: Error;\n}\n\n/**\n * Logger configuration\n */\nexport interface LoggerOptions {\n  /** Minimum level to log (default: INFO) */\n  level?: LogLevel;\n\n  /** Logger name/prefix */\n  name?: string;\n\n  /** Whether to include timestamps (default: true) */\n  timestamps?: boolean;\n\n  /** Whether to output as JSON (default: false) */\n  json?: boolean;\n\n  /** Whether to use colors (default: true) */\n  colors?: boolean;\n\n  /** Custom output function */\n  output?: (entry: LogEntry) => void;\n}\n\n/**\n * Parse log level from string\n */\nexport function parseLogLevel(level: string): LogLevel {\n  const upper = level.toUpperCase();\n  switch (upper) {\n    case 'TRACE':\n      return LogLevel.TRACE;\n    case 'DEBUG':\n      return LogLevel.DEBUG;\n    case 'INFO':\n      return LogLevel.INFO;\n    case 'WARN':\n    case 'WARNING':\n      return LogLevel.WARN;\n    case 'ERROR':\n      return LogLevel.ERROR;\n    case 'FATAL':\n      return LogLevel.FATAL;\n    case 'SILENT':\n    case 'NONE':\n      return LogLevel.SILENT;\n    default:\n      return LogLevel.INFO;\n  }\n}\n\n/**\n * Logger class\n */\nexport class Logger {\n  private level: LogLevel;\n  private name?: string;\n  private timestamps: boolean;\n  private json: boolean;\n  private colors: boolean;\n  private output: (entry: LogEntry) => void;\n\n  constructor(options: LoggerOptions = {}) {\n    this.level = options.level ?? LogLevel.INFO;\n    this.name = options.name;\n    this.timestamps = options.timestamps ?? true;\n    this.json = options.json ?? false;\n    this.colors = options.colors ?? true;\n    this.output = options.output ?? this.defaultOutput.bind(this);\n  }\n\n  /**\n   * Default output implementation\n   */\n  private defaultOutput(entry: LogEntry): void {\n    if (this.json) {\n      console.log(JSON.stringify({\n        level: LOG_LEVEL_NAMES[entry.level],\n        message: entry.message,\n        timestamp: entry.timestamp.toISOString(),\n        name: entry.name,\n        ...entry.context,\n        error: entry.error ? {\n          name: entry.error.name,\n          message: entry.error.message,\n          stack: sanitizeStackTrace(entry.error.stack),\n        } : undefined,\n      }));\n      return;\n    }\n\n    const parts: string[] = [];\n\n    // Timestamp\n    if (this.timestamps) {\n      const time = entry.timestamp.toISOString().slice(11, 23);\n      parts.push(this.colors ? chalk.gray(`[${time}]`) : `[${time}]`);\n    }\n\n    // Level\n    const levelName = LOG_LEVEL_NAMES[entry.level].padEnd(5);\n    const colorFn = LOG_LEVEL_COLORS[entry.level];\n    parts.push(this.colors ? colorFn(levelName) : levelName);\n\n    // Name\n    if (entry.name) {\n      parts.push(this.colors ? chalk.cyan(`[${entry.name}]`) : `[${entry.name}]`);\n    }\n\n    // Message\n    parts.push(entry.message);\n\n    // Context\n    if (entry.context && Object.keys(entry.context).length > 0) {\n      const contextStr = JSON.stringify(entry.context);\n      parts.push(this.colors ? chalk.gray(contextStr) : contextStr);\n    }\n\n    // Output\n    const line = parts.join(' ');\n    if (entry.level >= LogLevel.ERROR) {\n      console.error(line);\n      if (entry.error?.stack) {\n        console.error(this.colors ? chalk.gray(entry.error.stack) : entry.error.stack);\n      }\n    } else {\n      console.log(line);\n    }\n  }\n\n  /**\n   * Log at specified level\n   */\n  log(level: LogLevel, message: string, context?: Record<string, unknown>): void {\n    if (level < this.level) return;\n\n    const entry: LogEntry = {\n      level,\n      message,\n      timestamp: new Date(),\n      name: this.name,\n      context,\n    };\n\n    this.output(entry);\n  }\n\n  /**\n   * Log trace message\n   */\n  trace(message: string, context?: Record<string, unknown>): void {\n    this.log(LogLevel.TRACE, message, context);\n  }\n\n  /**\n   * Log debug message\n   */\n  debug(message: string, context?: Record<string, unknown>): void {\n    this.log(LogLevel.DEBUG, message, context);\n  }\n\n  /**\n   * Log info message\n   */\n  info(message: string, context?: Record<string, unknown>): void {\n    this.log(LogLevel.INFO, message, context);\n  }\n\n  /**\n   * Log warning message\n   */\n  warn(message: string, context?: Record<string, unknown>): void {\n    this.log(LogLevel.WARN, message, context);\n  }\n\n  /**\n   * Log error message\n   */\n  error(message: string, error?: Error, context?: Record<string, unknown>): void {\n    const entry: LogEntry = {\n      level: LogLevel.ERROR,\n      message,\n      timestamp: new Date(),\n      name: this.name,\n      context,\n      error,\n    };\n\n    if (LogLevel.ERROR >= this.level) {\n      this.output(entry);\n    }\n  }\n\n  /**\n   * Log fatal message\n   */\n  fatal(message: string, error?: Error, context?: Record<string, unknown>): void {\n    const entry: LogEntry = {\n      level: LogLevel.FATAL,\n      message,\n      timestamp: new Date(),\n      name: this.name,\n      context,\n      error,\n    };\n\n    if (LogLevel.FATAL >= this.level) {\n      this.output(entry);\n    }\n  }\n\n  /**\n   * Create a child logger with additional context\n   */\n  child(name: string): Logger {\n    const childName = this.name ? `${this.name}:${name}` : name;\n    return new Logger({\n      level: this.level,\n      name: childName,\n      timestamps: this.timestamps,\n      json: this.json,\n      colors: this.colors,\n      output: this.output,\n    });\n  }\n\n  /**\n   * Set log level\n   */\n  setLevel(level: LogLevel): void {\n    this.level = level;\n  }\n\n  /**\n   * Get current log level\n   */\n  getLevel(): LogLevel {\n    return this.level;\n  }\n\n  /**\n   * Check if level is enabled\n   */\n  isLevelEnabled(level: LogLevel): boolean {\n    return level >= this.level;\n  }\n}\n\n/**\n * Default logger instance\n */\nlet defaultLogger: Logger | null = null;\n\n/**\n * Get or create the default logger\n */\nexport function getLogger(): Logger {\n  if (!defaultLogger) {\n    const level = parseLogLevel(process.env.LOG_LEVEL ?? 'info');\n    defaultLogger = new Logger({\n      level,\n      name: 'kg',\n      colors: process.stdout.isTTY ?? true,\n    });\n  }\n  return defaultLogger;\n}\n\n/**\n * Create a named logger\n */\nexport function createLogger(name: string, options: Omit<LoggerOptions, 'name'> = {}): Logger {\n  return new Logger({ ...options, name });\n}\n\n/**\n * Set the default logger\n */\nexport function setDefaultLogger(logger: Logger): void {\n  defaultLogger = logger;\n}\n\n/**\n * Progress indicator for long-running operations\n */\nexport interface ProgressLogger {\n  start(message: string): void;\n  update(message: string): void;\n  succeed(message?: string): void;\n  fail(message?: string): void;\n  stop(): void;\n}\n\n/**\n * Create a simple progress logger\n */\nexport function createProgressLogger(logger: Logger = getLogger()): ProgressLogger {\n  let currentMessage = '';\n\n  return {\n    start(message: string) {\n      currentMessage = message;\n      logger.info(`⏳ ${message}`);\n    },\n    update(message: string) {\n      currentMessage = message;\n      logger.debug(`   ${message}`);\n    },\n    succeed(message?: string) {\n      logger.info(`✅ ${message ?? currentMessage}`);\n    },\n    fail(message?: string) {\n      logger.error(`❌ ${message ?? currentMessage}`);\n    },\n    stop() {\n      // No-op for simple logger\n    },\n  };\n}\n"],"names":["LogLevel"],"mappings":"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"}

package/dist/vector/config.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Vector Configuration
+ *
+ * Configuration types and defaults for RuVector-compatible vector storage.
+ * Supports multiple backends (memory, postgres, standalone) with HNSW indexing.
+ *
+ * @module vector/config
+ */
+import type { VectorIndexConfig } from './types.js';
+/**
+ * Backend storage type for vectors
+ */
+export type VectorBackend = 'memory' | 'postgres' | 'standalone' | 'sqlite' | 'cloud';
+/**
+ * HNSW (Hierarchical Navigable Small World) index configuration
+ *
+ * HNSW provides fast approximate nearest neighbor search with
+ * configurable accuracy/speed tradeoffs.
+ */
+export interface HNSWConfig {
+    /**
+     * Maximum number of connections per layer
+     * Higher values improve recall but increase memory usage
+     * @default 16
+     */
+    m: number;
+    /**
+     * Size of dynamic candidate list for construction
+     * Higher values improve index quality but slow down construction
+     * @default 200
+     */
+    efConstruction: number;
+    /**
+     * Size of dynamic candidate list for search
+     * Higher values improve recall but slow down search
+     * @default 100
+     */
+    efSearch: number;
+}
+/**
+ * Re-export VectorIndexConfig from types for convenience
+ */
+export type { VectorIndexConfig } from './types.js';
+/**
+ * PostgreSQL backend configuration
+ */
+export interface PostgresBackendConfig {
+    /**
+     * PostgreSQL connection string
+     * @example 'postgres://user:pass@localhost:5432/dbname'
+     */
+    connectionString: string;
+    /**
+     * Database schema for vector tables
+     * @default 'ruvector'
+     */
+    schema: string;
+}
+/**
+ * Cloud backend configuration
+ */
+export interface CloudBackendConfig {
+    /**
+     * Cloud vector database endpoint URL
+     */
+    url: string;
+    /**
+     * API key for authentication
+     */
+    apiKey?: string;
+}
+/**
+ * Standalone backend configuration
+ */
+export interface StandaloneBackendConfig {
+    /**
+     * Directory for vector data storage
+     * @default '.ruvector'
+     */
+    dataDir: string;
+}
+/**
+ * RuVector configuration
+ *
+ * Main configuration interface for the vector database system.
+ */
+export interface RuVectorConfig {
+    /**
+     * Storage backend type
+     */
+    backend: VectorBackend;
+    /**
+     * Vector index configuration
+     */
+    index: VectorIndexConfig;
+    /**
+     * PostgreSQL connection configuration
+     * Required when backend is 'postgres'
+     */
+    postgres?: PostgresBackendConfig;
+    /**
+     * Cloud endpoint configuration
+     * Required when backend is 'cloud'
+     */
+    cloud?: CloudBackendConfig;
+    /**
+     * Standalone file path configuration
+     * Required when backend is 'standalone'
+     */
+    standalone?: StandaloneBackendConfig;
+    /**
+     * Enable self-learning SONA (Self-Optimizing Neural Architecture) engine
+     * When enabled, the system learns from agent trajectories to improve performance
+     * @default false
+     */
+    enableSona?: boolean;
+    /**
+     * Enable trajectory tracking for agents
+     * Records agent actions for analysis and learning
+     * @default false
+     */
+    enableTrajectoryTracking?: boolean;
+    /**
+     * Cache configuration
+     */
+    cache?: {
+        /** Enable result caching */
+        enabled: boolean;
+        /** Maximum cache size in entries */
+        maxSize: number;
+        /** Cache TTL in seconds */
+        ttlSeconds: number;
+    };
+    /**
+     * Performance tuning
+     */
+    performance?: {
+        /** Batch size for bulk operations */
+        batchSize: number;
+        /** Enable parallel processing */
+        parallelProcessing: boolean;
+        /** Maximum concurrent operations */
+        maxConcurrency: number;
+        /** Memory limit in MB for index */
+        memoryLimitMb?: number;
+    };
+    /**
+     * Hybrid search configuration
+     */
+    hybrid?: {
+        /** Enable hybrid search */
+        enabled: boolean;
+        /** Default vector weight (0-1) */
+        defaultVectorWeight: number;
+        /** Graph database connection (for Cypher queries) */
+        graphConnection?: {
+            type: 'neo4j' | 'memgraph' | 'sqlite';
+            uri?: string;
+            database?: string;
+            auth?: {
+                user: string;
+                password: string;
+            };
+        };
+    };
+    /**
+     * Namespace configuration for multi-tenant support
+     */
+    namespace?: {
+        /** Default namespace */
+        defaultNamespace: string;
+        /** Namespace isolation level */
+        isolation: 'soft' | 'hard';
+    };
+}
+/**
+ * Default HNSW configuration
+ * Balanced settings for most use cases
+ */
+export declare const DEFAULT_HNSW_CONFIG: HNSWConfig;
+/**
+ * Default vector index configuration
+ * Optimized for OpenAI/Claude embeddings (1536 dimensions)
+ */
+export declare const DEFAULT_INDEX_CONFIG: VectorIndexConfig;
+/**
+ * Default cache configuration
+ */
+export declare const DEFAULT_CACHE_CONFIG: {
+    readonly enabled: true;
+    readonly maxSize: 1000;
+    readonly ttlSeconds: 300;
+};
+/**
+ * Default performance configuration
+ */
+export declare const DEFAULT_PERFORMANCE_CONFIG: {
+    readonly batchSize: 100;
+    readonly parallelProcessing: true;
+    readonly maxConcurrency: 4;
+};
+/**
+ * Create RuVector configuration from environment variables
+ *
+ * Reads configuration from the following environment variables:
+ * - RUVECTOR_BACKEND: Storage backend type (default: 'memory')
+ * - RUVECTOR_DIMENSIONS: Vector dimensions (default: 384)
+ * - RUVECTOR_ENABLE_SONA: Enable SONA learning (default: false)
+ * - RUVECTOR_ENABLE_TRAJECTORY: Enable trajectory tracking (default: false)
+ * - DATABASE_URL: PostgreSQL connection string (for postgres backend)
+ * - RUVECTOR_SCHEMA: PostgreSQL schema (default: 'ruvector')
+ * - RUVECTOR_CLOUD_URL: Cloud endpoint URL (for cloud backend)
+ * - RUVECTOR_API_KEY: Cloud API key (for cloud backend)
+ * - RUVECTOR_DATA_DIR: Data directory (for standalone backend)
+ *
+ * @returns RuVectorConfig configured from environment
+ *
+ * @example
+ * ```typescript
+ * // Set environment variables
+ * process.env.RUVECTOR_BACKEND = 'postgres';
+ * process.env.DATABASE_URL = 'postgres://localhost:5432/mydb';
+ *
+ * // Create configuration
+ * const config = createRuVectorConfig();
+ * ```
+ */
+export declare function createRuVectorConfig(): RuVectorConfig;
+/**
+ * Validation result for RuVector configuration
+ */
+export interface ConfigValidationResult {
+    /**
+     * Whether the configuration is valid
+     */
+    valid: boolean;
+    /**
+     * List of validation errors (empty if valid)
+     */
+    errors: string[];
+    /**
+     * List of validation warnings
+     */
+    warnings: string[];
+}
+/**
+ * Legacy alias for backwards compatibility
+ */
+export type ValidationResult = ConfigValidationResult;
+/**
+ * Validate RuVector configuration
+ *
+ * Checks that all required fields are present and valid based on
+ * the selected backend type.
+ *
+ * @param config - Configuration to validate
+ * @returns Validation result with errors if invalid
+ *
+ * @example
+ * ```typescript
+ * const config = createRuVectorConfig();
+ * const result = validateRuVectorConfig(config);
+ *
+ * if (!result.valid) {
+ *   console.error('Configuration errors:', result.errors);
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export declare function validateRuVectorConfig(config: RuVectorConfig): ConfigValidationResult;
+/**
+ * Default configuration instance
+ * Created from environment variables at module load time
+ */
+export declare const defaultConfig: RuVectorConfig;
+/**
+ * Create configuration for high-performance scenarios
+ *
+ * Optimized for large-scale deployments with many vectors
+ */
+export declare function createHighPerformanceConfig(dimensions?: number): RuVectorConfig;
+/**
+ * Create configuration for memory-constrained environments
+ *
+ * Optimized for minimal memory usage
+ */
+export declare function createLowMemoryConfig(dimensions?: number): RuVectorConfig;
+/**
+ * Create configuration for hybrid search with graph integration
+ */
+export declare function createHybridSearchConfig(dimensions?: number, graphType?: 'neo4j' | 'memgraph' | 'sqlite'): RuVectorConfig;
+/**
+ * Get recommended configuration based on vector count
+ *
+ * @param estimatedVectorCount - Estimated number of vectors to store
+ * @param dimensions - Vector dimensions
+ * @returns Recommended configuration
+ */
+export declare function getRecommendedConfig(estimatedVectorCount: number, dimensions?: number): RuVectorConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/vector/config.d.ts.map

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