@yesvara/svara 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,967 @@
+import { RequestHandler, Express } from 'express';
+import EventEmitter from 'events';
+
+/**
+ * @module SvaraApp
+ *
+ * The framework entry point. Wraps Express to give you a clean,
+ * AI-first HTTP server that works with zero configuration.
+ *
+ * @example
+ * ```ts
+ * import { SvaraApp, SvaraAgent } from '@yesvara/svara';
+ *
+ * const app = new SvaraApp();
+ *
+ * const agent = new SvaraAgent({
+ *   name: 'Support Bot',
+ *   model: 'gpt-4o-mini',
+ *   knowledge: './docs',
+ * });
+ *
+ * app.route('/chat', agent.handler());
+ * app.listen(3000);
+ * // → Server running at http://localhost:3000
+ * // → POST /chat accepts { message, sessionId }
+ * // → GET  /health returns { status: 'ok' }
+ * ```
+ *
+ * @example With your own Express app
+ * ```ts
+ * import express from 'express';
+ * const expressApp = express();
+ *
+ * // Mount as middleware on any path
+ * expressApp.post('/api/chat', agent.handler());
+ * ```
+ */
+
+interface AppOptions {
+    /**
+     * Enable CORS. Pass `true` for wildcard (*), or a specific origin string.
+     * @default false
+     */
+    cors?: boolean | string;
+    /**
+     * Require an API key in the `Authorization: Bearer <key>` header.
+     * Useful for protecting your agent endpoint.
+     */
+    apiKey?: string;
+    /**
+     * Request body size limit. @default '10mb'
+     */
+    bodyLimit?: string;
+}
+declare class SvaraApp {
+    private readonly express;
+    private server;
+    constructor(options?: AppOptions);
+    /**
+     * Mount an agent (or any Express handler) on a route.
+     * Returns `this` for chaining.
+     *
+     * @example
+     * app
+     *   .route('/chat', supportAgent.handler())
+     *   .route('/sales', salesAgent.handler());
+     */
+    route(path: string, handler: RequestHandler): this;
+    /**
+     * Add Express middleware (logging, auth, rate limiting, etc.)
+     *
+     * @example
+     * import rateLimit from 'express-rate-limit';
+     * app.use(rateLimit({ windowMs: 60_000, max: 100 }));
+     */
+    use(middleware: RequestHandler): this;
+    /**
+     * Start listening on the given port.
+     *
+     * @example
+     * await app.listen(3000);
+     * // → [@yesvara/svara] Listening at http://localhost:3000
+     */
+    listen(port?: number): Promise<void>;
+    /**
+     * Stop the server gracefully.
+     */
+    stop(): Promise<void>;
+    /**
+     * Access the underlying Express app for advanced configuration.
+     *
+     * @example
+     * const expressApp = app.express();
+     * expressApp.set('trust proxy', 1);
+     */
+    getExpressApp(): Express;
+    private setup;
+}
+
+/**
+ * @internal
+ * Internal types for the SvaraJS framework engine.
+ * These are NOT exported to users — see src/types.ts for the public API.
+ */
+type LLMProviderName = 'openai' | 'anthropic' | 'ollama' | 'groq';
+interface LLMConfig {
+    provider: LLMProviderName;
+    model: string;
+    apiKey?: string;
+    baseURL?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeout?: number;
+}
+interface LLMMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCallId?: string;
+    toolCalls?: LLMToolCall[];
+    name?: string;
+}
+interface LLMToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+interface InternalAgentContext {
+    sessionId: string;
+    userId: string;
+    agentName: string;
+    history: LLMMessage[];
+    metadata: Record<string, unknown>;
+}
+interface AgentRunOptions {
+    sessionId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AgentRunResult {
+    response: string;
+    sessionId: string;
+    toolsUsed: string[];
+    iterations: number;
+    usage: TokenUsage;
+    duration: number;
+}
+type DocumentType = 'text' | 'markdown' | 'pdf' | 'html' | 'json' | 'docx';
+interface Document {
+    id: string;
+    content: string;
+    type: DocumentType;
+    source: string;
+    metadata: {
+        filename: string;
+        extension: string;
+        size: number;
+        lastModified: string;
+    };
+}
+interface DocumentChunk {
+    id: string;
+    documentId: string;
+    content: string;
+    index: number;
+    metadata: {
+        filename: string;
+        extension: string;
+        size: number;
+        lastModified: string;
+        chunkIndex: number;
+        strategy: 'fixed' | 'sentence' | 'paragraph';
+        charCount: number;
+    };
+}
+interface RAGConfig {
+    embeddings?: {
+        provider: 'openai' | 'ollama';
+        apiKey?: string;
+        model?: string;
+    };
+    chunking?: {
+        strategy?: 'fixed' | 'sentence' | 'paragraph';
+        size?: number;
+        overlap?: number;
+    };
+    retrieval?: {
+        threshold?: number;
+    };
+}
+interface RetrievedContext {
+    chunks: DocumentChunk[];
+    query: string;
+    totalFound: number;
+}
+interface RAGRetriever {
+    init(config: RAGConfig): Promise<void>;
+    addDocuments(filePaths: string[]): Promise<void>;
+    retrieve(query: string, topK?: number): Promise<string>;
+    retrieveChunks(query: string, topK?: number): Promise<RetrievedContext>;
+}
+type ChannelName = 'web' | 'whatsapp' | 'telegram' | 'discord' | 'slack';
+interface IncomingMessage {
+    id: string;
+    sessionId: string;
+    userId: string;
+    channel: ChannelName;
+    text: string;
+    timestamp: Date;
+    raw?: unknown;
+}
+
+/**
+ * @module types
+ * Public types for @yesvara/svara
+ *
+ * These are the types users import and work with directly.
+ * Internal implementation types stay in core/types.ts.
+ */
+
+/**
+ * A function the agent can call during a conversation.
+ *
+ * @example
+ * const weatherTool: Tool = {
+ *   name: 'get_weather',
+ *   description: 'Get the current weather for a city',
+ *   parameters: {
+ *     city: { type: 'string', description: 'The city name', required: true },
+ *   },
+ *   async run({ city }) {
+ *     const data = await fetchWeather(city as string);
+ *     return { temp: data.temp, condition: data.condition };
+ *   },
+ * };
+ */
+interface Tool {
+    /** Unique identifier used by the LLM to call this tool. snake_case recommended. */
+    name: string;
+    /** What this tool does. The LLM uses this to decide when to call it. Be specific. */
+    description: string;
+    /**
+     * Input parameters the tool accepts.
+     * The LLM will fill these in based on the conversation.
+     */
+    parameters?: Record<string, ToolParameter>;
+    /**
+     * The function that runs when the LLM calls this tool.
+     * Return anything — it gets serialized and sent back to the LLM.
+     */
+    run(args: Record<string, unknown>, ctx: AgentContext): Promise<unknown>;
+    /** Group related tools together. Optional — used for organization. */
+    category?: string;
+    /** Timeout in milliseconds before the tool is cancelled. @default 30000 */
+    timeout?: number;
+}
+/**
+ * A single parameter definition for a tool.
+ *
+ * @example
+ * { type: 'string', description: 'City name', required: true }
+ * { type: 'number', description: 'Temperature in Celsius', required: false }
+ * { type: 'string', description: 'Status', enum: ['active', 'inactive'] }
+ */
+interface ToolParameter {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    description: string;
+    required?: boolean;
+    enum?: string[];
+    default?: unknown;
+}
+/**
+ * Context passed to tool `run()` functions.
+ * Gives tools access to session info and conversation history.
+ */
+type AgentContext = InternalAgentContext;
+/**
+ * The full result of a `agent.process()` call.
+ */
+interface ProcessResult {
+    /** The agent's response text. */
+    response: string;
+    /** The session ID used for this conversation. */
+    sessionId: string;
+    /** Names of tools called during this response. */
+    toolsUsed: string[];
+    /** Number of LLM iterations (tool call rounds) used. */
+    iterations: number;
+    /** Token usage for this request. */
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** Total time in milliseconds. */
+    duration: number;
+}
+/**
+ * Memory configuration for a SvaraAgent.
+ */
+interface MemoryOptions {
+    /** Number of previous messages to include in context. @default 20 */
+    window?: number;
+}
+
+/**
+ * @module SvaraAgent
+ *
+ * The heart of the framework. One class. Infinite possibilities.
+ *
+ * A SvaraAgent is a stateful AI agent that:
+ * - Holds a conversation across multiple turns (memory)
+ * - Can search your documents to answer questions (RAG)
+ * - Can call functions you define (tools)
+ * - Can receive messages from any channel (WhatsApp, Telegram, Web, etc.)
+ *
+ * @example Minimal — works in 5 lines
+ * ```ts
+ * const agent = new SvaraAgent({ name: 'Aria', model: 'gpt-4o' });
+ * const reply = await agent.chat('What is the capital of France?');
+ * console.log(reply); // "Paris"
+ * ```
+ *
+ * @example Full — production-ready bot
+ * ```ts
+ * const agent = new SvaraAgent({
+ *   name: 'Support Bot',
+ *   model: 'gpt-4o-mini',
+ *   systemPrompt: 'You are a helpful support agent.',
+ *   knowledge: './docs',
+ *   memory: { window: 20 },
+ * });
+ *
+ * agent
+ *   .addTool(emailTool)
+ *   .addTool(databaseTool)
+ *   .connectChannel('telegram', { token: process.env.TG_TOKEN });
+ *
+ * await agent.start();
+ * ```
+ */
+
+interface SvaraChannel {
+    readonly name: ChannelName;
+    mount(agent: SvaraAgent): Promise<void>;
+    send(sessionId: string, text: string): Promise<void>;
+    stop(): Promise<void>;
+}
+interface AgentConfig {
+    /**
+     * Display name for this agent.
+     * Used in logs, system prompts, and the CLI.
+     */
+    name: string;
+    /**
+     * LLM model to use. Provider is auto-detected from the name.
+     *
+     * @example 'gpt-4o'             — OpenAI (needs OPENAI_API_KEY)
+     * @example 'claude-opus-4-6'   — Anthropic (needs ANTHROPIC_API_KEY)
+     * @example 'llama3'             — Ollama (local, needs Ollama running)
+     * @example 'gpt-4o-mini'        — OpenAI (cheaper, faster)
+     */
+    model: string;
+    /**
+     * Instruction that shapes the agent's personality and behavior.
+     * If omitted, a sensible default is used based on `name`.
+     */
+    systemPrompt?: string;
+    /**
+     * Path(s) to your documents for RAG (Retrieval Augmented Generation).
+     * Supports PDF, Markdown, TXT, DOCX, HTML, JSON. Glob patterns welcome.
+     *
+     * @example './docs'
+     * @example ['./faqs.pdf', './policies/*.md']
+     */
+    knowledge?: string | string[];
+    /**
+     * Conversation memory configuration.
+     * - `true` — enable with defaults (20 message window)
+     * - `false` — disable (stateless, every call is fresh)
+     * - object — custom configuration
+     *
+     * @default true
+     */
+    memory?: boolean | {
+        window?: number;
+    };
+    /**
+     * Tools (function calls) the agent can use.
+     * Can also add tools later with `agent.addTool()`.
+     */
+    tools?: Tool[];
+    /**
+     * LLM temperature — controls creativity vs. precision.
+     * 0 = deterministic, 2 = very creative. Default: 0.7
+     */
+    temperature?: number;
+    /**
+     * Max output tokens per LLM call. Default: provider-dependent.
+     */
+    maxTokens?: number;
+    /**
+     * Maximum agentic loop iterations (tool calls) per message.
+     * Prevents infinite loops. Default: 10
+     */
+    maxIterations?: number;
+    /**
+     * Advanced: override LLM provider or add custom endpoint.
+     * Usually not needed — `model` auto-detects the provider.
+     */
+    llm?: Partial<LLMConfig>;
+    /**
+     * Print detailed logs of every LLM call, tool execution, and memory operation.
+     * Useful during development. Default: false
+     */
+    verbose?: boolean;
+}
+declare class SvaraAgent extends EventEmitter {
+    readonly name: string;
+    private readonly llmConfig;
+    private readonly llm;
+    private readonly systemPrompt;
+    private readonly tools;
+    private readonly executor;
+    private readonly memory;
+    private readonly context;
+    private readonly maxIterations;
+    private readonly verbose;
+    private channels;
+    private knowledgeBase;
+    private knowledgePaths;
+    private isStarted;
+    constructor(config: AgentConfig);
+    /**
+     * Send a message and get a reply. The simplest way to use an agent.
+     *
+     * @example
+     * const reply = await agent.chat('What is the weather in Tokyo?');
+     * console.log(reply); // "Currently 28°C and sunny in Tokyo."
+     *
+     * @param message  The user's message.
+     * @param sessionId  Optional session ID for multi-turn conversations.
+     *                   Defaults to 'default' — all calls share one history.
+     */
+    chat(message: string, sessionId?: string): Promise<string>;
+    /**
+     * Process a message and get the full result with metadata.
+     * Use this when you need usage stats, tool info, or session details.
+     *
+     * @example
+     * const result = await agent.process('Summarize my report', {
+     *   sessionId: 'user-42',
+     *   userId: 'alice@example.com',
+     * });
+     * console.log(result.response);    // The agent's reply
+     * console.log(result.toolsUsed);   // ['read_file', 'summarize']
+     * console.log(result.usage);       // { totalTokens: 1234, ... }
+     */
+    process(message: string, options?: AgentRunOptions): Promise<AgentRunResult>;
+    /**
+     * Register a tool the agent can call during a conversation.
+     * Returns `this` for chaining.
+     *
+     * @example
+     * agent
+     *   .addTool(weatherTool)
+     *   .addTool(emailTool)
+     *   .addTool(databaseTool);
+     */
+    addTool(tool: Tool): this;
+    /**
+     * Connect a messaging channel. The agent will receive and respond to
+     * messages from this channel automatically.
+     *
+     * @example
+     * agent.connectChannel('telegram', { token: process.env.TG_TOKEN });
+     * agent.connectChannel('whatsapp', {
+     *   token: process.env.WA_TOKEN,
+     *   phoneId: process.env.WA_PHONE_ID,
+     *   verifyToken: process.env.WA_VERIFY_TOKEN,
+     * });
+     */
+    connectChannel(name: ChannelName, config: Record<string, unknown>): this;
+    /**
+     * Returns an Express request handler for mounting on any HTTP server.
+     * POST body: `{ message: string, sessionId?: string, userId?: string }`
+     *
+     * @example With SvaraApp
+     * app.route('/chat', agent.handler());
+     *
+     * @example With existing Express app
+     * expressApp.post('/api/chat', agent.handler());
+     */
+    handler(): RequestHandler;
+    /**
+     * Initialize all channels and knowledge base, then start listening.
+     * Call this once after you've configured the agent.
+     *
+     * @example
+     * agent.connectChannel('web', { port: 3000 });
+     * await agent.start(); // "Web channel running at http://localhost:3000"
+     */
+    start(): Promise<void>;
+    /**
+     * Gracefully shut down all channels.
+     */
+    stop(): Promise<void>;
+    /**
+     * Clear conversation history for a session.
+     *
+     * @example
+     * agent.on('user:leave', (userId) => agent.clearHistory(userId));
+     */
+    clearHistory(sessionId: string): Promise<void>;
+    /**
+     * Add documents to the knowledge base at runtime (no restart needed).
+     *
+     * @example
+     * agent.addKnowledge('./new-policies.pdf');
+     */
+    addKnowledge(paths: string | string[]): Promise<void>;
+    /**
+     * Receives a raw incoming message from a channel and processes it.
+     * Called by channel handlers — not typically used directly.
+     */
+    receive(msg: IncomingMessage): Promise<AgentRunResult>;
+    private run;
+    private initKnowledge;
+    private loadChannel;
+    private log;
+}
+
+/**
+ * @module tools
+ *
+ * `createTool` — the elegant way to define tools for your agent.
+ *
+ * @example
+ * ```ts
+ * import { createTool } from '@yesvara/svara';
+ *
+ * const weatherTool = createTool({
+ *   name: 'get_weather',
+ *   description: 'Get the current weather for a location',
+ *   parameters: {
+ *     city: { type: 'string', description: 'City name', required: true },
+ *     units: { type: 'string', description: 'Temperature units', enum: ['celsius', 'fahrenheit'] },
+ *   },
+ *   async run({ city, units = 'celsius' }) {
+ *     const data = await fetchWeather(city as string);
+ *     return { temp: data.temp, condition: data.description, city };
+ *   },
+ * });
+ *
+ * agent.addTool(weatherTool);
+ * ```
+ */
+
+/**
+ * Create a type-safe tool definition with IDE autocomplete.
+ *
+ * This is a convenience wrapper — it validates your tool at definition time
+ * and returns a properly typed `Tool` object.
+ *
+ * @example Basic tool
+ * ```ts
+ * const timeTool = createTool({
+ *   name: 'get_current_time',
+ *   description: 'Get the current date and time',
+ *   parameters: {},
+ *   async run() {
+ *     return { datetime: new Date().toISOString() };
+ *   },
+ * });
+ * ```
+ *
+ * @example Tool with parameters and error handling
+ * ```ts
+ * const searchTool = createTool({
+ *   name: 'search_database',
+ *   description: 'Search for records in the database',
+ *   parameters: {
+ *     query: { type: 'string', description: 'Search query', required: true },
+ *     limit: { type: 'number', description: 'Max results to return' },
+ *   },
+ *   async run({ query, limit = 10 }, ctx) {
+ *     console.log(`[${ctx.agentName}] Searching for: ${query}`);
+ *     const results = await db.search(String(query), Number(limit));
+ *     return { results, count: results.length };
+ *   },
+ *   timeout: 10_000, // 10 seconds
+ * });
+ * ```
+ */
+declare function createTool(definition: Tool): Tool;
+
+/**
+ * @module database/sqlite
+ * SvaraJS — SQLite adapter
+ *
+ * A clean, ergonomic wrapper around better-sqlite3.
+ * Provides typed query helpers, migrations, and a KV store.
+ * Used internally by SvaraJS and optionally exposed to users.
+ *
+ * @example
+ * const db = new SvaraDB('./data/agent.db');
+ *
+ * // Typed queries
+ * const users = db.query<{ id: string; name: string }>(
+ *   'SELECT id, name FROM users WHERE active = ?', [1]
+ * );
+ *
+ * // KV store
+ * db.kv.set('onboarding:done', true);
+ * const done = db.kv.get<boolean>('onboarding:done');
+ *
+ * // Custom tables
+ * db.exec(`CREATE TABLE IF NOT EXISTS orders (id TEXT PRIMARY KEY, ...)`);
+ */
+type Database = {
+    prepare: (sql: string) => Statement;
+    exec: (sql: string) => void;
+    close: () => void;
+    pragma: (pragma: string, options?: {
+        simple?: boolean;
+    }) => unknown;
+    transaction: <T>(fn: () => T) => () => T;
+};
+type Statement = {
+    run: (...args: unknown[]) => {
+        lastInsertRowid: bigint | number;
+        changes: number;
+    };
+    get: (...args: unknown[]) => unknown;
+    all: (...args: unknown[]) => unknown[];
+};
+declare class KVStore {
+    private db;
+    constructor(db: Database);
+    /** Set a key-value pair, with optional TTL in seconds. */
+    set<T>(key: string, value: T, ttlSeconds?: number): void;
+    /** Get a value by key. Returns undefined if not found or expired. */
+    get<T = unknown>(key: string): T | undefined;
+    /** Delete a key. */
+    delete(key: string): void;
+    /** Check if a key exists and is not expired. */
+    has(key: string): boolean;
+    /** Get all keys matching a prefix. */
+    keys(prefix?: string): string[];
+}
+declare class SvaraDB {
+    private db;
+    readonly kv: KVStore;
+    constructor(dbPath?: string);
+    /**
+     * Run a SELECT and return all matching rows.
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    /**
+     * Run a SELECT and return the first matching row.
+     */
+    queryOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | undefined;
+    /**
+     * Run an INSERT/UPDATE/DELETE. Returns affected row count.
+     */
+    run(sql: string, params?: unknown[]): number;
+    /**
+     * Execute raw SQL (for DDL, migrations, etc.).
+     */
+    exec(sql: string): void;
+    /**
+     * Run multiple operations in a single transaction.
+     *
+     * @example
+     * db.transaction(() => {
+     *   db.run('INSERT INTO orders ...', [...]);
+     *   db.run('UPDATE inventory ...', [...]);
+     * });
+     */
+    transaction<T>(fn: () => T): T;
+    /**
+     * Close the database connection.
+     */
+    close(): void;
+    saveMessage(params: {
+        id: string;
+        sessionId: string;
+        role: string;
+        content: string;
+        toolCallId?: string;
+    }): void;
+    getMessages(sessionId: string, limit?: number): Array<{
+        id: string;
+        role: string;
+        content: string;
+        tool_call_id: string | null;
+        created_at: number;
+    }>;
+    clearSession(sessionId: string): void;
+    private openDatabase;
+    private configure;
+    private migrate;
+}
+
+/**
+ * @module channels/web
+ *
+ * HTTP channel — exposes the agent as a REST API with SSE streaming.
+ *
+ * Used automatically when you call:
+ * ```ts
+ * agent.connectChannel('web', { port: 3000 });
+ * ```
+ *
+ * Or mount it on SvaraApp/Express:
+ * ```ts
+ * app.route('/chat', agent.handler());
+ * ```
+ *
+ * API:
+ *   POST /chat       — { message, sessionId? } → { response, sessionId, usage }
+ *   GET  /health     — { status: 'ok' }
+ */
+
+interface WebChannelConfig {
+    port?: number;
+    cors?: boolean | string;
+    apiKey?: string;
+    path?: string;
+}
+declare class WebChannel implements SvaraChannel {
+    private config;
+    readonly name: ChannelName;
+    private app;
+    private server;
+    private agent;
+    constructor(config?: WebChannelConfig);
+    mount(agent: SvaraAgent): Promise<void>;
+    send(_sessionId: string, _text: string): Promise<void>;
+    stop(): Promise<void>;
+    private buildApp;
+    private attachRoutes;
+    private buildMessage;
+}
+
+/**
+ * @module channels/telegram
+ *
+ * Telegram Bot channel.
+ * Used when you call: `agent.connectChannel('telegram', { token: '...' })`
+ */
+
+interface TelegramChannelConfig {
+    token: string;
+    mode?: 'polling' | 'webhook';
+    webhookUrl?: string;
+    pollingInterval?: number;
+}
+declare class TelegramChannel implements SvaraChannel {
+    private config;
+    readonly name: ChannelName;
+    private agent;
+    private baseUrl;
+    private lastUpdateId;
+    private pollingTimer;
+    constructor(config: TelegramChannelConfig);
+    mount(agent: SvaraAgent): Promise<void>;
+    send(sessionId: string, text: string): Promise<void>;
+    stop(): Promise<void>;
+    private startPolling;
+    private handleUpdate;
+    private sendMessage;
+    private api;
+    private split;
+}
+
+/**
+ * @module channels/whatsapp
+ *
+ * WhatsApp Business API channel (Meta Cloud API).
+ * Used when you call: `agent.connectChannel('whatsapp', { ... })`
+ *
+ * Requires the 'web' channel to be mounted first (it shares the Express server).
+ * Webhook endpoint: POST /whatsapp/webhook
+ */
+
+interface WhatsAppChannelConfig {
+    /** WhatsApp Cloud API access token */
+    token: string;
+    /** Your WhatsApp Phone Number ID */
+    phoneId: string;
+    /** Token to verify the webhook with Meta */
+    verifyToken: string;
+    /** API version, default 'v19.0' */
+    apiVersion?: string;
+}
+declare class WhatsAppChannel implements SvaraChannel {
+    private config;
+    readonly name: ChannelName;
+    private agent;
+    private readonly apiUrl;
+    constructor(config: WhatsAppChannelConfig);
+    mount(agent: SvaraAgent): Promise<void>;
+    send(to: string, text: string): Promise<void>;
+    stop(): Promise<void>;
+    private handle;
+    private sendMessage;
+    private split;
+}
+
+/**
+ * @module rag/loader
+ * SvaraJS — Document loader
+ *
+ * Loads documents from various sources into a normalized format.
+ * Supported formats: TXT, MD, PDF, DOCX, HTML, JSON
+ *
+ * @example
+ * const loader = new DocumentLoader();
+ * const docs = await loader.loadMany(['./docs/*.pdf', './knowledge/*.txt']);
+ */
+
+declare class DocumentLoader {
+    private loaders;
+    private extensionMap;
+    constructor();
+    /**
+     * Load a single file into a Document.
+     */
+    load(filePath: string): Promise<Document>;
+    /**
+     * Load multiple files. Silently skips unreadable files with a warning.
+     */
+    loadMany(filePaths: string[]): Promise<Document[]>;
+    /** Check if this loader supports a given file extension. */
+    supports(filePath: string): boolean;
+    private detectType;
+    private hashFile;
+}
+
+/**
+ * @module rag/chunker
+ * SvaraJS — Document chunking strategies
+ *
+ * Breaks documents into retrieval-optimized chunks.
+ * Strategy selection matters: fixed for code/data, sentence for prose, paragraph for docs.
+ *
+ * @example
+ * const chunker = new Chunker({ strategy: 'sentence', size: 512, overlap: 50 });
+ * const chunks = chunker.chunk(document);
+ */
+
+interface ChunkOptions {
+    strategy?: 'fixed' | 'sentence' | 'paragraph';
+    size?: number;
+    overlap?: number;
+}
+declare class Chunker {
+    private options;
+    constructor(options?: ChunkOptions);
+    /**
+     * Split a document into overlapping chunks.
+     * Returns the document with populated `chunks` field.
+     */
+    chunk(document: Document): DocumentChunk[];
+    /**
+     * Chunk multiple documents at once.
+     */
+    chunkMany(documents: Document[]): DocumentChunk[];
+    /** Split into fixed-size windows with overlap. Good for code and structured data. */
+    private fixedChunk;
+    /**
+     * Split by sentences, grouping them until size limit.
+     * Best for prose text — preserves natural reading units.
+     */
+    private sentenceChunk;
+    /**
+     * Split by paragraphs (double newline), grouping small ones.
+     * Best for documentation, articles, and manuals.
+     */
+    private paragraphChunk;
+    private splitSentences;
+    private groupBySize;
+    private chunkId;
+}
+
+/**
+ * @module rag/retriever
+ * SvaraJS — Vector retrieval for RAG
+ *
+ * Embeds document chunks and performs similarity search.
+ * Uses in-memory vector store by default (great for dev),
+ * with SQLite persistence for production.
+ *
+ * @example
+ * const retriever = new VectorRetriever();
+ * await retriever.init({ embeddings: { provider: 'openai' } });
+ * await retriever.addDocuments(['./docs/*.pdf']);
+ *
+ * const context = await retriever.retrieve('What is the refund policy?');
+ */
+
+declare class VectorRetriever implements RAGRetriever {
+    private embedder;
+    private store;
+    private loader;
+    private chunker;
+    private config;
+    constructor();
+    init(config: RAGConfig): Promise<void>;
+    addDocuments(filePaths: string[]): Promise<void>;
+    retrieve(query: string, topK?: number): Promise<string>;
+    retrieveChunks(query: string, topK?: number): Promise<RetrievedContext>;
+}
+
+/**
+ * @yesvara/svara — Agentic AI Backend Framework
+ *
+ * Build production-ready AI agents in minutes, not months.
+ *
+ * @example The 15-line agent
+ * ```ts
+ * import { SvaraApp, SvaraAgent } from '@yesvara/svara';
+ *
+ * const app = new SvaraApp();
+ *
+ * const agent = new SvaraAgent({
+ *   name: 'Support Bot',
+ *   model: 'gpt-4o-mini',
+ *   knowledge: './docs',
+ * });
+ *
+ * app.route('/chat', agent.handler());
+ * app.listen(3000);
+ * ```
+ *
+ * @example With tools and channels
+ * ```ts
+ * import { SvaraAgent, createTool } from '@yesvara/svara';
+ *
+ * const agent = new SvaraAgent({ name: 'Aria', model: 'gpt-4o' });
+ *
+ * agent
+ *   .addTool(createTool({
+ *     name: 'get_time',
+ *     description: 'Get current date and time',
+ *     parameters: {},
+ *     async run() { return { time: new Date().toISOString() }; },
+ *   }))
+ *   .connectChannel('telegram', { token: process.env.TG_TOKEN! })
+ *   .connectChannel('whatsapp', {
+ *     token: process.env.WA_TOKEN!,
+ *     phoneId: process.env.WA_PHONE_ID!,
+ *     verifyToken: process.env.WA_VERIFY_TOKEN!,
+ *   });
+ *
+ * await agent.start();
+ * ```
+ */
+
+declare const VERSION = "0.1.0";
+
+export { type AgentConfig, type AgentContext, type AppOptions, type ChannelName, Chunker, DocumentLoader, type MemoryOptions, type ProcessResult, SvaraAgent, SvaraApp, SvaraDB, TelegramChannel, type TelegramChannelConfig, type Tool, type ToolParameter, VERSION, VectorRetriever, WebChannel, type WebChannelConfig, WhatsAppChannel, type WhatsAppChannelConfig, createTool };