/** * Incremental Indexing Infrastructure for PraisonAI Agents. * * Port of `praisonaiagents/knowledge/indexing.py`. * * Provides: * - CorpusStats: Statistics about indexed corpus * - IndexResult: Result of indexing operation * - IgnoreMatcher: .praisonignore pattern matching * - FileTracker: File hash/mtime tracking for incremental updates * * No heavy imports - only Node stdlib. * * Serialised shapes (`toDict()`, the FileTracker state file) keep the Python * snake_case keys so the JSON written by either runtime is readable by the * other. Constructor/method parameters use camelCase. */ /** * Strategy thresholds based on corpus size. * Mirrors `STRATEGY_THRESHOLDS` in indexing.py:24-30. */ export declare const STRATEGY_THRESHOLDS: Record; /** Strategy for corpora above every threshold. indexing.py:31 */ export declare const DEFAULT_STRATEGY = "hierarchical"; /** * Default extensions scanned by `CorpusStats.fromDirectory`. indexing.py:87-90 */ export declare const DEFAULT_CORPUS_EXTENSIONS: readonly string[]; /** * Simple token estimation (~4 chars per token). * Mirrors the Python `estimate_tokens` heuristic in `rag/budget.py`. */ export declare function estimateTokensSimple(text: string): number; /** * Translate a shell-style pattern to a RegExp source, following Python's * `fnmatch.translate`: `*` matches any run of characters (including `/`), * `?` matches one character, `[seq]` / `[!seq]` are character classes and * everything else is literal. The result anchors to the whole string. */ export declare function fnmatchTranslate(pattern: string): string; /** * Shell-style pattern match with Python `fnmatch.fnmatch` semantics * (case-sensitive, as on POSIX). */ export declare function fnmatch(name: string, pattern: string): boolean; /** Constructor options for {@link CorpusStats}. indexing.py:56-60 */ export interface CorpusStatsOptions { /** Number of files in corpus (Python `file_count`, default 0). */ fileCount?: number; /** Number of chunks created (Python `chunk_count`, default 0). */ chunkCount?: number; /** Estimated total tokens (Python `total_tokens`, default 0). */ totalTokens?: number; /** ISO timestamp of last indexing (Python `indexed_at`, default None). */ indexedAt?: string | null; /** Path to corpus root (Python `path`, default None). */ path?: string | null; } /** Serialised form produced by `CorpusStats.toDict()`. indexing.py:117-124 */ export interface CorpusStatsDict { file_count: number; chunk_count: number; total_tokens: number; indexed_at: string | null; path: string | null; strategy_recommendation: string; } /** * Statistics about an indexed corpus. * * Used for strategy selection and monitoring. * Port of `CorpusStats` (indexing.py:41-135). */ export declare class CorpusStats { fileCount: number; chunkCount: number; totalTokens: number; indexedAt: string | null; path: string | null; /** * @param options - dataclass fields, all optional. indexing.py:56-60 */ constructor(options?: CorpusStatsOptions); /** * Recommend retrieval strategy based on corpus size. * Port of the `strategy_recommendation` property (indexing.py:62-68). */ get strategyRecommendation(): string; /** * Create CorpusStats from a directory scan. * Port of `CorpusStats.from_directory` (indexing.py:70-113). * * @param path - Directory path to scan * @param extensions - Optional list of extensions to include * (default: {@link DEFAULT_CORPUS_EXTENSIONS}) * @returns CorpusStats with file count and token estimate */ static fromDirectory(dirPath: string, extensions?: string[] | null): CorpusStats; /** Convert to dictionary. Port of `to_dict` (indexing.py:115-124). */ toDict(): CorpusStatsDict; /** Create from dictionary. Port of `from_dict` (indexing.py:126-135). */ static fromDict(data: Partial & Record): CorpusStats; } /** Constructor options for {@link IndexResult}. indexing.py:152-158 */ export interface IndexResultOptions { /** Whether indexing succeeded (Python `success`, default True). */ success?: boolean; /** Number of files indexed (Python `files_indexed`, default 0). */ filesIndexed?: number; /** Number of files skipped as unchanged (Python `files_skipped`, default 0). */ filesSkipped?: number; /** Number of chunks created (Python `chunks_created`, default 0). */ chunksCreated?: number; /** Error messages (Python `errors`, default []). */ errors?: string[]; /** Time taken for indexing (Python `duration_seconds`, default 0.0). */ durationSeconds?: number; /** Stats about the indexed corpus (Python `corpus_stats`, default None). */ corpusStats?: CorpusStats | null; } /** Serialised form produced by `IndexResult.toDict()`. indexing.py:167-176 */ export interface IndexResultDict { success: boolean; files_indexed: number; files_skipped: number; chunks_created: number; total_files: number; errors: string[]; duration_seconds: number; corpus_stats: CorpusStatsDict | null; } /** * Result of an indexing operation. * Port of `IndexResult` (indexing.py:138-176). */ export declare class IndexResult { success: boolean; filesIndexed: number; filesSkipped: number; chunksCreated: number; errors: string[]; durationSeconds: number; corpusStats: CorpusStats | null; /** * @param options - dataclass fields, all optional. indexing.py:152-158 */ constructor(options?: IndexResultOptions); /** Total files processed (indexed + skipped). indexing.py:160-163 */ get totalFiles(): number; /** Convert to dictionary. Port of `to_dict` (indexing.py:165-176). */ toDict(): IndexResultDict; } /** * Matcher for .praisonignore patterns. * * Supports gitignore-style patterns: * - `*` matches any sequence of characters * - `**` matches any path segments * - `!` negates a pattern * - `#` starts a comment * * Port of `IgnoreMatcher` (indexing.py:179-323). */ export declare class IgnoreMatcher { private readonly includePatterns; private readonly excludePatterns; /** * Initialize with patterns. indexing.py:190-208 * * @param patterns - List of gitignore-style patterns (default None) */ constructor(patterns?: string[] | null); /** * Check if path should be ignored. Port of `should_ignore` (indexing.py:210-237). * * @param filePath - Path to check (relative or absolute) * @returns True if path should be ignored */ shouldIgnore(filePath: string): boolean; /** Check if path matches pattern. Port of `_matches` (indexing.py:239-269). */ private matches; /** * Load patterns from file. Port of `from_file` (indexing.py:271-288). * An unreadable file yields an empty matcher. * * @param filepath - Path to .praisonignore file */ static fromFile(filepath: string): IgnoreMatcher; /** * Auto-detect and load .praisonignore from directory; also reads .gitignore. * Port of `from_directory` (indexing.py:290-323). * * @param directory - Directory to search */ static fromDirectory(directory: string): IgnoreMatcher; } /** * Record returned by `FileTracker.getFileInfo()` and persisted in the state * file. Keys are the Python names (indexing.py:363-368, 382) so state files * are interchangeable between runtimes. */ export interface FileInfo { path: string; hash: string; /** Modification time in seconds (Python `st_mtime`). */ mtime: number; size: number; memory_ids?: string[]; [key: string]: any; } /** * Track file hashes and modification times for incremental indexing. * * Persists state to a JSON file for cross-session tracking. * Port of `FileTracker` (indexing.py:326-451). */ export declare class FileTracker { private readonly stateFile; private tracked; /** * Initialize tracker. indexing.py:333-341 * * @param stateFile - Path to state file for persistence (default None) */ constructor(stateFile?: string | null); /** * Get file information (hash, mtime, size). Port of `get_file_info` (indexing.py:343-368). * Throws (like `os.stat`) if the file does not exist. * * @param filepath - Path to file */ getFileInfo(filepath: string): FileInfo; /** * Mark file as indexed. Port of `mark_indexed` (indexing.py:370-383). * * @param filepath - Path to file * @param info - File info from `getFileInfo()` * @param memoryIds - Optional list of vector-store memory IDs produced for this * file, so a later re-index can delete stale chunks before re-adding. */ markIndexed(filepath: string, info: FileInfo, memoryIds?: string[] | null): void; /** Return the memory IDs previously stored for a file (empty if none). indexing.py:385-390 */ getMemoryIds(filepath: string): string[]; /** * Check if file has changed since last indexing. Port of `has_changed` (indexing.py:392-419). * * @param filepath - Path to file * @returns True if file is new, changed, or no longer readable */ hasChanged(filepath: string): boolean; /** Paths currently tracked (helper; not in the Python class). */ trackedPaths(): string[]; /** * Save state to file. Port of `save` (indexing.py:421-431). * Write failures are swallowed, as in Python. */ save(): void; /** * Load state from file. Port of `load` (indexing.py:433-442). * A missing file is a no-op; a corrupt file resets the tracker. */ load(): void; /** Clear all tracked files and remove the state file. Port of `clear` (indexing.py:444-451). */ clear(): void; }