@yesvara/svara 0.1.1 → 0.1.3

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to SvaraJS
 
-Thanks for your interest in contributing! We welcome all contributions—bug reports, feature requests, documentation improvements, and pull requests.
+Thanks for your interest in contributing! We welcome all contributions such as bug reports, feature requests, documentation improvements, and pull requests.
 
 ## Code of Conduct
 

package/README.md

@@ -1,6 +1,7 @@
 <div align="center">
+<img src="SvaraJS.png" alt="SvaraJS" width="400">
 
-# @yesvara/svara
+<!-- # @yesvara/svara -->
 
 **Build AI agents in 15 lines. Ship to production.**
 
@@ -28,7 +29,7 @@ const app = new SvaraApp();
 const agent = new SvaraAgent({
   name: 'Support Bot',
   model: 'gpt-4o-mini',       // provider auto-detected
-  knowledge: './docs',         // PDF, MD, TXT — just point to a folder
+  knowledge: './docs',         // PDF, MD, TXT, just point to a folder
 });
 
 app.route('/chat', agent.handler());
@@ -43,7 +44,7 @@ That's it. No pipeline setup. No embedding boilerplate. No webhook configuration
 
 ## Features
 
-| | |
+|||
 |---|---|
 | **Zero-config LLM** | Pass a model name, provider is auto-detected |
 | **Instant RAG** | Point to a folder, documents are indexed automatically |
@@ -53,7 +54,7 @@ That's it. No pipeline setup. No embedding boilerplate. No webhook configuration
 | **Express-compatible** | `agent.handler()` drops into any existing app |
 | **Built-in database** | Persistent SQLite for users, sessions, RAG chunks, and state |
 | **RAG per agent** | Each agent has isolated knowledge base, no cross-contamination |
-| **RAG persistence** | Vector embeddings stored in SQLite, survive restarts, auto-dedup |
+| **RAG persistence** | Vector embeddings stored in SQLite, auto-dedup |
 | **User tracking** | Auto-tracks users and sessions with timestamps |
 | **CLI included** | `svara new`, `svara dev`, `svara build` |
 
@@ -262,6 +263,43 @@ await salesBot.start();
 - Deduplication happens per agent (same content in different agents is OK)
 - Perfect for multi-agent systems with different domains
 
+**Accessing Retrieved Documents:**
+
+The `/chat` endpoint returns `retrievedDocuments` showing which knowledge was used:
+
+```ts
+const response = await fetch('http://localhost:3000/chat', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    message: 'What is the pricing?',
+    sessionId: 'user-123'
+  })
+});
+
+const result = await response.json();
+// {
+//   response: "Our pricing starts at...",
+//   retrievedDocuments: [
+//     {
+//       source: "./docs/pricing.md",
+//       score: 0.89,        // relevance (0-1)
+//       excerpt: "# Pricing\n\nOur plans start at..."
+//     },
+//     {
+//       source: "./docs/faq.md",
+//       score: 0.76,
+//       excerpt: "## Is there a free trial?\n\nYes, 14 days..."
+//     }
+//   ]
+// }
+```
+
+The `retrievedDocuments` field shows:
+- **source**: File path of the matching document
+- **score**: Cosine similarity (0-1, higher = more relevant)
+- **excerpt**: First 150 characters of the matched chunk
+
 ### User & Session Tracking
 
 Every message automatically tracks the user and their session.
@@ -321,7 +359,7 @@ agent
     verifyToken: process.env.WA_VERIFY_TOKEN,
   });
 
-await agent.start();
+await agent.start(); // Start all channels
 ```
 
 ### Events
@@ -378,12 +416,15 @@ console.log(reply); // "It's currently 14:32 UTC..."
 const agent = new SvaraAgent({
   name: 'Support Bot',
   model: 'gpt-4o-mini',
-  knowledge: './docs',
+  knowledge: './docs',  // Auto-loaded on first request
   systemPrompt: 'You are a customer support agent. Answer using the documentation.',
   memory: { window: 20 },
 });
 
-await agent.start(); // indexes documents
+const app = new SvaraApp({ cors: true });
+app.route('/chat', agent.handler());
+app.listen(3000);
+// Knowledge indexes automatically on first request
 ```
 
 ### Multi-channel (Web + Telegram + WhatsApp)
@@ -424,21 +465,105 @@ app.listen(3000);
 
 ---
 
+## Adding Knowledge & Tools at Runtime
+
+### Adding knowledge (dynamic indexing)
+
+After the agent is created, add more documents **without restarting**:
+
+```ts
+const agent = new SvaraAgent({
+  name: 'Support Bot',
+  model: 'gpt-4o-mini',
+  knowledge: './docs',  // Initial knowledge
+});
+
+// ── Later (no restart needed) ──────────────────────
+// Add a single document
+await agent.addKnowledge('./policies/new-policy-2024.pdf');
+
+// Add multiple documents
+await agent.addKnowledge(['./faq.md', './terms.txt', './pricing.pdf']);
+
+// Agent immediately has the new knowledge
+```
+
+**Real-world example** — admin endpoint to upload documents:
+
+```ts
+const app = new SvaraApp({ cors: true });
+app.route('/chat', agent.handler());
+
+// Admin: dynamically add knowledge
+app.post('/admin/add-knowledge', async (req, res) => {
+  const { path } = req.body;
+  try {
+    await agent.addKnowledge(path);
+    res.json({ status: 'Knowledge added', path });
+  } catch (err) {
+    res.status(400).json({ error: (err as Error).message });
+  }
+});
+
+app.listen(3000);
+```
+
+### Adding tools (dynamic function calling)
+
+Add tools at runtime with `addTool()`:
+
+```ts
+import { SvaraAgent, createTool } from '@yesvara/svara';
+
+const agent = new SvaraAgent({
+  name: 'Assistant',
+  model: 'gpt-4o-mini',
+  tools: [initialTool],  // Start with one tool
+});
+
+// ── Later ────────────────────────────────────────
+// Add more tools dynamically
+const newTool = createTool({
+  name: 'send_email',
+  description: 'Send an email to a user',
+  parameters: {
+    to: { type: 'string', description: 'Email address', required: true },
+    subject: { type: 'string', description: 'Email subject', required: true },
+    body: { type: 'string', description: 'Email body', required: true },
+  },
+  async run({ to, subject, body }) {
+    // Call your email service
+    return { status: 'sent', to, subject };
+  },
+});
+
+agent.addTool(newTool);
+
+// Agent can now use send_email tool
+```
+
+**Chainable tool registration** (multiple tools):
+
+```ts
+agent
+  .addTool(emailTool)
+  .addTool(databaseTool)
+  .addTool(slackTool)
+  .addTool(webhookTool);
+```
+
+---
+
 ## CLI
 
+### Create a new project
+
 ```bash
-# Scaffold a new project
 svara new my-app
-
-# Start dev server with hot-reload
-svara dev
-
-# Build for production
-svara build
 ```
 
+Output:
 ```
-$ svara new my-app
 ✨ Creating SvaraJS project: my-app
 
   ✓ package.json
@@ -456,6 +581,89 @@ $ svara new my-app
   npm run dev
 ```
 
+Options:
+- `--template <name>` — Use a specific template (default: `basic`)
+  - `basic` — Simple agent with HTTP endpoint
+  - `rag` — RAG-powered agent with document loader
+  - `multi-channel` — Web + Telegram + WhatsApp setup
+  - `tools` — Agent with tool calling examples
+
+### Start development server
+
+```bash
+svara dev
+```
+
+Features:
+- Hot-reload on file changes
+- Auto-restart agent on code updates
+- Debug logging enabled
+- Serves on `http://localhost:3000` (configurable)
+
+Options:
+- `--port <number>` — Custom port (default: `3000`)
+- `--watch <glob>` — Watch additional paths (default: `src/**`)
+- `--env <file>` — Load custom .env file
+
+### Build for production
+
+```bash
+svara build
+```
+
+Outputs:
+- `dist/` — Compiled JavaScript
+- `dist/index.js` — Entry point (ready for Node or Docker)
+- Source maps and type declarations included
+
+Options:
+- `--minify` — Minify output
+- `--sourcemaps` — Include source maps (default: true)
+- `--outdir <path>` — Custom output directory (default: `dist/`)
+
+### Running built projects
+
+```bash
+# After building
+node dist/index.js
+
+# Or with env file
+NODE_ENV=production OPENAI_API_KEY=sk-... node dist/index.js
+```
+
+### Database management
+
+```bash
+# Initialize database (auto-creates tables)
+svara db init
+
+# Show database schema
+svara db schema
+
+# Export users and conversation history
+svara db export --format json
+svara db export --format csv --table svara_messages
+
+# Query database directly
+svara db query "SELECT COUNT(*) FROM svara_users"
+
+# Reset database (⚠️ deletes all data)
+svara db reset
+
+# Backup database
+svara db backup --output backup-2026-01-15.db
+
+# Restore from backup
+svara db restore --input backup-2026-01-15.db
+```
+
+Options:
+- `--db <path>` — Custom database path (default: `./data/svara.db`)
+- `--format <type>` — Export format: `json`, `csv`, `sql` (default: `json`)
+- `--table <name>` — Specific table to export
+- `--output <path>` — Output file path
+- `--force` — Skip confirmation prompts (use with `reset` carefully!)
+
 ---
 
 ## Built-in Database

package/dist/{chunk-WA3BIA3S.mjs → chunk-CCNWHBEI.mjs}

@@ -1,3 +1,6 @@
+import {
+  SvaraDB
+} from "./chunk-GA7LHPOF.mjs";
 import {
   __require
 } from "./chunk-CIESM3BP.mjs";
@@ -256,256 +259,6 @@ var Chunker = class {
   }
 };
 
-// src/database/sqlite.ts
-import path2 from "path";
-import fs2 from "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);
-
--- User registry
-CREATE TABLE IF NOT EXISTS svara_users (
-  id          TEXT PRIMARY KEY,
-  email       TEXT,
-  display_name TEXT,
-  first_seen  INTEGER NOT NULL DEFAULT (unixepoch()),
-  last_seen   INTEGER NOT NULL DEFAULT (unixepoch()),
-  metadata    TEXT DEFAULT '{}'
-);
-
-CREATE INDEX IF NOT EXISTS idx_users_email
-  ON svara_users (email);
-
--- Session metadata
-CREATE TABLE IF NOT EXISTS svara_sessions (
-  id          TEXT PRIMARY KEY,
-  user_id     TEXT NOT NULL,
-  channel     TEXT NOT NULL,
-  created_at  INTEGER NOT NULL DEFAULT (unixepoch()),
-  updated_at  INTEGER NOT NULL DEFAULT (unixepoch()),
-  metadata    TEXT DEFAULT '{}',
-  FOREIGN KEY (user_id) REFERENCES svara_users(id)
-);
-
-CREATE INDEX IF NOT EXISTS idx_sessions_user
-  ON svara_sessions (user_id);
-
--- Vector store chunks for RAG (per agent)
-CREATE TABLE IF NOT EXISTS svara_chunks (
-  id           TEXT PRIMARY KEY,
-  agent_name   TEXT NOT NULL,   -- Separate RAG per agent
-  document_id  TEXT NOT NULL,
-  content      TEXT NOT NULL,
-  content_hash TEXT NOT NULL,   -- MD5 hash of content for deduplication
-  chunk_index  INTEGER NOT NULL,
-  embedding    TEXT,            -- stored as JSON string of float array
-  source       TEXT NOT NULL,
-  metadata     TEXT DEFAULT '{}',
-  created_at   INTEGER NOT NULL DEFAULT (unixepoch())
-);
-
-CREATE INDEX IF NOT EXISTS idx_chunks_agent
-  ON svara_chunks (agent_name);
-
-CREATE INDEX IF NOT EXISTS idx_chunks_agent_document
-  ON svara_chunks (agent_name, document_id);
-
-CREATE INDEX IF NOT EXISTS idx_chunks_content_hash
-  ON svara_chunks (content_hash);
-
--- 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:") {
-      fs2.mkdirSync(path2.dirname(path2.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/rag/retriever.ts
 import crypto3 from "crypto";
 var OpenAIEmbeddings = class {
@@ -740,7 +493,6 @@ function cosineSimilarity(a, b) {
 }
 
 export {
-  SvaraDB,
   DocumentLoader,
   Chunker,
   VectorRetriever