@yesvara/svara 0.1.0

package/dist/index.js

@@ -0,0 +1,1976 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/rag/loader.ts
+var import_promises, import_path, import_crypto, TextFileLoader, JsonFileLoader, HtmlFileLoader, PdfFileLoader, DocxFileLoader, DocumentLoader;
+var init_loader = __esm({
+  "src/rag/loader.ts"() {
+    "use strict";
+    import_promises = __toESM(require("fs/promises"));
+    import_path = __toESM(require("path"));
+    import_crypto = __toESM(require("crypto"));
+    TextFileLoader = class {
+      extensions = [".txt", ".md", ".mdx", ".rst", ".csv", ".log"];
+      async load(filePath) {
+        return import_promises.default.readFile(filePath, "utf-8");
+      }
+    };
+    JsonFileLoader = class {
+      extensions = [".json", ".jsonl"];
+      async load(filePath) {
+        const raw = await import_promises.default.readFile(filePath, "utf-8");
+        if (import_path.default.extname(filePath) === ".jsonl") {
+          return raw.split("\n").filter(Boolean).map((line) => {
+            const obj = JSON.parse(line);
+            return Object.values(obj).join(" ");
+          }).join("\n");
+        }
+        const data = JSON.parse(raw);
+        return JSON.stringify(data, null, 2);
+      }
+    };
+    HtmlFileLoader = class {
+      extensions = [".html", ".htm"];
+      async load(filePath) {
+        const raw = await import_promises.default.readFile(filePath, "utf-8");
+        return raw.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+      }
+    };
+    PdfFileLoader = class {
+      extensions = [".pdf"];
+      async load(filePath) {
+        try {
+          const pdfParse = require("pdf-parse");
+          const buffer = await import_promises.default.readFile(filePath);
+          const data = await pdfParse(buffer);
+          return data.text;
+        } catch {
+          throw new Error(
+            '[SvaraJS] PDF loading requires the "pdf-parse" package.\nRun: npm install pdf-parse'
+          );
+        }
+      }
+    };
+    DocxFileLoader = class {
+      extensions = [".docx"];
+      async load(filePath) {
+        try {
+          const mammoth = require("mammoth");
+          const result = await mammoth.extractRawText({ path: filePath });
+          return result.value;
+        } catch {
+          throw new Error(
+            '[SvaraJS] DOCX loading requires the "mammoth" package.\nRun: npm install mammoth'
+          );
+        }
+      }
+    };
+    DocumentLoader = class {
+      loaders;
+      extensionMap;
+      constructor() {
+        this.loaders = [
+          new TextFileLoader(),
+          new JsonFileLoader(),
+          new HtmlFileLoader(),
+          new PdfFileLoader(),
+          new DocxFileLoader()
+        ];
+        this.extensionMap = /* @__PURE__ */ new Map();
+        for (const loader of this.loaders) {
+          for (const ext of loader.extensions) {
+            this.extensionMap.set(ext, loader);
+          }
+        }
+      }
+      /**
+       * Load a single file into a Document.
+       */
+      async load(filePath) {
+        const ext = import_path.default.extname(filePath).toLowerCase();
+        const loader = this.extensionMap.get(ext);
+        if (!loader) {
+          throw new Error(
+            `[SvaraJS] Unsupported file type: "${ext}". Supported: ${[...this.extensionMap.keys()].join(", ")}`
+          );
+        }
+        const content = await loader.load(filePath);
+        const stats = await import_promises.default.stat(filePath);
+        return {
+          id: this.hashFile(filePath),
+          content,
+          type: this.detectType(ext),
+          source: filePath,
+          metadata: {
+            filename: import_path.default.basename(filePath),
+            extension: ext,
+            size: stats.size,
+            lastModified: stats.mtime.toISOString()
+          }
+        };
+      }
+      /**
+       * Load multiple files. Silently skips unreadable files with a warning.
+       */
+      async loadMany(filePaths) {
+        const results = [];
+        for (const filePath of filePaths) {
+          try {
+            const doc = await this.load(filePath);
+            results.push(doc);
+          } catch (err) {
+            console.warn(`[SvaraJS:RAG] Skipping "${filePath}": ${err.message}`);
+          }
+        }
+        return results;
+      }
+      /** Check if this loader supports a given file extension. */
+      supports(filePath) {
+        const ext = import_path.default.extname(filePath).toLowerCase();
+        return this.extensionMap.has(ext);
+      }
+      detectType(ext) {
+        const map = {
+          ".txt": "text",
+          ".md": "markdown",
+          ".mdx": "markdown",
+          ".pdf": "pdf",
+          ".html": "html",
+          ".htm": "html",
+          ".json": "json",
+          ".jsonl": "json",
+          ".docx": "docx"
+        };
+        return map[ext] ?? "text";
+      }
+      hashFile(filePath) {
+        return import_crypto.default.createHash("md5").update(filePath).digest("hex");
+      }
+    };
+  }
+});
+
+// src/rag/chunker.ts
+var import_crypto2, Chunker;
+var init_chunker = __esm({
+  "src/rag/chunker.ts"() {
+    "use strict";
+    import_crypto2 = __toESM(require("crypto"));
+    Chunker = class {
+      options;
+      constructor(options = {}) {
+        this.options = {
+          strategy: options.strategy ?? "sentence",
+          size: options.size ?? 2e3,
+          overlap: options.overlap ?? 200
+        };
+      }
+      /**
+       * Split a document into overlapping chunks.
+       * Returns the document with populated `chunks` field.
+       */
+      chunk(document) {
+        const text = document.content.trim();
+        if (!text) return [];
+        let texts;
+        switch (this.options.strategy) {
+          case "fixed":
+            texts = this.fixedChunk(text);
+            break;
+          case "paragraph":
+            texts = this.paragraphChunk(text);
+            break;
+          case "sentence":
+          default:
+            texts = this.sentenceChunk(text);
+            break;
+        }
+        return texts.filter((t) => t.trim().length > 0).map((content, index) => ({
+          id: this.chunkId(document.id, index),
+          documentId: document.id,
+          content: content.trim(),
+          index,
+          metadata: {
+            ...document.metadata,
+            chunkIndex: index,
+            strategy: this.options.strategy,
+            charCount: content.length
+          }
+        }));
+      }
+      /**
+       * Chunk multiple documents at once.
+       */
+      chunkMany(documents) {
+        return documents.flatMap((doc) => this.chunk(doc));
+      }
+      // ─── Strategies ───────────────────────────────────────────────────────────
+      /** Split into fixed-size windows with overlap. Good for code and structured data. */
+      fixedChunk(text) {
+        const { size, overlap } = this.options;
+        const chunks = [];
+        let start = 0;
+        while (start < text.length) {
+          const end = Math.min(start + size, text.length);
+          chunks.push(text.slice(start, end));
+          start += size - overlap;
+        }
+        return chunks;
+      }
+      /**
+       * Split by sentences, grouping them until size limit.
+       * Best for prose text — preserves natural reading units.
+       */
+      sentenceChunk(text) {
+        const sentences = this.splitSentences(text);
+        return this.groupBySize(sentences);
+      }
+      /**
+       * Split by paragraphs (double newline), grouping small ones.
+       * Best for documentation, articles, and manuals.
+       */
+      paragraphChunk(text) {
+        const paragraphs = text.split(/\n{2,}/).map((p) => p.trim()).filter(Boolean);
+        return this.groupBySize(paragraphs);
+      }
+      // ─── Helpers ──────────────────────────────────────────────────────────────
+      splitSentences(text) {
+        return text.split(/(?<=[.!?])\s+(?=[A-Z"'(])/).map((s) => s.trim()).filter(Boolean);
+      }
+      groupBySize(units) {
+        const { size, overlap } = this.options;
+        const chunks = [];
+        let current = "";
+        let overlapBuffer = "";
+        for (const unit of units) {
+          if (current.length + unit.length + 1 > size && current.length > 0) {
+            chunks.push(current);
+            current = overlapBuffer + (overlapBuffer ? " " : "") + unit;
+            overlapBuffer = "";
+          } else {
+            current += (current ? " " : "") + unit;
+          }
+          if (current.length > overlap) {
+            overlapBuffer = current.slice(-overlap);
+          } else {
+            overlapBuffer = current;
+          }
+        }
+        if (current.trim()) chunks.push(current);
+        return chunks;
+      }
+      chunkId(documentId, index) {
+        return import_crypto2.default.createHash("md5").update(`${documentId}:${index}`).digest("hex");
+      }
+    };
+  }
+});
+
+// src/rag/retriever.ts
+var retriever_exports = {};
+__export(retriever_exports, {
+  VectorRetriever: () => VectorRetriever
+});
+function cosineSimilarity(a, b) {
+  if (a.length !== b.length) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+  return denominator === 0 ? 0 : dot / denominator;
+}
+var OpenAIEmbeddings, OllamaEmbeddings, InMemoryVectorStore, VectorRetriever;
+var init_retriever = __esm({
+  "src/rag/retriever.ts"() {
+    "use strict";
+    init_loader();
+    init_chunker();
+    OpenAIEmbeddings = class {
+      client;
+      model;
+      constructor(apiKey, model = "text-embedding-3-small") {
+        this.model = model;
+        try {
+          const { default: OpenAI } = require("openai");
+          this.client = new OpenAI({ apiKey: apiKey ?? process.env.OPENAI_API_KEY });
+        } catch {
+          throw new Error('[SvaraJS] OpenAI embeddings require the "openai" package.');
+        }
+      }
+      async embed(texts) {
+        const client = this.client;
+        const BATCH_SIZE = 100;
+        const results = [];
+        for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+          const batch = texts.slice(i, i + BATCH_SIZE);
+          const response = await client.embeddings.create({
+            model: this.model,
+            input: batch
+          });
+          results.push(...response.data.map((d) => d.embedding));
+        }
+        return results;
+      }
+      async embedOne(text) {
+        const [embedding] = await this.embed([text]);
+        return embedding;
+      }
+    };
+    OllamaEmbeddings = class {
+      baseURL;
+      model;
+      constructor(model = "nomic-embed-text", baseURL = "http://localhost:11434") {
+        this.model = model;
+        this.baseURL = baseURL;
+      }
+      async embed(texts) {
+        return Promise.all(texts.map((t) => this.embedOne(t)));
+      }
+      async embedOne(text) {
+        const response = await fetch(`${this.baseURL}/api/embeddings`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ model: this.model, prompt: text })
+        });
+        if (!response.ok) {
+          throw new Error(`[SvaraJS] Ollama embeddings failed: ${response.statusText}`);
+        }
+        const data = await response.json();
+        return data.embedding;
+      }
+    };
+    InMemoryVectorStore = class {
+      entries = [];
+      add(chunk, embedding) {
+        const existing = this.entries.findIndex((e) => e.chunk.id === chunk.id);
+        if (existing >= 0) {
+          this.entries[existing] = { chunk, embedding };
+        } else {
+          this.entries.push({ chunk, embedding });
+        }
+      }
+      search(queryEmbedding, topK, threshold = 0) {
+        const scored = this.entries.map((entry) => ({
+          chunk: entry.chunk,
+          score: cosineSimilarity(queryEmbedding, entry.embedding)
+        }));
+        return scored.filter((s) => s.score >= threshold).sort((a, b) => b.score - a.score).slice(0, topK).map((s) => s.chunk);
+      }
+      get size() {
+        return this.entries.length;
+      }
+    };
+    VectorRetriever = class {
+      embedder;
+      store;
+      loader;
+      chunker;
+      config;
+      constructor() {
+        this.store = new InMemoryVectorStore();
+        this.loader = new DocumentLoader();
+        this.chunker = new Chunker();
+      }
+      async init(config) {
+        this.config = config;
+        if (config.chunking) {
+          this.chunker = new Chunker({
+            strategy: config.chunking.strategy ?? "sentence",
+            size: config.chunking.size ? config.chunking.size * 4 : 2e3,
+            // rough token→char
+            overlap: config.chunking.overlap ? config.chunking.overlap * 4 : 200
+          });
+        }
+        const emb = config.embeddings ?? { provider: "openai" };
+        switch (emb.provider) {
+          case "openai":
+            this.embedder = new OpenAIEmbeddings(emb.apiKey, emb.model);
+            break;
+          case "ollama":
+            this.embedder = new OllamaEmbeddings(emb.model);
+            break;
+          default:
+            throw new Error(`[SvaraJS] Unknown embeddings provider: "${emb.provider}"`);
+        }
+      }
+      async addDocuments(filePaths) {
+        const documents = await this.loader.loadMany(filePaths);
+        if (!documents.length) return;
+        const chunks = this.chunker.chunkMany(documents);
+        if (!chunks.length) return;
+        console.log(`[SvaraJS:RAG] Embedding ${chunks.length} chunk(s)...`);
+        const embeddings = await this.embedder.embed(chunks.map((c) => c.content));
+        for (let i = 0; i < chunks.length; i++) {
+          this.store.add(chunks[i], embeddings[i]);
+        }
+        console.log(`[SvaraJS:RAG] Vector store now has ${this.store.size} chunk(s).`);
+      }
+      async retrieve(query, topK = 5) {
+        if (this.store.size === 0) return "";
+        const queryEmbedding = await this.embedder.embedOne(query);
+        const threshold = this.config.retrieval?.threshold ?? 0.3;
+        const chunks = this.store.search(queryEmbedding, topK, threshold);
+        if (!chunks.length) return "";
+        return chunks.map((chunk, i) => `[Context ${i + 1}]
+Source: ${String(chunk.metadata.filename ?? chunk.documentId)}
+${chunk.content}`).join("\n\n---\n\n");
+      }
+      async retrieveChunks(query, topK = 5) {
+        const queryEmbedding = await this.embedder.embedOne(query);
+        const threshold = this.config.retrieval?.threshold ?? 0.3;
+        const chunks = this.store.search(queryEmbedding, topK, threshold);
+        return {
+          chunks,
+          query,
+          totalFound: chunks.length
+        };
+      }
+    };
+  }
+});
+
+// src/channels/web.ts
+var web_exports = {};
+__export(web_exports, {
+  WebChannel: () => WebChannel
+});
+var import_express2, WebChannel;
+var init_web = __esm({
+  "src/channels/web.ts"() {
+    "use strict";
+    import_express2 = __toESM(require("express"));
+    WebChannel = class {
+      constructor(config = {}) {
+        this.config = config;
+        this.app = this.buildApp();
+      }
+      config;
+      name = "web";
+      app;
+      server = null;
+      agent;
+      async mount(agent) {
+        this.agent = agent;
+        this.attachRoutes();
+        const port = this.config.port ?? 3e3;
+        return new Promise((resolve, reject) => {
+          this.server = this.app.listen(port, () => {
+            console.log(`[@yesvara/svara] Web channel running at http://localhost:${port}`);
+            resolve();
+          });
+          this.server.on("error", reject);
+        });
+      }
+      async send(_sessionId, _text) {
+      }
+      async stop() {
+        return new Promise((resolve) => {
+          this.server?.close(() => resolve()) ?? resolve();
+        });
+      }
+      // ─── Private ───────────────────────────────────────────────────────────────
+      buildApp() {
+        const app = (0, import_express2.default)();
+        app.use(import_express2.default.json({ limit: "10mb" }));
+        if (this.config.cors) {
+          const origin = this.config.cors === true ? "*" : this.config.cors;
+          app.use((_req, res, next) => {
+            res.setHeader("Access-Control-Allow-Origin", origin);
+            res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS");
+            res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+            next();
+          });
+          app.options("*", (_req, res) => res.sendStatus(204));
+        }
+        if (this.config.apiKey) {
+          app.use((req, res, next) => {
+            const token = req.headers.authorization?.replace("Bearer ", "");
+            if (token !== this.config.apiKey) {
+              res.status(401).json({ error: "Unauthorized" });
+              return;
+            }
+            next();
+          });
+        }
+        return app;
+      }
+      attachRoutes() {
+        const base = this.config.path ?? "";
+        this.app.get(`${base}/health`, (_req, res) => {
+          res.json({ status: "ok", agent: this.agent.name, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+        });
+        this.app.post(`${base}/chat`, this.agent.handler());
+      }
+      buildMessage(body) {
+        return {
+          id: crypto.randomUUID(),
+          sessionId: body.sessionId ?? crypto.randomUUID(),
+          userId: body.userId ?? "web-user",
+          channel: "web",
+          text: body.message,
+          timestamp: /* @__PURE__ */ new Date()
+        };
+      }
+    };
+  }
+});
+
+// src/channels/telegram.ts
+var telegram_exports = {};
+__export(telegram_exports, {
+  TelegramChannel: () => TelegramChannel
+});
+var TelegramChannel;
+var init_telegram = __esm({
+  "src/channels/telegram.ts"() {
+    "use strict";
+    TelegramChannel = class {
+      constructor(config) {
+        this.config = config;
+        if (!config.token) throw new Error("[@yesvara/svara] Telegram requires a bot token.");
+        this.baseUrl = `https://api.telegram.org/bot${config.token}`;
+      }
+      config;
+      name = "telegram";
+      agent;
+      baseUrl;
+      lastUpdateId = 0;
+      pollingTimer = null;
+      async mount(agent) {
+        this.agent = agent;
+        const me = await this.api("getMe");
+        console.log(`[@yesvara/svara] Telegram connected as @${me.username}`);
+        if (this.config.mode === "webhook" && this.config.webhookUrl) {
+          await this.api("setWebhook", { url: `${this.config.webhookUrl}/telegram/webhook` });
+          console.log(`[@yesvara/svara] Telegram webhook registered.`);
+        } else {
+          this.startPolling();
+        }
+      }
+      async send(sessionId, text) {
+        const chatId = parseInt(sessionId, 10);
+        if (!isNaN(chatId)) await this.sendMessage(chatId, text);
+      }
+      async stop() {
+        if (this.pollingTimer) clearInterval(this.pollingTimer);
+      }
+      startPolling() {
+        const interval = this.config.pollingInterval ?? 1e3;
+        console.log("[@yesvara/svara] Telegram polling started...");
+        this.pollingTimer = setInterval(async () => {
+          try {
+            const updates = await this.api("getUpdates", {
+              offset: this.lastUpdateId + 1,
+              allowed_updates: ["message"]
+            });
+            for (const update of updates) {
+              this.lastUpdateId = update.update_id;
+              if (update.message?.text) await this.handleUpdate(update);
+            }
+          } catch {
+          }
+        }, interval);
+      }
+      async handleUpdate(update) {
+        const msg = update.message;
+        const message = {
+          id: String(msg.message_id),
+          sessionId: String(msg.chat.id),
+          userId: String(msg.from.id),
+          channel: "telegram",
+          text: msg.text ?? "",
+          timestamp: new Date(msg.date * 1e3),
+          raw: msg
+        };
+        await this.api("sendChatAction", { chat_id: msg.chat.id, action: "typing" }).catch(() => {
+        });
+        try {
+          const result = await this.agent.receive(message);
+          for (const chunk of this.split(result.response, 4096)) {
+            await this.sendMessage(msg.chat.id, chunk);
+          }
+        } catch (err) {
+          await this.sendMessage(msg.chat.id, "Sorry, something went wrong. Please try again.");
+          console.error("[@yesvara/svara] Telegram error:", err.message);
+        }
+      }
+      async sendMessage(chatId, text) {
+        await this.api("sendMessage", { chat_id: chatId, text, parse_mode: "Markdown" });
+      }
+      async api(method, params) {
+        const res = await fetch(`${this.baseUrl}/${method}`, {
+          method: params ? "POST" : "GET",
+          headers: { "Content-Type": "application/json" },
+          body: params ? JSON.stringify(params) : void 0
+        });
+        const data = await res.json();
+        if (!data.ok) throw new Error(`Telegram API: ${data.description}`);
+        return data.result;
+      }
+      split(text, max) {
+        if (text.length <= max) return [text];
+        const chunks = [];
+        let rest = text;
+        while (rest.length > 0) {
+          chunks.push(rest.slice(0, max));
+          rest = rest.slice(max);
+        }
+        return chunks;
+      }
+    };
+  }
+});
+
+// src/channels/whatsapp.ts
+var whatsapp_exports = {};
+__export(whatsapp_exports, {
+  WhatsAppChannel: () => WhatsAppChannel
+});
+var WhatsAppChannel;
+var init_whatsapp = __esm({
+  "src/channels/whatsapp.ts"() {
+    "use strict";
+    WhatsAppChannel = class {
+      constructor(config) {
+        this.config = config;
+        if (!config.token || !config.phoneId || !config.verifyToken) {
+          throw new Error(
+            "[@yesvara/svara] WhatsApp requires: token, phoneId, and verifyToken."
+          );
+        }
+        const version = config.apiVersion ?? "v19.0";
+        this.apiUrl = `https://graph.facebook.com/${version}/${config.phoneId}`;
+      }
+      config;
+      name = "whatsapp";
+      agent;
+      apiUrl;
+      async mount(agent) {
+        this.agent = agent;
+        const webChannel = agent.channels?.get("web");
+        const app = webChannel?.app;
+        if (!app) {
+          console.warn(
+            '[@yesvara/svara] WhatsApp: no "web" channel found. Add connectChannel("web", ...) before connectChannel("whatsapp", ...) so the webhook can be mounted.'
+          );
+          return;
+        }
+        app.get("/whatsapp/webhook", (req, res) => {
+          const { "hub.mode": mode, "hub.verify_token": token, "hub.challenge": challenge } = req.query;
+          if (mode === "subscribe" && token === this.config.verifyToken) {
+            console.log("[@yesvara/svara] WhatsApp webhook verified.");
+            res.status(200).send(challenge);
+          } else {
+            res.status(403).send("Forbidden");
+          }
+        });
+        app.post("/whatsapp/webhook", async (req, res) => {
+          res.sendStatus(200);
+          if (req.body.object !== "whatsapp_business_account") return;
+          for (const entry of req.body.entry) {
+            for (const change of entry.changes) {
+              for (const waMsg of change.value.messages ?? []) {
+                if (waMsg.type !== "text" || !waMsg.text?.body) continue;
+                await this.handle(waMsg).catch(
+                  (err) => console.error("[@yesvara/svara] WhatsApp error:", err.message)
+                );
+              }
+            }
+          }
+        });
+        console.log("[@yesvara/svara] WhatsApp webhook mounted at /whatsapp/webhook");
+      }
+      async send(to, text) {
+        await this.sendMessage(to, text);
+      }
+      async stop() {
+      }
+      async handle(waMsg) {
+        const message = {
+          id: waMsg.id,
+          sessionId: waMsg.from,
+          userId: waMsg.from,
+          channel: "whatsapp",
+          text: waMsg.text?.body ?? "",
+          timestamp: new Date(parseInt(waMsg.timestamp) * 1e3),
+          raw: waMsg
+        };
+        try {
+          const result = await this.agent.receive(message);
+          for (const chunk of this.split(result.response, 4e3)) {
+            await this.sendMessage(waMsg.from, chunk);
+          }
+        } catch (err) {
+          await this.sendMessage(waMsg.from, "Sorry, something went wrong. Please try again.");
+          throw err;
+        }
+      }
+      async sendMessage(to, text) {
+        const res = await fetch(`${this.apiUrl}/messages`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${this.config.token}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            messaging_product: "whatsapp",
+            to,
+            type: "text",
+            text: { body: text }
+          })
+        });
+        if (!res.ok) {
+          const err = await res.json();
+          throw new Error(`WhatsApp API: ${err.error?.message}`);
+        }
+      }
+      split(text, max) {
+        if (text.length <= max) return [text];
+        const chunks = [];
+        let rest = text;
+        while (rest.length > 0) {
+          chunks.push(rest.slice(0, max));
+          rest = rest.slice(max);
+        }
+        return chunks;
+      }
+    };
+  }
+});
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Chunker: () => Chunker,
+  DocumentLoader: () => DocumentLoader,
+  SvaraAgent: () => SvaraAgent,
+  SvaraApp: () => SvaraApp,
+  SvaraDB: () => SvaraDB,
+  TelegramChannel: () => TelegramChannel,
+  VERSION: () => VERSION,
+  VectorRetriever: () => VectorRetriever,
+  WebChannel: () => WebChannel,
+  WhatsAppChannel: () => WhatsAppChannel,
+  createTool: () => createTool
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/app/index.ts
+var import_express = __toESM(require("express"));
+var import_http = require("http");
+var SvaraApp = class {
+  express;
+  server = null;
+  constructor(options = {}) {
+    this.express = (0, import_express.default)();
+    this.setup(options);
+  }
+  // ─── Public API ────────────────────────────────────────────────────────────
+  /**
+   * 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(path3, handler) {
+    this.express.post(path3, handler);
+    return 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) {
+    this.express.use(middleware);
+    return this;
+  }
+  /**
+   * Start listening on the given port.
+   *
+   * @example
+   * await app.listen(3000);
+   * // → [@yesvara/svara] Listening at http://localhost:3000
+   */
+  listen(port = 3e3) {
+    return new Promise((resolve, reject) => {
+      this.server = (0, import_http.createServer)(this.express);
+      this.server.listen(port, () => {
+        console.log(`[@yesvara/svara] Server running at http://localhost:${port}`);
+        resolve();
+      });
+      this.server.on("error", reject);
+    });
+  }
+  /**
+   * Stop the server gracefully.
+   */
+  stop() {
+    return new Promise((resolve) => {
+      if (this.server) {
+        this.server.close(() => resolve());
+      } else {
+        resolve();
+      }
+    });
+  }
+  /**
+   * Access the underlying Express app for advanced configuration.
+   *
+   * @example
+   * const expressApp = app.express();
+   * expressApp.set('trust proxy', 1);
+   */
+  getExpressApp() {
+    return this.express;
+  }
+  // ─── Private Setup ────────────────────────────────────────────────────────
+  setup(options) {
+    this.express.use(import_express.default.json({ limit: options.bodyLimit ?? "10mb" }));
+    if (options.cors) {
+      this.express.use((_req, res, next) => {
+        const origin = options.cors === true ? "*" : options.cors;
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+        next();
+      });
+      this.express.options("*", (_req, res) => res.sendStatus(204));
+    }
+    if (options.apiKey) {
+      this.express.use((req, res, next) => {
+        const token = req.headers.authorization?.replace("Bearer ", "");
+        if (token !== options.apiKey) {
+          res.status(401).json({ error: "Unauthorized", message: "Invalid API key." });
+          return;
+        }
+        next();
+      });
+    }
+    this.express.get("/health", (_req, res) => {
+      res.json({
+        status: "ok",
+        framework: "@yesvara/svara",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    });
+  }
+};
+
+// src/core/agent.ts
+var import_events = __toESM(require("events"));
+
+// src/core/llm.ts
+var OPENAI_PREFIXES = ["gpt-", "o1", "o3", "text-davinci", "chatgpt"];
+var ANTHROPIC_PREFIXES = ["claude-"];
+var GROQ_MODELS = [
+  "llama-3.1-405b",
+  "llama-3.1-70b",
+  "llama-3.1-8b",
+  "mixtral-8x7b",
+  "gemma-7b",
+  "gemma2-9b"
+];
+function detectProvider(model) {
+  const m = model.toLowerCase();
+  if (OPENAI_PREFIXES.some((p) => m.startsWith(p))) return "openai";
+  if (ANTHROPIC_PREFIXES.some((p) => m.startsWith(p))) return "anthropic";
+  if (GROQ_MODELS.some((gm) => m.includes(gm)) && process.env.GROQ_API_KEY) {
+    return "groq";
+  }
+  return "ollama";
+}
+function resolveConfig(model, overrides = {}) {
+  const provider = overrides.provider ?? detectProvider(model);
+  return {
+    provider,
+    model,
+    temperature: 0.7,
+    timeout: 6e4,
+    ...overrides
+  };
+}
+var OpenAIAdapter = class {
+  constructor(config) {
+    this.config = config;
+    this.client = this.init();
+  }
+  config;
+  client;
+  init() {
+    try {
+      const { default: OpenAI } = require("openai");
+      return new OpenAI({
+        apiKey: this.config.apiKey ?? process.env.OPENAI_API_KEY,
+        baseURL: this.config.baseURL,
+        timeout: this.config.timeout
+      });
+    } catch {
+      throw new SvaraLLMError(
+        "openai",
+        "Package not found. Run: npm install openai"
+      );
+    }
+  }
+  async chat(messages, tools, temperature) {
+    const client = this.client;
+    const response = await client.chat.completions.create({
+      model: this.config.model,
+      messages: messages.map(toOpenAIMessage),
+      tools: tools?.length ? tools.map(toOpenAITool) : void 0,
+      tool_choice: tools?.length ? "auto" : void 0,
+      temperature: temperature ?? this.config.temperature ?? 0.7,
+      max_tokens: this.config.maxTokens
+    });
+    const choice = response.choices[0];
+    const toolCalls = (choice.message.tool_calls ?? []).map((tc) => ({
+      id: tc.id,
+      name: tc.function.name,
+      arguments: safeParseJSON(tc.function.arguments)
+    }));
+    return {
+      content: choice.message.content ?? "",
+      toolCalls: toolCalls.length ? toolCalls : void 0,
+      usage: {
+        promptTokens: response.usage.prompt_tokens,
+        completionTokens: response.usage.completion_tokens,
+        totalTokens: response.usage.total_tokens
+      },
+      model: response.model,
+      finishReason: choice.finish_reason === "tool_calls" ? "tool_calls" : "stop"
+    };
+  }
+  countTokens(text) {
+    return Math.ceil(text.length / 4);
+  }
+};
+var AnthropicAdapter = class {
+  constructor(config) {
+    this.config = config;
+    this.client = this.init();
+  }
+  config;
+  client;
+  init() {
+    try {
+      const { default: Anthropic } = require("@anthropic-ai/sdk");
+      return new Anthropic({
+        apiKey: this.config.apiKey ?? process.env.ANTHROPIC_API_KEY,
+        baseURL: this.config.baseURL,
+        timeout: this.config.timeout
+      });
+    } catch {
+      throw new SvaraLLMError(
+        "anthropic",
+        "Package not found. Run: npm install @anthropic-ai/sdk"
+      );
+    }
+  }
+  async chat(messages, tools, temperature) {
+    const client = this.client;
+    const systemMsg = messages.find((m) => m.role === "system")?.content;
+    const chatMsgs = messages.filter((m) => m.role !== "system").map(toAnthropicMessage);
+    const response = await client.messages.create({
+      model: this.config.model,
+      system: systemMsg,
+      messages: chatMsgs,
+      tools: tools?.length ? tools.map(toAnthropicTool) : void 0,
+      max_tokens: this.config.maxTokens ?? 4096,
+      temperature: temperature ?? this.config.temperature ?? 0.7
+    });
+    const textParts = response.content.filter((c) => c.type === "text");
+    const toolParts = response.content.filter((c) => c.type === "tool_use");
+    const toolCalls = toolParts.map((c) => ({
+      id: c.id,
+      name: c.name,
+      arguments: c.input
+    }));
+    return {
+      content: textParts.map((c) => c.text).join(""),
+      toolCalls: toolCalls.length ? toolCalls : void 0,
+      usage: {
+        promptTokens: response.usage.input_tokens,
+        completionTokens: response.usage.output_tokens,
+        totalTokens: response.usage.input_tokens + response.usage.output_tokens
+      },
+      model: response.model,
+      finishReason: response.stop_reason === "tool_use" ? "tool_calls" : "stop"
+    };
+  }
+  countTokens(text) {
+    return Math.ceil(text.length / 4);
+  }
+};
+var OllamaAdapter = class {
+  constructor(config) {
+    this.config = config;
+    this.baseURL = config.baseURL ?? "http://localhost:11434";
+  }
+  config;
+  baseURL;
+  async chat(messages, _tools, temperature) {
+    const response = await fetch(`${this.baseURL}/api/chat`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: this.config.model,
+        messages: messages.map((m) => ({ role: m.role, content: m.content })),
+        options: { temperature: temperature ?? this.config.temperature ?? 0.7 },
+        stream: false
+      }),
+      signal: AbortSignal.timeout(this.config.timeout ?? 6e4)
+    });
+    if (!response.ok) {
+      throw new SvaraLLMError("ollama", `Request failed: ${response.statusText}. Is Ollama running?`);
+    }
+    const data = await response.json();
+    return {
+      content: data.message.content,
+      usage: {
+        promptTokens: data.prompt_eval_count ?? 0,
+        completionTokens: data.eval_count ?? 0,
+        totalTokens: (data.prompt_eval_count ?? 0) + (data.eval_count ?? 0)
+      },
+      model: data.model ?? this.config.model,
+      finishReason: "stop"
+    };
+  }
+  countTokens(text) {
+    return Math.ceil(text.length / 4);
+  }
+};
+var GroqAdapter = class extends OpenAIAdapter {
+  constructor(config) {
+    super({
+      ...config,
+      baseURL: config.baseURL ?? "https://api.groq.com/openai/v1",
+      apiKey: config.apiKey ?? process.env.GROQ_API_KEY
+    });
+  }
+};
+function createAdapter(config) {
+  switch (config.provider) {
+    case "openai":
+      return new OpenAIAdapter(config);
+    case "anthropic":
+      return new AnthropicAdapter(config);
+    case "ollama":
+      return new OllamaAdapter(config);
+    case "groq":
+      return new GroqAdapter(config);
+    default:
+      throw new Error(
+        `[@yesvara/svara] Unknown LLM provider: "${config.provider}".
+Auto-supported: openai, anthropic, ollama, groq`
+      );
+  }
+}
+function toOpenAIMessage(msg) {
+  if (msg.role === "tool") {
+    return { role: "tool", tool_call_id: msg.toolCallId, content: msg.content };
+  }
+  if (msg.toolCalls?.length) {
+    return {
+      role: "assistant",
+      content: msg.content || null,
+      tool_calls: msg.toolCalls.map((tc) => ({
+        id: tc.id,
+        type: "function",
+        function: { name: tc.name, arguments: JSON.stringify(tc.arguments) }
+      }))
+    };
+  }
+  return { role: msg.role, content: msg.content };
+}
+function toOpenAITool(tool) {
+  return {
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: {
+        type: "object",
+        properties: Object.fromEntries(
+          Object.entries(tool.parameters).map(([k, p]) => [
+            k,
+            { type: p.type, description: p.description, enum: p.enum }
+          ])
+        ),
+        required: Object.entries(tool.parameters).filter(([, p]) => p.required).map(([k]) => k)
+      }
+    }
+  };
+}
+function toAnthropicMessage(msg) {
+  if (msg.role === "tool") {
+    return {
+      role: "user",
+      content: [{ type: "tool_result", tool_use_id: msg.toolCallId, content: msg.content }]
+    };
+  }
+  if (msg.toolCalls?.length) {
+    return {
+      role: "assistant",
+      content: [
+        ...msg.content ? [{ type: "text", text: msg.content }] : [],
+        ...msg.toolCalls.map((tc) => ({
+          type: "tool_use",
+          id: tc.id,
+          name: tc.name,
+          input: tc.arguments
+        }))
+      ]
+    };
+  }
+  return { role: msg.role, content: msg.content };
+}
+function toAnthropicTool(tool) {
+  return {
+    name: tool.name,
+    description: tool.description,
+    input_schema: {
+      type: "object",
+      properties: Object.fromEntries(
+        Object.entries(tool.parameters).map(([k, p]) => [
+          k,
+          { type: p.type, description: p.description, enum: p.enum }
+        ])
+      ),
+      required: Object.entries(tool.parameters).filter(([, p]) => p.required).map(([k]) => k)
+    }
+  };
+}
+var SvaraLLMError = class extends Error {
+  constructor(provider, message) {
+    super(`[@yesvara/svara] LLM error (${provider}): ${message}`);
+    this.provider = provider;
+    this.name = "SvaraLLMError";
+  }
+  provider;
+};
+function safeParseJSON(str) {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return {};
+  }
+}
+
+// src/memory/conversation.ts
+var ConversationMemory = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  sessions = /* @__PURE__ */ new Map();
+  async getHistory(sessionId) {
+    return this.sessions.get(sessionId)?.messages ?? [];
+  }
+  async append(sessionId, messages) {
+    if (this.config.type === "none") return;
+    const store = this.sessions.get(sessionId) ?? {
+      messages: [],
+      createdAt: /* @__PURE__ */ new Date(),
+      updatedAt: /* @__PURE__ */ new Date()
+    };
+    store.messages.push(...messages);
+    store.updatedAt = /* @__PURE__ */ new Date();
+    if (store.messages.length > this.config.maxMessages) {
+      const system = store.messages.filter((m) => m.role === "system");
+      const rest = store.messages.filter((m) => m.role !== "system");
+      store.messages = [...system, ...rest.slice(-this.config.maxMessages)];
+    }
+    this.sessions.set(sessionId, store);
+  }
+  async clear(sessionId) {
+    this.sessions.delete(sessionId);
+  }
+  getSessionIds() {
+    return [...this.sessions.keys()];
+  }
+};
+
+// src/memory/context.ts
+var ContextBuilder = class {
+  constructor(llm) {
+    this.llm = llm;
+  }
+  llm;
+  buildMessages(systemPrompt, history, userMessage, ragContext) {
+    const messages = [
+      { role: "system", content: systemPrompt },
+      // Exclude any system messages from history — we prepend our own
+      ...history.filter((m) => m.role !== "system")
+    ];
+    const content = ragContext ? this.augmentWithRAG(userMessage, ragContext) : userMessage;
+    messages.push({ role: "user", content });
+    return messages;
+  }
+  estimateTokens(messages) {
+    const text = messages.map((m) => m.content).join(" ");
+    return this.llm.countTokens(text);
+  }
+  augmentWithRAG(message, context) {
+    return [
+      "Use the following context to answer the question.",
+      "If the answer isn't in the context, say so honestly \u2014 don't guess.",
+      "",
+      "--- Context ---",
+      context,
+      "--- End Context ---",
+      "",
+      `Question: ${message}`
+    ].join("\n");
+  }
+};
+
+// src/tools/registry.ts
+var ToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  register(tool) {
+    if (this.tools.has(tool.name)) {
+      throw new Error(
+        `[@yesvara/svara] Tool "${tool.name}" is already registered. Use a different name or call registry.update() to replace it.`
+      );
+    }
+    this.tools.set(tool.name, tool);
+  }
+  update(tool) {
+    this.tools.set(tool.name, tool);
+  }
+  unregister(name) {
+    this.tools.delete(name);
+  }
+  get(name) {
+    return this.tools.get(name);
+  }
+  getAll() {
+    return [...this.tools.values()];
+  }
+  has(name) {
+    return this.tools.has(name);
+  }
+  get size() {
+    return this.tools.size;
+  }
+};
+
+// src/tools/executor.ts
+var ToolExecutor = class {
+  constructor(registry) {
+    this.registry = registry;
+  }
+  registry;
+  async execute(call, ctx) {
+    const start = Date.now();
+    const tool = this.registry.get(call.name);
+    if (!tool) {
+      return {
+        toolCallId: call.id,
+        name: call.name,
+        result: null,
+        error: `Tool "${call.name}" is not registered. Available: ${this.registry.getAll().map((t) => t.name).join(", ")}`,
+        duration: Date.now() - start
+      };
+    }
+    try {
+      const result = await Promise.race([
+        tool.run(call.arguments, ctx),
+        this.timeout(tool.timeout ?? 3e4, tool.name)
+      ]);
+      return { toolCallId: call.id, name: call.name, result, duration: Date.now() - start };
+    } catch (err) {
+      const message = err.message;
+      console.error(`[@yesvara/svara] Tool "${call.name}" failed: ${message}`);
+      return {
+        toolCallId: call.id,
+        name: call.name,
+        result: null,
+        error: message,
+        duration: Date.now() - start
+      };
+    }
+  }
+  async executeAll(calls, ctx) {
+    return Promise.all(calls.map((c) => this.execute(c, ctx)));
+  }
+  timeout(ms, name) {
+    return new Promise(
+      (_, reject) => setTimeout(() => reject(new Error(`Tool "${name}" timed out after ${ms}ms`)), ms)
+    );
+  }
+};
+
+// src/core/agent.ts
+var SvaraAgent = class extends import_events.default {
+  name;
+  llmConfig;
+  llm;
+  systemPrompt;
+  tools;
+  executor;
+  memory;
+  context;
+  maxIterations;
+  verbose;
+  channels = /* @__PURE__ */ new Map();
+  knowledgeBase = null;
+  knowledgePaths = [];
+  isStarted = false;
+  constructor(config) {
+    super();
+    this.name = config.name;
+    this.maxIterations = config.maxIterations ?? 10;
+    this.verbose = config.verbose ?? false;
+    this.systemPrompt = config.systemPrompt ?? `You are ${config.name}, a helpful and friendly AI assistant. Be concise and accurate.`;
+    this.llmConfig = resolveConfig(config.model, {
+      temperature: config.temperature,
+      maxTokens: config.maxTokens,
+      ...config.llm
+    });
+    this.llm = createAdapter(this.llmConfig);
+    const memCfg = config.memory ?? true;
+    const window = memCfg === false ? 0 : typeof memCfg === "object" ? memCfg.window ?? 20 : 20;
+    this.memory = new ConversationMemory({ type: "conversation", maxMessages: window });
+    this.context = new ContextBuilder(this.llm);
+    this.tools = new ToolRegistry();
+    this.executor = new ToolExecutor(this.tools);
+    config.tools?.forEach((t) => this.addTool(t));
+    if (config.knowledge) {
+      this.knowledgePaths = Array.isArray(config.knowledge) ? config.knowledge : [config.knowledge];
+    }
+  }
+  // ─── Public API ────────────────────────────────────────────────────────────
+  /**
+   * 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.
+   */
+  async chat(message, sessionId = "default") {
+    const result = await this.run(message, { sessionId });
+    return result.response;
+  }
+  /**
+   * 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, ... }
+   */
+  async process(message, options) {
+    return this.run(message, options ?? {});
+  }
+  /**
+   * Register a tool the agent can call during a conversation.
+   * Returns `this` for chaining.
+   *
+   * @example
+   * agent
+   *   .addTool(weatherTool)
+   *   .addTool(emailTool)
+   *   .addTool(databaseTool);
+   */
+  addTool(tool) {
+    const internal = {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters ?? {},
+      run: tool.run,
+      category: tool.category,
+      timeout: tool.timeout
+    };
+    this.tools.register(internal);
+    return 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, config) {
+    const channel = this.loadChannel(name, config);
+    this.channels.set(name, channel);
+    return 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() {
+    return async (req, res) => {
+      const { message, sessionId, userId } = req.body;
+      if (!message?.trim()) {
+        res.status(400).json({
+          error: "Bad Request",
+          message: 'Request body must include a non-empty "message" field.'
+        });
+        return;
+      }
+      try {
+        const result = await this.run(message, {
+          sessionId: sessionId ?? req.headers["x-session-id"],
+          userId
+        });
+        res.json({
+          response: result.response,
+          sessionId: result.sessionId,
+          usage: result.usage,
+          toolsUsed: result.toolsUsed
+        });
+      } catch (err) {
+        const error = err;
+        this.log("error", error.message);
+        res.status(500).json({ error: "Internal Server Error", message: error.message });
+      }
+    };
+  }
+  /**
+   * 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"
+   */
+  async start() {
+    if (this.isStarted) {
+      console.warn(`[@yesvara/svara] ${this.name} is already running.`);
+      return;
+    }
+    if (this.knowledgePaths.length) {
+      await this.initKnowledge(this.knowledgePaths);
+    }
+    for (const [name, channel] of this.channels) {
+      await channel.mount(this);
+      this.log("info", `Channel "${name}" connected.`);
+      this.emit("channel:ready", { channel: name });
+    }
+    this.isStarted = true;
+    if (this.channels.size === 0) {
+      console.warn(
+        `[@yesvara/svara] ${this.name} has no channels configured.
+  Add one: agent.connectChannel('web', { port: 3000 })`
+      );
+    }
+  }
+  /**
+   * Gracefully shut down all channels.
+   */
+  async stop() {
+    for (const [, channel] of this.channels) {
+      await channel.stop();
+    }
+    this.isStarted = false;
+    this.emit("stopped");
+  }
+  /**
+   * Clear conversation history for a session.
+   *
+   * @example
+   * agent.on('user:leave', (userId) => agent.clearHistory(userId));
+   */
+  async clearHistory(sessionId) {
+    await this.memory.clear(sessionId);
+  }
+  /**
+   * Add documents to the knowledge base at runtime (no restart needed).
+   *
+   * @example
+   * agent.addKnowledge('./new-policies.pdf');
+   */
+  async addKnowledge(paths) {
+    const arr = Array.isArray(paths) ? paths : [paths];
+    if (!this.knowledgeBase) {
+      await this.initKnowledge(arr);
+    } else {
+      await this.knowledgeBase.load(arr);
+    }
+  }
+  // ─── Internal: Agentic Loop ───────────────────────────────────────────────
+  /**
+   * Receives a raw incoming message from a channel and processes it.
+   * Called by channel handlers — not typically used directly.
+   */
+  async receive(msg) {
+    return this.run(msg.text, {
+      sessionId: msg.sessionId,
+      userId: msg.userId
+    });
+  }
+  async run(message, options) {
+    const startTime = Date.now();
+    const sessionId = options.sessionId ?? crypto.randomUUID();
+    this.emit("message:received", { message, sessionId, userId: options.userId });
+    const history = await this.memory.getHistory(sessionId);
+    let ragContext = "";
+    if (this.knowledgeBase) {
+      ragContext = await this.knowledgeBase.retrieve(message);
+    }
+    const messages = this.context.buildMessages(
+      this.systemPrompt,
+      history,
+      message,
+      ragContext
+    );
+    const internalCtx = {
+      sessionId,
+      userId: options.userId ?? "unknown",
+      agentName: this.name,
+      history,
+      metadata: options.metadata ?? {}
+    };
+    const toolsUsed = [];
+    const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    let iterations = 0;
+    let finalResponse = "";
+    while (iterations < this.maxIterations) {
+      iterations++;
+      this.log("debug", `Iteration ${iterations}`);
+      const allTools = this.tools.getAll();
+      const llmResponse = await this.llm.chat(messages, allTools, this.llmConfig.temperature);
+      totalUsage.promptTokens += llmResponse.usage.promptTokens;
+      totalUsage.completionTokens += llmResponse.usage.completionTokens;
+      totalUsage.totalTokens += llmResponse.usage.totalTokens;
+      if (!llmResponse.toolCalls?.length) {
+        finalResponse = llmResponse.content;
+        messages.push({ role: "assistant", content: finalResponse });
+        break;
+      }
+      messages.push({
+        role: "assistant",
+        content: llmResponse.content,
+        toolCalls: llmResponse.toolCalls
+      });
+      this.emit("tool:call", {
+        sessionId,
+        tools: llmResponse.toolCalls.map((tc) => tc.name)
+      });
+      const results = await this.executor.executeAll(llmResponse.toolCalls, internalCtx);
+      for (const result2 of results) {
+        toolsUsed.push(result2.name);
+        const content = result2.error ? `Error executing ${result2.name}: ${result2.error}` : JSON.stringify(result2.result, null, 2);
+        messages.push({
+          role: "tool",
+          content,
+          toolCallId: result2.toolCallId,
+          name: result2.name
+        });
+        this.emit("tool:result", { sessionId, name: result2.name, result: result2.result });
+      }
+    }
+    if (!finalResponse) {
+      finalResponse = `I've reached the reasoning limit for this request. Please try a simpler question.`;
+    }
+    await this.memory.append(sessionId, [
+      { role: "user", content: message },
+      { role: "assistant", content: finalResponse }
+    ]);
+    const result = {
+      response: finalResponse,
+      sessionId,
+      toolsUsed: [...new Set(toolsUsed)],
+      iterations,
+      usage: totalUsage,
+      duration: Date.now() - startTime
+    };
+    this.emit("message:sent", { response: finalResponse, sessionId });
+    return result;
+  }
+  // ─── Private Helpers ──────────────────────────────────────────────────────
+  async initKnowledge(paths) {
+    try {
+      const { glob } = await import("glob");
+      const { VectorRetriever: VectorRetriever2 } = await Promise.resolve().then(() => (init_retriever(), retriever_exports));
+      const retriever = new VectorRetriever2();
+      await retriever.init({ embeddings: { provider: "openai" } });
+      const files = [];
+      for (const pattern of paths) {
+        const matches = await glob(pattern);
+        files.push(...matches);
+      }
+      if (files.length === 0) {
+        console.warn(`[@yesvara/svara] No files found matching: ${paths.join(", ")}`);
+        return;
+      }
+      await retriever.addDocuments(files);
+      this.knowledgeBase = {
+        load: async (p) => {
+          const newFiles = [];
+          for (const pattern of Array.isArray(p) ? p : [p]) {
+            newFiles.push(...await glob(pattern));
+          }
+          await retriever.addDocuments(newFiles);
+        },
+        retrieve: (query, topK) => retriever.retrieve(query, topK)
+      };
+      this.log("info", `Knowledge base loaded: ${files.length} file(s).`);
+    } catch (err) {
+      console.warn(`[@yesvara/svara] Knowledge base init failed: ${err.message}`);
+    }
+  }
+  loadChannel(name, config) {
+    try {
+      switch (name) {
+        case "web": {
+          const { WebChannel: WebChannel2 } = (init_web(), __toCommonJS(web_exports));
+          return new WebChannel2(config);
+        }
+        case "telegram": {
+          const { TelegramChannel: TelegramChannel2 } = (init_telegram(), __toCommonJS(telegram_exports));
+          return new TelegramChannel2(config);
+        }
+        case "whatsapp": {
+          const { WhatsAppChannel: WhatsAppChannel2 } = (init_whatsapp(), __toCommonJS(whatsapp_exports));
+          return new WhatsAppChannel2(config);
+        }
+        default:
+          throw new Error(`Unknown channel: "${name}"`);
+      }
+    } catch (err) {
+      const error = err;
+      if (error.message.startsWith("[@yesvara") || error.message.startsWith("Unknown")) throw error;
+      throw new Error(`[@yesvara/svara] Failed to load channel "${name}": ${error.message}`);
+    }
+  }
+  log(level, msg) {
+    if (level === "error") {
+      console.error(`[@yesvara/svara] ${this.name}: ${msg}`);
+    } else if (this.verbose) {
+      console.log(`[@yesvara/svara] ${this.name}: ${msg}`);
+    }
+  }
+};
+
+// src/tools/index.ts
+function createTool(definition) {
+  if (!definition.name?.trim()) {
+    throw new Error('[@yesvara/svara] createTool: "name" is required.');
+  }
+  if (!definition.description?.trim()) {
+    throw new Error(`[@yesvara/svara] createTool "${definition.name}": "description" is required.`);
+  }
+  if (typeof definition.run !== "function") {
+    throw new Error(`[@yesvara/svara] createTool "${definition.name}": "run" must be a function.`);
+  }
+  if (!/^[a-zA-Z0-9_-]+$/.test(definition.name)) {
+    throw new Error(
+      `[@yesvara/svara] createTool: Invalid tool name "${definition.name}". Use only letters, numbers, underscores, or hyphens.`
+    );
+  }
+  return {
+    parameters: {},
+    ...definition
+  };
+}
+
+// src/database/sqlite.ts
+var import_path2 = __toESM(require("path"));
+var import_fs = __toESM(require("fs"));
+
+// src/database/schema.ts
+var SCHEMA_VERSION = 1;
+var CREATE_TABLES_SQL = `
+-- Schema version tracking
+CREATE TABLE IF NOT EXISTS svara_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+-- Conversation history persistence
+CREATE TABLE IF NOT EXISTS svara_messages (
+  id          TEXT PRIMARY KEY,
+  session_id  TEXT NOT NULL,
+  role        TEXT NOT NULL CHECK(role IN ('user', 'assistant', 'system', 'tool')),
+  content     TEXT NOT NULL,
+  tool_call_id TEXT,
+  created_at  INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_messages_session
+  ON svara_messages (session_id, created_at);
+
+-- Session metadata
+CREATE TABLE IF NOT EXISTS svara_sessions (
+  id          TEXT PRIMARY KEY,
+  user_id     TEXT,
+  channel     TEXT NOT NULL,
+  created_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+  metadata    TEXT DEFAULT '{}'
+);
+
+-- Vector store chunks for RAG
+CREATE TABLE IF NOT EXISTS svara_chunks (
+  id           TEXT PRIMARY KEY,
+  document_id  TEXT NOT NULL,
+  content      TEXT NOT NULL,
+  chunk_index  INTEGER NOT NULL,
+  embedding    BLOB,          -- stored as binary float32 array
+  source       TEXT NOT NULL,
+  metadata     TEXT DEFAULT '{}',
+  created_at   INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_chunks_document
+  ON svara_chunks (document_id);
+
+-- Document registry
+CREATE TABLE IF NOT EXISTS svara_documents (
+  id          TEXT PRIMARY KEY,
+  source      TEXT NOT NULL UNIQUE,
+  type        TEXT NOT NULL,
+  size        INTEGER,
+  hash        TEXT,
+  indexed_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+  metadata    TEXT DEFAULT '{}'
+);
+
+-- Key-value store for arbitrary agent state
+CREATE TABLE IF NOT EXISTS svara_kv (
+  key         TEXT PRIMARY KEY,
+  value       TEXT NOT NULL,
+  expires_at  INTEGER,         -- unix timestamp, NULL = no expiry
+  updated_at  INTEGER NOT NULL DEFAULT (unixepoch())
+);
+`;
+var INSERT_META_SQL = `
+INSERT OR REPLACE INTO svara_meta (key, value)
+VALUES ('schema_version', ?), ('created_at', ?);
+`;
+
+// src/database/sqlite.ts
+var KVStore = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  /** Set a key-value pair, with optional TTL in seconds. */
+  set(key, value, ttlSeconds) {
+    const expiresAt = ttlSeconds ? Math.floor(Date.now() / 1e3) + ttlSeconds : null;
+    this.db.prepare(`
+      INSERT OR REPLACE INTO svara_kv (key, value, expires_at, updated_at)
+      VALUES (?, ?, ?, unixepoch())
+    `).run(key, JSON.stringify(value), expiresAt);
+  }
+  /** Get a value by key. Returns undefined if not found or expired. */
+  get(key) {
+    const row = this.db.prepare(`
+      SELECT value, expires_at FROM svara_kv
+      WHERE key = ? AND (expires_at IS NULL OR expires_at > unixepoch())
+    `).get(key);
+    if (!row) return void 0;
+    return JSON.parse(row.value);
+  }
+  /** Delete a key. */
+  delete(key) {
+    this.db.prepare("DELETE FROM svara_kv WHERE key = ?").run(key);
+  }
+  /** Check if a key exists and is not expired. */
+  has(key) {
+    return this.get(key) !== void 0;
+  }
+  /** Get all keys matching a prefix. */
+  keys(prefix = "") {
+    const rows = this.db.prepare(`
+      SELECT key FROM svara_kv
+      WHERE key LIKE ? AND (expires_at IS NULL OR expires_at > unixepoch())
+    `).all(`${prefix}%`);
+    return rows.map((r) => r.key);
+  }
+};
+var SvaraDB = class {
+  db;
+  kv;
+  constructor(dbPath = ":memory:") {
+    if (dbPath !== ":memory:") {
+      import_fs.default.mkdirSync(import_path2.default.dirname(import_path2.default.resolve(dbPath)), { recursive: true });
+    }
+    this.db = this.openDatabase(dbPath);
+    this.configure();
+    this.migrate();
+    this.kv = new KVStore(this.db);
+  }
+  // ─── Query Helpers ────────────────────────────────────────────────────────
+  /**
+   * Run a SELECT and return all matching rows.
+   */
+  query(sql, params = []) {
+    return this.db.prepare(sql).all(...params);
+  }
+  /**
+   * Run a SELECT and return the first matching row.
+   */
+  queryOne(sql, params = []) {
+    return this.db.prepare(sql).get(...params);
+  }
+  /**
+   * Run an INSERT/UPDATE/DELETE. Returns affected row count.
+   */
+  run(sql, params = []) {
+    return this.db.prepare(sql).run(...params).changes;
+  }
+  /**
+   * Execute raw SQL (for DDL, migrations, etc.).
+   */
+  exec(sql) {
+    this.db.exec(sql);
+  }
+  /**
+   * Run multiple operations in a single transaction.
+   *
+   * @example
+   * db.transaction(() => {
+   *   db.run('INSERT INTO orders ...', [...]);
+   *   db.run('UPDATE inventory ...', [...]);
+   * });
+   */
+  transaction(fn) {
+    return this.db.transaction(fn)();
+  }
+  /**
+   * Close the database connection.
+   */
+  close() {
+    this.db.close();
+  }
+  // ─── Internal Message Storage ─────────────────────────────────────────────
+  saveMessage(params) {
+    this.db.prepare(`
+      INSERT OR REPLACE INTO svara_messages (id, session_id, role, content, tool_call_id)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(
+      params.id,
+      params.sessionId,
+      params.role,
+      params.content,
+      params.toolCallId ?? null
+    );
+  }
+  getMessages(sessionId, limit = 50) {
+    return this.db.prepare(`
+      SELECT id, role, content, tool_call_id, created_at
+      FROM svara_messages
+      WHERE session_id = ?
+      ORDER BY created_at ASC
+      LIMIT ?
+    `).all(sessionId, limit);
+  }
+  clearSession(sessionId) {
+    this.db.prepare("DELETE FROM svara_messages WHERE session_id = ?").run(sessionId);
+  }
+  // ─── Private Setup ────────────────────────────────────────────────────────
+  openDatabase(dbPath) {
+    try {
+      const Database = require("better-sqlite3");
+      return new Database(dbPath);
+    } catch {
+      throw new Error(
+        '[SvaraJS] Database requires the "better-sqlite3" package.\nRun: npm install better-sqlite3'
+      );
+    }
+  }
+  configure() {
+    this.db.pragma("journal_mode = WAL");
+    this.db.pragma("synchronous = NORMAL");
+    this.db.pragma("foreign_keys = ON");
+  }
+  migrate() {
+    this.db.exec(CREATE_TABLES_SQL);
+    const meta = this.db.prepare(
+      "SELECT value FROM svara_meta WHERE key = 'schema_version'"
+    ).get();
+    if (!meta) {
+      this.db.prepare(INSERT_META_SQL).run(
+        String(SCHEMA_VERSION),
+        (/* @__PURE__ */ new Date()).toISOString()
+      );
+    }
+  }
+};
+
+// src/index.ts
+init_web();
+init_telegram();
+init_whatsapp();
+init_loader();
+init_chunker();
+init_retriever();
+var VERSION = "0.1.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Chunker,
+  DocumentLoader,
+  SvaraAgent,
+  SvaraApp,
+  SvaraDB,
+  TelegramChannel,
+  VERSION,
+  VectorRetriever,
+  WebChannel,
+  WhatsAppChannel,
+  createTool
+});