@agenticc/core 1.0.0

package/dist/core/tool-registry.js

@@ -0,0 +1,252 @@
+/**
+ * Tool Registry
+ *
+ * Manages registration and retrieval of tools for the Agent.
+ * Validates tool definitions and provides Function Calling format conversion.
+ *
+ * @module core/tool-registry
+ */
+import { toolToDefinition } from '../types/tool.js';
+/**
+ * Error thrown when tool registration fails
+ */
+export class ToolRegistrationError extends Error {
+    toolName;
+    reason;
+    constructor(message, toolName, reason) {
+        super(message);
+        this.toolName = toolName;
+        this.reason = reason;
+        this.name = 'ToolRegistrationError';
+    }
+}
+/**
+ * Error thrown when a tool is not found
+ */
+export class ToolNotFoundError extends Error {
+    constructor(toolName) {
+        super(`Tool not found: ${toolName}`);
+        this.name = 'ToolNotFoundError';
+    }
+}
+/**
+ * Validates a tool parameter definition
+ */
+function validateParameter(param, toolName) {
+    if (!param.name || typeof param.name !== 'string') {
+        throw new ToolRegistrationError(`Invalid parameter name in tool ${toolName}`, toolName, 'Parameter name must be a non-empty string');
+    }
+    const validTypes = ['string', 'number', 'boolean', 'object', 'array'];
+    if (!validTypes.includes(param.type)) {
+        throw new ToolRegistrationError(`Invalid parameter type "${param.type}" in tool ${toolName}`, toolName, `Parameter type must be one of: ${validTypes.join(', ')}`);
+    }
+    if (!param.description || typeof param.description !== 'string') {
+        throw new ToolRegistrationError(`Invalid parameter description in tool ${toolName}`, toolName, 'Parameter description must be a non-empty string');
+    }
+    if (typeof param.required !== 'boolean') {
+        throw new ToolRegistrationError(`Invalid parameter required flag in tool ${toolName}`, toolName, 'Parameter required must be a boolean');
+    }
+    if (param.enum !== undefined && !Array.isArray(param.enum)) {
+        throw new ToolRegistrationError(`Invalid parameter enum in tool ${toolName}`, toolName, 'Parameter enum must be an array of strings');
+    }
+}
+/**
+ * Validates a complete tool definition
+ */
+function validateTool(tool) {
+    // Validate name
+    if (!tool.name || typeof tool.name !== 'string') {
+        throw new ToolRegistrationError('Invalid tool name', tool.name || 'unknown', 'Tool name must be a non-empty string');
+    }
+    // Validate name format (alphanumeric, underscores, hyphens)
+    if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(tool.name)) {
+        throw new ToolRegistrationError(`Invalid tool name format: ${tool.name}`, tool.name, 'Tool name must start with a letter and contain only alphanumeric characters, underscores, and hyphens');
+    }
+    // Validate description
+    if (!tool.description || typeof tool.description !== 'string') {
+        throw new ToolRegistrationError(`Invalid tool description for ${tool.name}`, tool.name, 'Tool description must be a non-empty string');
+    }
+    // Validate parameters
+    if (!Array.isArray(tool.parameters)) {
+        throw new ToolRegistrationError(`Invalid parameters for tool ${tool.name}`, tool.name, 'Tool parameters must be an array');
+    }
+    // Check for duplicate parameter names
+    const paramNames = new Set();
+    for (const param of tool.parameters) {
+        validateParameter(param, tool.name);
+        if (paramNames.has(param.name)) {
+            throw new ToolRegistrationError(`Duplicate parameter name "${param.name}" in tool ${tool.name}`, tool.name, 'Parameter names must be unique within a tool');
+        }
+        paramNames.add(param.name);
+    }
+    // Validate execute function
+    if (typeof tool.execute !== 'function') {
+        throw new ToolRegistrationError(`Invalid execute function for tool ${tool.name}`, tool.name, 'Tool execute must be a function');
+    }
+    // Validate optional fields
+    if (tool.riskLevel !== undefined) {
+        const validRiskLevels = ['low', 'medium', 'high'];
+        if (!validRiskLevels.includes(tool.riskLevel)) {
+            throw new ToolRegistrationError(`Invalid risk level for tool ${tool.name}`, tool.name, `Risk level must be one of: ${validRiskLevels.join(', ')}`);
+        }
+    }
+}
+/**
+ * Registry for managing Agent tools
+ *
+ * Provides methods to register, retrieve, and list tools.
+ * Ensures tool uniqueness and validates definitions.
+ */
+export class ToolRegistry {
+    tools = new Map();
+    options;
+    constructor(options = {}) {
+        this.options = {
+            allowReplace: options.allowReplace ?? false,
+            strictValidation: options.strictValidation ?? true,
+        };
+    }
+    /**
+     * Register a tool with the registry
+     *
+     * @param tool - The tool to register
+     * @throws ToolRegistrationError if validation fails or tool already exists
+     */
+    register(tool) {
+        // Validate tool definition
+        if (this.options.strictValidation) {
+            validateTool(tool);
+        }
+        // Check for existing tool
+        if (this.tools.has(tool.name)) {
+            if (!this.options.allowReplace) {
+                throw new ToolRegistrationError(`Tool already registered: ${tool.name}`, tool.name, 'A tool with this name already exists. Use allowReplace option to override.');
+            }
+        }
+        this.tools.set(tool.name, tool);
+    }
+    /**
+     * Register multiple tools at once
+     *
+     * @param tools - Array of tools to register
+     * @throws ToolRegistrationError if any tool fails validation
+     */
+    registerAll(tools) {
+        for (const tool of tools) {
+            this.register(tool);
+        }
+    }
+    /**
+     * Get a tool by name
+     *
+     * @param name - The tool name
+     * @returns The tool if found, undefined otherwise
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Get a tool by name, throwing if not found
+     *
+     * @param name - The tool name
+     * @returns The tool
+     * @throws ToolNotFoundError if tool doesn't exist
+     */
+    getOrThrow(name) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            throw new ToolNotFoundError(name);
+        }
+        return tool;
+    }
+    /**
+     * Check if a tool is registered
+     *
+     * @param name - The tool name
+     * @returns true if the tool exists
+     */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /**
+     * Remove a tool from the registry
+     *
+     * @param name - The tool name
+     * @returns true if the tool was removed, false if it didn't exist
+     */
+    unregister(name) {
+        return this.tools.delete(name);
+    }
+    /**
+     * List all registered tools
+     *
+     * @returns Array of all registered tools
+     */
+    list() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * List tool names
+     *
+     * @returns Array of registered tool names
+     */
+    listNames() {
+        return Array.from(this.tools.keys());
+    }
+    /**
+     * List tools by category
+     *
+     * @param category - The category to filter by
+     * @returns Array of tools in the specified category
+     */
+    listByCategory(category) {
+        return this.list().filter((tool) => tool.category === category);
+    }
+    /**
+     * Get all unique categories
+     *
+     * @returns Array of unique category names
+     */
+    getCategories() {
+        const categories = new Set();
+        for (const tool of this.tools.values()) {
+            if (tool.category) {
+                categories.add(tool.category);
+            }
+        }
+        return Array.from(categories);
+    }
+    /**
+     * Get tool definitions in Function Calling format
+     *
+     * @returns Array of tool definitions for LLM APIs
+     */
+    getDefinitions() {
+        return this.list().map((tool) => toolToDefinition(tool));
+    }
+    /**
+     * Get tool definitions for specific tools
+     *
+     * @param names - Array of tool names to get definitions for
+     * @returns Array of tool definitions
+     */
+    getDefinitionsFor(names) {
+        return names
+            .map((name) => this.tools.get(name))
+            .filter((tool) => tool !== undefined)
+            .map((tool) => toolToDefinition(tool));
+    }
+    /**
+     * Get the number of registered tools
+     */
+    get size() {
+        return this.tools.size;
+    }
+    /**
+     * Clear all registered tools
+     */
+    clear() {
+        this.tools.clear();
+    }
+}
+//# sourceMappingURL=tool-registry.js.map

package/dist/core/tool-registry.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * AI Agent Framework
+ *
+ * A modular AI Agent framework with LLM support, RAG knowledge retrieval,
+ * and extensible tool system.
+ */
+export * from './types/tool.js';
+export * from './types/response.js';
+export * from './types/config.js';
+export * from './types/plugin.js';
+export * from './types/streaming.js';
+export type { LoopConfig, LoopStatus, LoopMessage, LLMToolCall, LoopState, LoopResult, LoopRunOptions, } from './types/loop.js';
+export { DEFAULT_LOOP_CONFIG } from './types/loop.js';
+export type { ToolCallRecord as LoopToolCallRecord } from './types/loop.js';
+export type { Document, DocumentInput, SearchOptions, SearchResult, KnowledgeAssessment, } from './types/knowledge.js';
+export * from './llm/index.js';
+export { KnowledgeStore } from './knowledge/store.js';
+export { Embedder } from './knowledge/embedder.js';
+export { Retriever } from './knowledge/retriever.js';
+export { MarkdownLoader } from './knowledge/loaders/markdown.js';
+export { YamlLoader } from './knowledge/loaders/yaml.js';
+export { TextChunker, createChunker, type ChunkerConfig, type TextChunk, } from './knowledge/chunker.js';
+/**
+ * @deprecated Use @ai-agent/storage-memory package instead.
+ * These exports are kept for backward compatibility.
+ */
+export { SessionManager } from './conversation/session.js';
+/**
+ * @deprecated Use @ai-agent/storage-memory package instead.
+ * These exports are kept for backward compatibility.
+ */
+export { MessageStore, type StoredMessage } from './conversation/message-store.js';
+export { ContextBuilder, type ContextBuilderConfig } from './conversation/context-builder.js';
+export { AuditLogger } from './audit/logger.js';
+export { AuditLogQuery, type AuditLogQueryOptions } from './audit/query.js';
+export { Agent } from './core/agent.js';
+export { ToolRegistry } from './core/tool-registry.js';
+export { ToolExecutor } from './core/tool-executor.js';
+export { IntentParser, type Intent } from './core/intent-parser.js';
+export { PlanGenerator, type ExecutionPlan } from './core/plan-generator.js';
+export { ResponseHandler } from './core/response-handler.js';
+export { PluginManager, PluginError } from './core/plugin-manager.js';
+export { AgenticLoop, LoopError } from './core/agentic-loop.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AAErC,YAAY,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,SAAS,EACT,UAAU,EACV,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,YAAY,EAAE,cAAc,IAAI,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,YAAY,EACV,QAAQ,EACR,aAAa,EACb,aAAa,EACb,YAAY,EACZ,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAG9B,cAAc,gBAAgB,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EACL,WAAW,EACX,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,wBAAwB,CAAC;AAGhC;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAG9F,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG5E,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,47 @@
+/**
+ * AI Agent Framework
+ *
+ * A modular AI Agent framework with LLM support, RAG knowledge retrieval,
+ * and extensible tool system.
+ */
+// Types
+export * from './types/tool.js';
+export * from './types/response.js';
+export * from './types/config.js';
+export * from './types/plugin.js';
+export * from './types/streaming.js';
+export { DEFAULT_LOOP_CONFIG } from './types/loop.js';
+// LLM Layer
+export * from './llm/index.js';
+// Knowledge System
+export { KnowledgeStore } from './knowledge/store.js';
+export { Embedder } from './knowledge/embedder.js';
+export { Retriever } from './knowledge/retriever.js';
+export { MarkdownLoader } from './knowledge/loaders/markdown.js';
+export { YamlLoader } from './knowledge/loaders/yaml.js';
+export { TextChunker, createChunker, } from './knowledge/chunker.js';
+// Conversation System (Deprecated - use @ai-agent/storage-memory instead)
+/**
+ * @deprecated Use @ai-agent/storage-memory package instead.
+ * These exports are kept for backward compatibility.
+ */
+export { SessionManager } from './conversation/session.js';
+/**
+ * @deprecated Use @ai-agent/storage-memory package instead.
+ * These exports are kept for backward compatibility.
+ */
+export { MessageStore } from './conversation/message-store.js';
+export { ContextBuilder } from './conversation/context-builder.js';
+// Audit System
+export { AuditLogger } from './audit/logger.js';
+export { AuditLogQuery } from './audit/query.js';
+// Core
+export { Agent } from './core/agent.js';
+export { ToolRegistry } from './core/tool-registry.js';
+export { ToolExecutor } from './core/tool-executor.js';
+export { IntentParser } from './core/intent-parser.js';
+export { PlanGenerator } from './core/plan-generator.js';
+export { ResponseHandler } from './core/response-handler.js';
+export { PluginManager, PluginError } from './core/plugin-manager.js';
+export { AgenticLoop, LoopError } from './core/agentic-loop.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,QAAQ;AACR,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AAWrC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAWtD,YAAY;AACZ,cAAc,gBAAgB,CAAC;AAE/B,mBAAmB;AACnB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EACL,WAAW,EACX,aAAa,GAGd,MAAM,wBAAwB,CAAC;AAEhC,0EAA0E;AAC1E;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAsB,MAAM,iCAAiC,CAAC;AACnF,OAAO,EAAE,cAAc,EAA6B,MAAM,mCAAmC,CAAC;AAE9F,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAA6B,MAAM,kBAAkB,CAAC;AAE5E,OAAO;AACP,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAe,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAsB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/knowledge/chunker.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Text Chunker
+ *
+ * Handles intelligent text chunking for embedding generation.
+ * Splits large documents into smaller chunks while preserving context.
+ *
+ * _Requirements: 3.5_
+ */
+/**
+ * Chunk configuration options
+ */
+export interface ChunkerConfig {
+    /** Maximum characters per chunk (default: 2000) */
+    maxChunkSize?: number;
+    /** Overlap between chunks in characters (default: 200) */
+    chunkOverlap?: number;
+    /** Minimum chunk size to avoid tiny fragments (default: 100) */
+    minChunkSize?: number;
+    /** Separators to use for splitting, in order of priority */
+    separators?: string[];
+}
+/**
+ * A chunk of text with metadata
+ */
+export interface TextChunk {
+    /** The chunk content */
+    content: string;
+    /** Index of this chunk in the original document */
+    index: number;
+    /** Start position in original text */
+    startPos: number;
+    /** End position in original text */
+    endPos: number;
+}
+/**
+ * Text Chunker class for splitting documents
+ */
+export declare class TextChunker {
+    private config;
+    constructor(config?: ChunkerConfig);
+    /**
+     * Check if text needs chunking
+     */
+    needsChunking(text: string): boolean;
+    /**
+     * Split text into chunks
+     */
+    chunk(text: string): TextChunk[];
+    /**
+     * Recursively split text using separators
+     */
+    private recursiveSplit;
+    /**
+     * Find the best separator that creates reasonable splits
+     */
+    private findBestSeparator;
+    /**
+     * Split text by size when no good separator found
+     */
+    private splitBySize;
+    /**
+     * Get overlap text from the end of a chunk
+     */
+    private getOverlapText;
+    /**
+     * Get configuration
+     */
+    getConfig(): Required<ChunkerConfig>;
+    /**
+     * Update configuration
+     */
+    setConfig(config: Partial<ChunkerConfig>): void;
+}
+/**
+ * Create a default chunker instance
+ */
+export declare function createChunker(config?: ChunkerConfig): TextChunker;
+//# sourceMappingURL=chunker.d.ts.map

package/dist/knowledge/chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.d.ts","sourceRoot":"","sources":["../../src/knowledge/chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAyBD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAA0B;gBAE5B,MAAM,CAAC,EAAE,aAAa;IAIlC;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIpC;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE;IAgBhC;;OAEG;IACH,OAAO,CAAC,cAAc;IAgFtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;OAEG;IACH,OAAO,CAAC,WAAW;IA+CnB;;OAEG;IACH,OAAO,CAAC,cAAc;IAmBtB;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,aAAa,CAAC;IAIpC;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;CAGhD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,WAAW,CAEjE"}

package/dist/knowledge/chunker.js

@@ -0,0 +1,233 @@
+/**
+ * Text Chunker
+ *
+ * Handles intelligent text chunking for embedding generation.
+ * Splits large documents into smaller chunks while preserving context.
+ *
+ * _Requirements: 3.5_
+ */
+const DEFAULT_CONFIG = {
+    maxChunkSize: 500, // Reduced to ~250 tokens to fit BGE embedding model limits
+    chunkOverlap: 50, // Reduced proportionally
+    minChunkSize: 30, // Reduced proportionally
+    separators: [
+        '\n\n\n', // Triple newline (major sections)
+        '\n\n', // Double newline (paragraphs)
+        '\n', // Single newline
+        '。', // Chinese period
+        '.', // English period
+        '！', // Chinese exclamation
+        '!', // English exclamation
+        '？', // Chinese question mark
+        '?', // English question mark
+        '；', // Chinese semicolon
+        ';', // English semicolon
+        '，', // Chinese comma
+        ',', // English comma
+        ' ', // Space
+        '', // Character by character (last resort)
+    ],
+};
+/**
+ * Text Chunker class for splitting documents
+ */
+export class TextChunker {
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Check if text needs chunking
+     */
+    needsChunking(text) {
+        return text.length > this.config.maxChunkSize;
+    }
+    /**
+     * Split text into chunks
+     */
+    chunk(text) {
+        // If text is small enough, return as single chunk
+        if (!this.needsChunking(text)) {
+            return [
+                {
+                    content: text,
+                    index: 0,
+                    startPos: 0,
+                    endPos: text.length,
+                },
+            ];
+        }
+        return this.recursiveSplit(text, this.config.separators);
+    }
+    /**
+     * Recursively split text using separators
+     */
+    recursiveSplit(text, separators) {
+        const chunks = [];
+        if (text.length <= this.config.maxChunkSize) {
+            chunks.push({
+                content: text,
+                index: 0,
+                startPos: 0,
+                endPos: text.length,
+            });
+            return chunks;
+        }
+        // Find the best separator to use
+        const separator = this.findBestSeparator(text, separators);
+        if (separator === '') {
+            // Last resort: split by character count
+            return this.splitBySize(text);
+        }
+        // Split by separator
+        const splits = text.split(separator);
+        let currentChunk = '';
+        let currentStartPos = 0;
+        let position = 0;
+        for (let i = 0; i < splits.length; i++) {
+            const split = splits[i];
+            const splitWithSep = i < splits.length - 1 ? split + separator : split;
+            // Check if adding this split would exceed max size
+            if (currentChunk.length + splitWithSep.length > this.config.maxChunkSize) {
+                // Save current chunk if it's not empty
+                if (currentChunk.length >= this.config.minChunkSize) {
+                    chunks.push({
+                        content: currentChunk.trim(),
+                        index: chunks.length,
+                        startPos: currentStartPos,
+                        endPos: position,
+                    });
+                    // Start new chunk with overlap
+                    const overlapText = this.getOverlapText(currentChunk);
+                    currentChunk = overlapText + splitWithSep;
+                    currentStartPos = position - overlapText.length;
+                }
+                else {
+                    // Current chunk too small, try to merge
+                    currentChunk += splitWithSep;
+                }
+            }
+            else {
+                currentChunk += splitWithSep;
+            }
+            position += splitWithSep.length;
+        }
+        // Add remaining chunk
+        if (currentChunk.trim().length >= this.config.minChunkSize) {
+            chunks.push({
+                content: currentChunk.trim(),
+                index: chunks.length,
+                startPos: currentStartPos,
+                endPos: text.length,
+            });
+        }
+        else if (chunks.length > 0 && currentChunk.trim().length > 0) {
+            // Merge small remaining chunk with previous
+            const lastChunk = chunks[chunks.length - 1];
+            lastChunk.content = lastChunk.content + ' ' + currentChunk.trim();
+            lastChunk.endPos = text.length;
+        }
+        // Re-index chunks
+        chunks.forEach((chunk, idx) => {
+            chunk.index = idx;
+        });
+        return chunks;
+    }
+    /**
+     * Find the best separator that creates reasonable splits
+     */
+    findBestSeparator(text, separators) {
+        for (const sep of separators) {
+            if (sep === '')
+                continue;
+            if (text.includes(sep)) {
+                const splits = text.split(sep);
+                // Check if this separator creates reasonable chunks
+                const avgSize = text.length / splits.length;
+                if (avgSize <= this.config.maxChunkSize * 1.5) {
+                    return sep;
+                }
+            }
+        }
+        // Return empty string to trigger character-based splitting
+        return '';
+    }
+    /**
+     * Split text by size when no good separator found
+     */
+    splitBySize(text) {
+        const chunks = [];
+        let position = 0;
+        while (position < text.length) {
+            let endPos = Math.min(position + this.config.maxChunkSize, text.length);
+            // Try to find a good break point (space or punctuation)
+            if (endPos < text.length) {
+                const searchStart = Math.max(position, endPos - 100);
+                let breakPoint = -1;
+                // Look for space or punctuation near the end
+                for (let i = endPos; i >= searchStart; i--) {
+                    const char = text[i];
+                    if (' \n\t。.！!？?；;，,'.includes(char)) {
+                        breakPoint = i + 1;
+                        break;
+                    }
+                }
+                if (breakPoint > position) {
+                    endPos = breakPoint;
+                }
+            }
+            const chunkContent = text.slice(position, endPos).trim();
+            if (chunkContent.length >= this.config.minChunkSize) {
+                chunks.push({
+                    content: chunkContent,
+                    index: chunks.length,
+                    startPos: position,
+                    endPos: endPos,
+                });
+            }
+            // Move position with overlap
+            position = endPos - this.config.chunkOverlap;
+            if (position <= chunks[chunks.length - 1]?.startPos) {
+                position = endPos; // Prevent infinite loop
+            }
+        }
+        return chunks;
+    }
+    /**
+     * Get overlap text from the end of a chunk
+     */
+    getOverlapText(text) {
+        if (text.length <= this.config.chunkOverlap) {
+            return text;
+        }
+        const overlapStart = text.length - this.config.chunkOverlap;
+        // Try to start at a word boundary
+        let adjustedStart = overlapStart;
+        for (let i = overlapStart; i < Math.min(overlapStart + 50, text.length); i++) {
+            if (' \n\t'.includes(text[i])) {
+                adjustedStart = i + 1;
+                break;
+            }
+        }
+        return text.slice(adjustedStart);
+    }
+    /**
+     * Get configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration
+     */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+}
+/**
+ * Create a default chunker instance
+ */
+export function createChunker(config) {
+    return new TextChunker(config);
+}
+//# sourceMappingURL=chunker.js.map