@yesvara/svara 0.1.0 → 0.1.2

package/src/cli/commands/db.ts

@@ -0,0 +1,267 @@
+/**
+ * @module cli/commands/db
+ * SvaraJS — Database inspection commands
+ *
+ * Usage:
+ *   svara db:list-chunks [--agent <name>]
+ *   svara db:search <query> [--agent <name>] [--limit 5]
+ *   svara db:stats [--agent <name>]
+ *   svara db:users
+ *   svara db:sessions [--user <email>]
+ */
+
+import { SvaraDB } from '../../database/sqlite.js';
+import type { DocumentChunk } from '../../core/types.js';
+
+interface DBCommandOptions {
+  agent?: string;
+  limit?: number;
+  user?: string;
+}
+
+const db = new SvaraDB('./data/svara.db');
+
+// ── List Chunks ───────────────────────────────────────────────────────────────
+
+export async function listChunks(options: DBCommandOptions): Promise<void> {
+  try {
+    let query = 'SELECT id, agent_name, document_id, content, source FROM svara_chunks';
+    const params: (string | number)[] = [];
+
+    if (options.agent) {
+      query += ' WHERE agent_name = ?';
+      params.push(options.agent);
+    }
+
+    query += ' LIMIT 20';
+
+    const chunks = db.query(query, params) as Array<{
+      id: string;
+      agent_name: string;
+      document_id: string;
+      content: string;
+      source: string;
+    }>;
+
+    if (!chunks.length) {
+      console.log('ℹ️  No chunks found.');
+      return;
+    }
+
+    console.log(`\n📚 Chunks (showing ${chunks.length}):\n`);
+    chunks.forEach((chunk, i) => {
+      const preview = chunk.content.substring(0, 80).replace(/\n/g, ' ');
+      console.log(`${i + 1}. [${chunk.agent_name}] ${chunk.source}`);
+      console.log(`   ID: ${chunk.id}`);
+      console.log(`   Preview: ${preview}...`);
+      console.log('');
+    });
+  } catch (error) {
+    console.error('❌ Error listing chunks:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+// ── Search Chunks ─────────────────────────────────────────────────────────────
+
+export async function searchChunks(query: string, options: DBCommandOptions): Promise<void> {
+  try {
+    const limit = options.limit || 5;
+    let sql = `SELECT id, agent_name, source, content FROM svara_chunks
+               WHERE content LIKE ?`;
+    const params: (string | number)[] = [`%${query}%`];
+
+    if (options.agent) {
+      sql += ' AND agent_name = ?';
+      params.push(options.agent);
+    }
+
+    sql += ` LIMIT ${limit}`;
+
+    const results = db.query(sql, params) as Array<{
+      id: string;
+      agent_name: string;
+      source: string;
+      content: string;
+    }>;
+
+    if (!results.length) {
+      console.log(`ℹ️  No chunks found matching "${query}".`);
+      return;
+    }
+
+    console.log(`\n🔍 Search Results for "${query}" (${results.length} found):\n`);
+    results.forEach((result, i) => {
+      const preview = result.content.substring(0, 100).replace(/\n/g, ' ');
+      console.log(`${i + 1}. [${result.agent_name}] ${result.source}`);
+      console.log(`   ${preview}...`);
+      console.log('');
+    });
+  } catch (error) {
+    console.error('❌ Error searching chunks:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+// ── Database Stats ────────────────────────────────────────────────────────────
+
+export async function dbStats(options: DBCommandOptions): Promise<void> {
+  try {
+    const totalChunks = db.query('SELECT COUNT(*) as count FROM svara_chunks') as Array<{
+      count: number;
+    }>;
+    const totalUsers = db.query('SELECT COUNT(*) as count FROM svara_users') as Array<{
+      count: number;
+    }>;
+    const totalSessions = db.query('SELECT COUNT(*) as count FROM svara_sessions') as Array<{
+      count: number;
+    }>;
+    const totalMessages = db.query('SELECT COUNT(*) as count FROM svara_messages') as Array<{
+      count: number;
+    }>;
+
+    const agents = db.query(
+      'SELECT DISTINCT agent_name, COUNT(*) as chunk_count FROM svara_chunks GROUP BY agent_name'
+    ) as Array<{
+      agent_name: string;
+      chunk_count: number;
+    }>;
+
+    console.log('\n📊 Database Statistics:\n');
+    console.log(`  Total Chunks:   ${totalChunks[0]?.count ?? 0}`);
+    console.log(`  Total Users:    ${totalUsers[0]?.count ?? 0}`);
+    console.log(`  Total Sessions: ${totalSessions[0]?.count ?? 0}`);
+    console.log(`  Total Messages: ${totalMessages[0]?.count ?? 0}`);
+    console.log('\n  Chunks by Agent:');
+
+    if (agents.length === 0) {
+      console.log('    (none)');
+    } else {
+      agents.forEach((agent) => {
+        console.log(`    - ${agent.agent_name}: ${agent.chunk_count} chunks`);
+      });
+    }
+
+    console.log('');
+  } catch (error) {
+    console.error('❌ Error getting stats:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+// ── List Users ────────────────────────────────────────────────────────────────
+
+export async function listUsers(): Promise<void> {
+  try {
+    const users = db.query(
+      'SELECT id, email, display_name, first_seen, last_seen FROM svara_users LIMIT 50'
+    ) as Array<{
+      id: string;
+      email: string;
+      display_name: string;
+      first_seen: string;
+      last_seen: string;
+    }>;
+
+    if (!users.length) {
+      console.log('ℹ️  No users found.');
+      return;
+    }
+
+    console.log(`\n👥 Users (${users.length}):\n`);
+    users.forEach((user) => {
+      console.log(`  ${user.email}`);
+      console.log(`    Name: ${user.display_name || '(none)'}`);
+      console.log(`    First seen: ${user.first_seen}`);
+      console.log(`    Last seen:  ${user.last_seen}`);
+      console.log('');
+    });
+  } catch (error) {
+    console.error('❌ Error listing users:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+// ── List Sessions ─────────────────────────────────────────────────────────────
+
+export async function listSessions(options: DBCommandOptions): Promise<void> {
+  try {
+    let query = `SELECT s.id, s.user_id, s.agent_name, s.created_at, COUNT(m.id) as message_count
+                 FROM svara_sessions s
+                 LEFT JOIN svara_messages m ON s.id = m.session_id`;
+    const params: string[] = [];
+
+    if (options.user) {
+      query += ` WHERE s.user_id = (SELECT id FROM svara_users WHERE email = ?)`;
+      params.push(options.user);
+    }
+
+    query += ' GROUP BY s.id LIMIT 50';
+
+    const sessions = db.query(query, params) as Array<{
+      id: string;
+      user_id: string;
+      agent_name: string;
+      created_at: string;
+      message_count: number;
+    }>;
+
+    if (!sessions.length) {
+      console.log('ℹ️  No sessions found.');
+      return;
+    }
+
+    console.log(`\n💬 Sessions (${sessions.length}):\n`);
+    sessions.forEach((session) => {
+      console.log(`  ID: ${session.id}`);
+      console.log(`    Agent: ${session.agent_name}`);
+      console.log(`    Messages: ${session.message_count}`);
+      console.log(`    Created: ${session.created_at}`);
+      console.log('');
+    });
+  } catch (error) {
+    console.error('❌ Error listing sessions:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+// ── Clear Chunks ──────────────────────────────────────────────────────────────
+
+export async function clearChunks(agentName: string): Promise<void> {
+  try {
+    if (!agentName) {
+      console.error('❌ Agent name required. Usage: svara db:clear-chunks <agent-name>');
+      process.exit(1);
+    }
+
+    const result = db.query('SELECT COUNT(*) as count FROM svara_chunks WHERE agent_name = ?', [
+      agentName,
+    ]) as Array<{
+      count: number;
+    }>;
+    const count = result[0]?.count ?? 0;
+
+    if (count === 0) {
+      console.log(`ℹ️  No chunks found for agent "${agentName}".`);
+      return;
+    }
+
+    console.log(`\n⚠️  About to delete ${count} chunks for agent "${agentName}".`);
+    console.log('Use --yes flag to confirm: svara db:clear-chunks <agent> --yes\n');
+
+    process.exit(0);
+  } catch (error) {
+    console.error('❌ Error clearing chunks:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+export async function clearChunksConfirmed(agentName: string): Promise<void> {
+  try {
+    db.run('DELETE FROM svara_chunks WHERE agent_name = ?', [agentName]);
+    console.log(`✅ Deleted all chunks for agent "${agentName}".`);
+  } catch (error) {
+    console.error('❌ Error deleting chunks:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}

package/src/cli/index.ts

@@ -11,11 +11,12 @@
  */
 
 import { Command } from 'commander';
-import { createRequire } from 'module';
+import path from 'path';
+import fs from 'fs';
 
-const require = createRequire(import.meta.url);
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const pkg = require('../../package.json') as { version: string; description: string };
+// Load package.json (works in both CommonJS and ESM)
+const pkgPath = path.resolve(path.dirname(__filename), '../../package.json');
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as { version: string; description: string };
 
 const program = new Command();
 
@@ -70,6 +71,75 @@ program
     }
   });
 
+// ── svara db:* commands ────────────────────────────────────────────────────────
+
+// svara db:list-chunks
+program
+  .command('db:list-chunks')
+  .description('List all chunks in vector store')
+  .option('--agent <name>', 'Filter by agent name')
+  .action(async (opts: { agent?: string }) => {
+    const { listChunks } = await import('./commands/db.js');
+    await listChunks(opts);
+  });
+
+// svara db:search
+program
+  .command('db:search <query>')
+  .description('Search chunks by content')
+  .option('--agent <name>', 'Filter by agent name')
+  .option('--limit <num>', 'Number of results', '5')
+  .action(async (query: string, opts: { agent?: string; limit: string }) => {
+    const { searchChunks } = await import('./commands/db.js');
+    await searchChunks(query, {
+      agent: opts.agent,
+      limit: parseInt(opts.limit, 10),
+    });
+  });
+
+// svara db:stats
+program
+  .command('db:stats')
+  .description('Show database statistics')
+  .option('--agent <name>', 'Filter by agent name')
+  .action(async (opts: { agent?: string }) => {
+    const { dbStats } = await import('./commands/db.js');
+    await dbStats(opts);
+  });
+
+// svara db:users
+program
+  .command('db:users')
+  .description('List all users in the database')
+  .action(async () => {
+    const { listUsers } = await import('./commands/db.js');
+    await listUsers();
+  });
+
+// svara db:sessions
+program
+  .command('db:sessions')
+  .description('List all sessions in the database')
+  .option('--user <email>', 'Filter by user email')
+  .action(async (opts: { user?: string }) => {
+    const { listSessions } = await import('./commands/db.js');
+    await listSessions(opts);
+  });
+
+// svara db:clear-chunks
+program
+  .command('db:clear-chunks <agent>')
+  .description('Delete all chunks for an agent (requires --yes confirmation)')
+  .option('--yes', 'Confirm deletion')
+  .action(async (agent: string, opts: { yes?: boolean }) => {
+    const { clearChunksConfirmed, clearChunks } = await import('./commands/db.js');
+    if (opts.yes) {
+      await clearChunksConfirmed(agent);
+    } else {
+      await clearChunks(agent);
+    }
+  });
+
 program.parse(process.argv);
 
 // Show help if no command given

package/src/core/agent.ts

@@ -53,6 +53,7 @@ import type {
 import { ConversationMemory } from '../memory/conversation.js';
 import { ContextBuilder } from '../memory/context.js';
 import { ToolRegistry } from '../tools/registry.js';
+import { SvaraDB } from '../database/sqlite.js';
 import { ToolExecutor } from '../tools/executor.js';
 import type { Tool } from '../types.js';
 
@@ -169,8 +170,10 @@ export class SvaraAgent extends EventEmitter {
 
   private channels: Map<ChannelName, SvaraChannel> = new Map();
   private knowledgeBase: KnowledgeBase | null = null;
+  private retriever: any = null; // Store VectorRetriever for retrieveChunks access
   private knowledgePaths: string[] = [];
   private isStarted = false;
+  private db: SvaraDB;
 
   constructor(config: AgentConfig) {
     super();
@@ -178,6 +181,7 @@ export class SvaraAgent extends EventEmitter {
     this.name = config.name;
     this.maxIterations = config.maxIterations ?? 10;
     this.verbose = config.verbose ?? false;
+    this.db = new SvaraDB('./data/svara.db');
 
     this.systemPrompt = config.systemPrompt
       ?? `You are ${config.name}, a helpful and friendly AI assistant. Be concise and accurate.`;
@@ -324,6 +328,7 @@ export class SvaraAgent extends EventEmitter {
           sessionId: result.sessionId,
           usage: result.usage,
           toolsUsed: result.toolsUsed,
+          retrievedDocuments: result.retrievedDocuments || [],
         });
       } catch (err) {
         const error = err as Error;
@@ -405,6 +410,58 @@ export class SvaraAgent extends EventEmitter {
     }
   }
 
+  // ─── Internal: User & Session Tracking ───────────────────────────────────────
+
+  private async trackUserAndSession(userId: string, sessionId: string, channel = 'api'): Promise<void> {
+    try {
+      // Track user
+      const existingUser = this.db.query(
+        'SELECT id FROM svara_users WHERE id = ?',
+        [userId]
+      ) as Array<{ id: string }>;
+
+      if (existingUser.length === 0) {
+        // New user
+        this.db.run(
+          `INSERT INTO svara_users (id, display_name, first_seen, last_seen)
+           VALUES (?, ?, unixepoch(), unixepoch())`,
+          [userId, userId]
+        );
+      } else {
+        // Update last_seen
+        this.db.run(
+          'UPDATE svara_users SET last_seen = unixepoch() WHERE id = ?',
+          [userId]
+        );
+      }
+
+      // Track session
+      const existingSession = this.db.query(
+        'SELECT id FROM svara_sessions WHERE id = ?',
+        [sessionId]
+      ) as Array<{ id: string }>;
+
+      if (existingSession.length === 0) {
+        // New session
+        this.db.run(
+          `INSERT INTO svara_sessions (id, user_id, channel, created_at, updated_at)
+           VALUES (?, ?, ?, unixepoch(), unixepoch())`,
+          [sessionId, userId, channel]
+        );
+      } else {
+        // Update updated_at
+        this.db.run(
+          'UPDATE svara_sessions SET updated_at = unixepoch() WHERE id = ?',
+          [sessionId]
+        );
+      }
+
+      this.log('debug', `Tracked user ${userId} with session ${sessionId}`);
+    } catch (error) {
+      this.log('error', `Failed to track user: ${(error as Error).message}`);
+    }
+  }
+
   // ─── Internal: Agentic Loop ───────────────────────────────────────────────
 
   /**
@@ -419,18 +476,40 @@ export class SvaraAgent extends EventEmitter {
   }
 
   private async run(message: string, options: AgentRunOptions): Promise<AgentRunResult> {
+    console.log(`\n[RUN START] kb=${!!this.knowledgeBase} ret=${!!this.retriever}`);
     const startTime = Date.now();
     const sessionId = options.sessionId ?? crypto.randomUUID();
+    const userId = options.userId ?? 'unknown';
+
+    // Track user and session
+    await this.trackUserAndSession(userId, sessionId);
 
-    this.emit('message:received', { message, sessionId, userId: options.userId });
+    this.emit('message:received', { message, sessionId, userId });
 
     // Build LLM message history
     const history = await this.memory.getHistory(sessionId);
 
     // RAG retrieval
     let ragContext = '';
-    if (this.knowledgeBase) {
+    let retrievedDocuments: Array<{ source: string; score: number; excerpt: string }> = [];
+    if (this.knowledgeBase && this.retriever) {
       ragContext = await this.knowledgeBase.retrieve(message);
+      // Also retrieve chunks to get document metadata and scores
+      try {
+        console.log(`[DEBUG] Calling retrieveChunks for query: "${message}"`);
+        const context = await this.retriever.retrieveChunks(message, 3);
+        console.log(`[DEBUG] Retrieved ${context.chunks.length} chunks`);
+        retrievedDocuments = context.chunks.map((item: any) => ({
+          source: item.chunk?.source || 'unknown',
+          score: Math.round(item.score * 100) / 100,
+          excerpt: item.chunk?.content?.substring(0, 150) || '',
+        }));
+        console.log(`[DEBUG] Mapped ${retrievedDocuments.length} documents`);
+      } catch (e) {
+        console.error(`[ERROR] RAG retrieval failed:`, e);
+      }
+    } else {
+      console.log(`[DEBUG] No knowledgeBase (${!!this.knowledgeBase}) or retriever (${!!this.retriever})`);
     }
 
     const messages = this.context.buildMessages(
@@ -442,7 +521,7 @@ export class SvaraAgent extends EventEmitter {
 
     const internalCtx: InternalAgentContext = {
       sessionId,
-      userId: options.userId ?? 'unknown',
+      userId,
       agentName: this.name,
       history,
       metadata: options.metadata ?? {},
@@ -521,6 +600,7 @@ export class SvaraAgent extends EventEmitter {
       iterations,
       usage: totalUsage,
       duration: Date.now() - startTime,
+      retrievedDocuments: retrievedDocuments.length > 0 ? retrievedDocuments : undefined,
     };
 
     this.emit('message:sent', { response: finalResponse, sessionId });
@@ -534,8 +614,9 @@ export class SvaraAgent extends EventEmitter {
       const { glob } = await import('glob');
       const { VectorRetriever } = await import('../rag/retriever.js');
 
-      const retriever = new VectorRetriever();
-      await retriever.init({ embeddings: { provider: 'openai' } });
+      // Create retriever with agent name for isolated RAG per agent
+      this.retriever = new VectorRetriever(this.name, this.db);
+      await this.retriever.init({ embeddings: { provider: 'openai' } });
 
       const files: string[] = [];
       for (const pattern of paths) {
@@ -548,16 +629,16 @@ export class SvaraAgent extends EventEmitter {
         return;
       }
 
-      await retriever.addDocuments(files);
+      await this.retriever.addDocuments(files);
       this.knowledgeBase = {
         load: async (p) => {
           const newFiles: string[] = [];
           for (const pattern of (Array.isArray(p) ? p : [p])) {
             newFiles.push(...await glob(pattern));
           }
-          await retriever.addDocuments(newFiles);
+          await this.retriever.addDocuments(newFiles);
         },
-        retrieve: (query, topK) => retriever.retrieve(query, topK),
+        retrieve: (query, topK) => this.retriever.retrieve(query, topK),
       };
 
       this.log('info', `Knowledge base loaded: ${files.length} file(s).`);

package/src/core/types.ts

@@ -89,6 +89,12 @@ export interface AgentRunOptions {
   metadata?: Record<string, unknown>;
 }
 
+export interface RetrievedDocument {
+  source: string;
+  score: number;
+  excerpt: string;
+}
+
 export interface AgentRunResult {
   response: string;
   sessionId: string;
@@ -96,6 +102,7 @@ export interface AgentRunResult {
   iterations: number;
   usage: TokenUsage;
   duration: number;
+  retrievedDocuments?: RetrievedDocument[];
 }
 
 // ─── Memory Internals ────────────────────────────────────────────────────────
@@ -127,6 +134,7 @@ export interface DocumentChunk {
   id: string;
   documentId: string;
   content: string;
+  source: string;
   index: number;
   metadata: {
     filename: string;
@@ -155,8 +163,13 @@ export interface RAGConfig {
   };
 }
 
+export interface ChunkWithScore {
+  chunk: DocumentChunk;
+  score: number;
+}
+
 export interface RetrievedContext {
-  chunks: DocumentChunk[];
+  chunks: ChunkWithScore[];
   query: string;
   totalFound: number;
 }

package/src/database/schema.ts

@@ -28,30 +28,55 @@ CREATE TABLE IF NOT EXISTS svara_messages (
 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,
+  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 '{}'
+  metadata    TEXT DEFAULT '{}',
+  FOREIGN KEY (user_id) REFERENCES svara_users(id)
 );
 
--- Vector store chunks for RAG
+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    BLOB,          -- stored as binary float32 array
+  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_document
-  ON svara_chunks (document_id);
+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 (

package/src/rag/chunker.ts

@@ -61,6 +61,7 @@ export class Chunker {
         id: this.chunkId(document.id, index),
         documentId: document.id,
         content: content.trim(),
+        source: document.source,
         index,
         metadata: {
           ...document.metadata,