@yesvara/svara 0.1.0

package/src/database/sqlite.ts

@@ -0,0 +1,239 @@
+/**
+ * @module database/sqlite
+ * SvaraJS — SQLite adapter
+ *
+ * A clean, ergonomic wrapper around better-sqlite3.
+ * Provides typed query helpers, migrations, and a KV store.
+ * Used internally by SvaraJS and optionally exposed to users.
+ *
+ * @example
+ * const db = new SvaraDB('./data/agent.db');
+ *
+ * // Typed queries
+ * const users = db.query<{ id: string; name: string }>(
+ *   'SELECT id, name FROM users WHERE active = ?', [1]
+ * );
+ *
+ * // KV store
+ * db.kv.set('onboarding:done', true);
+ * const done = db.kv.get<boolean>('onboarding:done');
+ *
+ * // Custom tables
+ * db.exec(`CREATE TABLE IF NOT EXISTS orders (id TEXT PRIMARY KEY, ...)`);
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { CREATE_TABLES_SQL, INSERT_META_SQL, SCHEMA_VERSION } from './schema.js';
+
+type Database = {
+  prepare: (sql: string) => Statement;
+  exec: (sql: string) => void;
+  close: () => void;
+  pragma: (pragma: string, options?: { simple?: boolean }) => unknown;
+  transaction: <T>(fn: () => T) => () => T;
+};
+
+type Statement = {
+  run: (...args: unknown[]) => { lastInsertRowid: bigint | number; changes: number };
+  get: (...args: unknown[]) => unknown;
+  all: (...args: unknown[]) => unknown[];
+};
+
+// ─── KV Store ─────────────────────────────────────────────────────────────────
+
+class KVStore {
+  constructor(private db: Database) {}
+
+  /** Set a key-value pair, with optional TTL in seconds. */
+  set<T>(key: string, value: T, ttlSeconds?: number): void {
+    const expiresAt = ttlSeconds ? Math.floor(Date.now() / 1000) + 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<T = unknown>(key: string): T | undefined {
+    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) as { value: string; expires_at: number | null } | undefined;
+
+    if (!row) return undefined;
+    return JSON.parse(row.value) as T;
+  }
+
+  /** Delete a key. */
+  delete(key: string): void {
+    this.db.prepare('DELETE FROM svara_kv WHERE key = ?').run(key);
+  }
+
+  /** Check if a key exists and is not expired. */
+  has(key: string): boolean {
+    return this.get(key) !== undefined;
+  }
+
+  /** Get all keys matching a prefix. */
+  keys(prefix = ''): string[] {
+    const rows = this.db.prepare(`
+      SELECT key FROM svara_kv
+      WHERE key LIKE ? AND (expires_at IS NULL OR expires_at > unixepoch())
+    `).all(`${prefix}%`) as Array<{ key: string }>;
+    return rows.map((r) => r.key);
+  }
+}
+
+// ─── SvaraDB ──────────────────────────────────────────────────────────────────
+
+export class SvaraDB {
+  private db: Database;
+  readonly kv: KVStore;
+
+  constructor(dbPath = ':memory:') {
+    // Ensure the directory exists
+    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<T = Record<string, unknown>>(sql: string, params: unknown[] = []): T[] {
+    return this.db.prepare(sql).all(...params) as T[];
+  }
+
+  /**
+   * Run a SELECT and return the first matching row.
+   */
+  queryOne<T = Record<string, unknown>>(sql: string, params: unknown[] = []): T | undefined {
+    return this.db.prepare(sql).get(...params) as T | undefined;
+  }
+
+  /**
+   * Run an INSERT/UPDATE/DELETE. Returns affected row count.
+   */
+  run(sql: string, params: unknown[] = []): number {
+    return this.db.prepare(sql).run(...params).changes;
+  }
+
+  /**
+   * Execute raw SQL (for DDL, migrations, etc.).
+   */
+  exec(sql: string): void {
+    this.db.exec(sql);
+  }
+
+  /**
+   * Run multiple operations in a single transaction.
+   *
+   * @example
+   * db.transaction(() => {
+   *   db.run('INSERT INTO orders ...', [...]);
+   *   db.run('UPDATE inventory ...', [...]);
+   * });
+   */
+  transaction<T>(fn: () => T): T {
+    return this.db.transaction(fn)();
+  }
+
+  /**
+   * Close the database connection.
+   */
+  close(): void {
+    this.db.close();
+  }
+
+  // ─── Internal Message Storage ─────────────────────────────────────────────
+
+  saveMessage(params: {
+    id: string;
+    sessionId: string;
+    role: string;
+    content: string;
+    toolCallId?: string;
+  }): void {
+    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: string, limit = 50): Array<{
+    id: string;
+    role: string;
+    content: string;
+    tool_call_id: string | null;
+    created_at: number;
+  }> {
+    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) as Array<{
+      id: string;
+      role: string;
+      content: string;
+      tool_call_id: string | null;
+      created_at: number;
+    }>;
+  }
+
+  clearSession(sessionId: string): void {
+    this.db.prepare('DELETE FROM svara_messages WHERE session_id = ?').run(sessionId);
+  }
+
+  // ─── Private Setup ────────────────────────────────────────────────────────
+
+  private openDatabase(dbPath: string): Database {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const Database = require('better-sqlite3') as new (path: string) => Database;
+      return new Database(dbPath);
+    } catch {
+      throw new Error(
+        '[SvaraJS] Database requires the "better-sqlite3" package.\n' +
+        'Run: npm install better-sqlite3'
+      );
+    }
+  }
+
+  private configure(): void {
+    // WAL mode = faster writes, better concurrency
+    this.db.pragma('journal_mode = WAL');
+    this.db.pragma('synchronous = NORMAL');
+    this.db.pragma('foreign_keys = ON');
+  }
+
+  private migrate(): void {
+    this.db.exec(CREATE_TABLES_SQL);
+
+    const meta = this.db.prepare(
+      "SELECT value FROM svara_meta WHERE key = 'schema_version'"
+    ).get() as { value: string } | undefined;
+
+    if (!meta) {
+      this.db.prepare(INSERT_META_SQL).run(
+        String(SCHEMA_VERSION),
+        new Date().toISOString()
+      );
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,94 @@
+/**
+ * @yesvara/svara — Agentic AI Backend Framework
+ *
+ * Build production-ready AI agents in minutes, not months.
+ *
+ * @example The 15-line agent
+ * ```ts
+ * import { SvaraApp, SvaraAgent } from '@yesvara/svara';
+ *
+ * const app = new SvaraApp();
+ *
+ * const agent = new SvaraAgent({
+ *   name: 'Support Bot',
+ *   model: 'gpt-4o-mini',
+ *   knowledge: './docs',
+ * });
+ *
+ * app.route('/chat', agent.handler());
+ * app.listen(3000);
+ * ```
+ *
+ * @example With tools and channels
+ * ```ts
+ * import { SvaraAgent, createTool } from '@yesvara/svara';
+ *
+ * const agent = new SvaraAgent({ name: 'Aria', model: 'gpt-4o' });
+ *
+ * agent
+ *   .addTool(createTool({
+ *     name: 'get_time',
+ *     description: 'Get current date and time',
+ *     parameters: {},
+ *     async run() { return { time: new Date().toISOString() }; },
+ *   }))
+ *   .connectChannel('telegram', { token: process.env.TG_TOKEN! })
+ *   .connectChannel('whatsapp', {
+ *     token: process.env.WA_TOKEN!,
+ *     phoneId: process.env.WA_PHONE_ID!,
+ *     verifyToken: process.env.WA_VERIFY_TOKEN!,
+ *   });
+ *
+ * await agent.start();
+ * ```
+ */
+
+// ─── Framework Classes ────────────────────────────────────────────────────────
+
+export { SvaraApp } from './app/index.js';
+export { SvaraAgent } from './core/agent.js';
+
+// ─── Tool Helpers ─────────────────────────────────────────────────────────────
+
+export { createTool } from './tools/index.js';
+
+// ─── Database ─────────────────────────────────────────────────────────────────
+
+export { SvaraDB } from './database/sqlite.js';
+
+// ─── Advanced: Direct Channel Classes ────────────────────────────────────────
+// Most users won't need these — use agent.connectChannel() instead.
+
+export { WebChannel } from './channels/web.js';
+export { TelegramChannel } from './channels/telegram.js';
+export { WhatsAppChannel } from './channels/whatsapp.js';
+
+// ─── Advanced: RAG Components ─────────────────────────────────────────────────
+// For building custom knowledge pipeline integrations.
+
+export { DocumentLoader } from './rag/loader.js';
+export { Chunker } from './rag/chunker.js';
+export { VectorRetriever } from './rag/retriever.js';
+
+// ─── Public Types ─────────────────────────────────────────────────────────────
+
+export type {
+  // The main types you'll use every day
+  AgentConfig,
+  Tool,
+  ToolParameter,
+  AgentContext,
+  ProcessResult,
+  MemoryOptions,
+  AppOptions,
+  ChannelName,
+} from './types.js';
+
+// Channel-specific configs (for advanced usage)
+export type { WebChannelConfig } from './channels/web.js';
+export type { TelegramChannelConfig } from './channels/telegram.js';
+export type { WhatsAppChannelConfig } from './channels/whatsapp.js';
+
+// ─── Version ──────────────────────────────────────────────────────────────────
+
+export const VERSION = '0.1.0';

package/src/memory/context.ts

@@ -0,0 +1,49 @@
+/**
+ * @internal
+ * Builds the messages array sent to the LLM on each call.
+ */
+
+import type { LLMMessage } from '../core/types.js';
+import type { LLMAdapter } from '../core/llm.js';
+
+export class ContextBuilder {
+  constructor(private llm: LLMAdapter) {}
+
+  buildMessages(
+    systemPrompt: string,
+    history: LLMMessage[],
+    userMessage: string,
+    ragContext?: string
+  ): LLMMessage[] {
+    const messages: LLMMessage[] = [
+      { 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: LLMMessage[]): number {
+    const text = messages.map((m) => m.content).join(' ');
+    return this.llm.countTokens(text);
+  }
+
+  private augmentWithRAG(message: string, context: string): string {
+    return [
+      'Use the following context to answer the question.',
+      "If the answer isn't in the context, say so honestly — don't guess.",
+      '',
+      '--- Context ---',
+      context,
+      '--- End Context ---',
+      '',
+      `Question: ${message}`,
+    ].join('\n');
+  }
+}

package/src/memory/conversation.ts

@@ -0,0 +1,51 @@
+/**
+ * @internal
+ * Per-session conversation history store.
+ */
+
+import type { LLMMessage, SessionStore } from '../core/types.js';
+
+export interface MemoryConfig {
+  type: 'conversation' | 'none';
+  maxMessages: number;
+}
+
+export class ConversationMemory {
+  private sessions: Map<string, SessionStore> = new Map();
+
+  constructor(private config: MemoryConfig) {}
+
+  async getHistory(sessionId: string): Promise<LLMMessage[]> {
+    return this.sessions.get(sessionId)?.messages ?? [];
+  }
+
+  async append(sessionId: string, messages: LLMMessage[]): Promise<void> {
+    if (this.config.type === 'none') return;
+
+    const store = this.sessions.get(sessionId) ?? {
+      messages: [],
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    store.messages.push(...messages);
+    store.updatedAt = new Date();
+
+    // Trim to window — always keep system messages
+    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: string): Promise<void> {
+    this.sessions.delete(sessionId);
+  }
+
+  getSessionIds(): string[] {
+    return [...this.sessions.keys()];
+  }
+}

package/src/rag/chunker.ts

@@ -0,0 +1,165 @@
+/**
+ * @module rag/chunker
+ * SvaraJS — Document chunking strategies
+ *
+ * Breaks documents into retrieval-optimized chunks.
+ * Strategy selection matters: fixed for code/data, sentence for prose, paragraph for docs.
+ *
+ * @example
+ * const chunker = new Chunker({ strategy: 'sentence', size: 512, overlap: 50 });
+ * const chunks = chunker.chunk(document);
+ */
+
+import crypto from 'crypto';
+import type { Document, DocumentChunk } from '../core/types.js';
+
+export interface ChunkOptions {
+  strategy?: 'fixed' | 'sentence' | 'paragraph'; // default: 'sentence'
+  size?: number;     // target chunk size in chars (not tokens), default 2000
+  overlap?: number;  // overlap in chars, default 200
+}
+
+// ─── Chunker ──────────────────────────────────────────────────────────────────
+
+export class Chunker {
+  private options: Required<ChunkOptions>;
+
+  constructor(options: ChunkOptions = {}) {
+    this.options = {
+      strategy: options.strategy ?? 'sentence',
+      size: options.size ?? 2000,
+      overlap: options.overlap ?? 200,
+    };
+  }
+
+  /**
+   * Split a document into overlapping chunks.
+   * Returns the document with populated `chunks` field.
+   */
+  chunk(document: Document): DocumentChunk[] {
+    const text = document.content.trim();
+    if (!text) return [];
+
+    let texts: string[];
+
+    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: Document[]): DocumentChunk[] {
+    return documents.flatMap((doc) => this.chunk(doc));
+  }
+
+  // ─── Strategies ───────────────────────────────────────────────────────────
+
+  /** Split into fixed-size windows with overlap. Good for code and structured data. */
+  private fixedChunk(text: string): string[] {
+    const { size, overlap } = this.options;
+    const chunks: string[] = [];
+    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.
+   */
+  private sentenceChunk(text: string): string[] {
+    const sentences = this.splitSentences(text);
+    return this.groupBySize(sentences);
+  }
+
+  /**
+   * Split by paragraphs (double newline), grouping small ones.
+   * Best for documentation, articles, and manuals.
+   */
+  private paragraphChunk(text: string): string[] {
+    const paragraphs = text
+      .split(/\n{2,}/)
+      .map((p) => p.trim())
+      .filter(Boolean);
+
+    return this.groupBySize(paragraphs);
+  }
+
+  // ─── Helpers ──────────────────────────────────────────────────────────────
+
+  private splitSentences(text: string): string[] {
+    // Split on sentence-ending punctuation followed by whitespace
+    // Handles: "Dr. Smith", "U.S.A.", abbreviations reasonably well
+    return text
+      .split(/(?<=[.!?])\s+(?=[A-Z"'(])/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+
+  private groupBySize(units: string[]): string[] {
+    const { size, overlap } = this.options;
+    const chunks: string[] = [];
+    let current = '';
+    let overlapBuffer = '';
+
+    for (const unit of units) {
+      if (current.length + unit.length + 1 > size && current.length > 0) {
+        chunks.push(current);
+        // Start next chunk with overlap
+        current = overlapBuffer + (overlapBuffer ? ' ' : '') + unit;
+        overlapBuffer = '';
+      } else {
+        current += (current ? ' ' : '') + unit;
+      }
+
+      // Build overlap buffer from the tail of current chunk
+      if (current.length > overlap) {
+        overlapBuffer = current.slice(-overlap);
+      } else {
+        overlapBuffer = current;
+      }
+    }
+
+    if (current.trim()) chunks.push(current);
+    return chunks;
+  }
+
+  private chunkId(documentId: string, index: number): string {
+    return crypto
+      .createHash('md5')
+      .update(`${documentId}:${index}`)
+      .digest('hex');
+  }
+}