@yesvara/svara 0.1.1 → 0.1.2

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.**
 
@@ -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.

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

package/dist/chunk-GA7LHPOF.mjs

@@ -0,0 +1,257 @@
+import {
+  __require
+} from "./chunk-CIESM3BP.mjs";
+
+// src/database/sqlite.ts
+import path from "path";
+import fs 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:") {
+      fs.mkdirSync(path.dirname(path.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()
+      );
+    }
+  }
+};
+
+export {
+  SvaraDB
+};