@yesvara/svara 0.1.0

package/dist/new-7K4NIDZO.mjs

@@ -0,0 +1,177 @@
+import "./chunk-CIESM3BP.mjs";
+
+// src/cli/commands/new.ts
+import fs from "fs/promises";
+import path from "path";
+import { execSync } from "child_process";
+async function newProject(options) {
+  const { name, provider = "openai", channels = ["web"] } = options;
+  const targetDir = path.resolve(process.cwd(), name);
+  console.log(`
+\u2728 Creating SvaraJS project: ${name}
+`);
+  try {
+    await fs.access(targetDir);
+    console.error(`\u274C Directory "${name}" already exists.`);
+    process.exit(1);
+  } catch {
+  }
+  await fs.mkdir(targetDir, { recursive: true });
+  await fs.mkdir(path.join(targetDir, "src"), { recursive: true });
+  await fs.mkdir(path.join(targetDir, "docs"), { recursive: true });
+  await fs.mkdir(path.join(targetDir, "data"), { recursive: true });
+  const files = {
+    "package.json": generatePackageJson(name),
+    "tsconfig.json": generateTsConfig(),
+    ".env.example": generateEnvExample(provider, channels),
+    ".gitignore": generateGitignore(),
+    "src/index.ts": generateIndexFile(name, provider, channels),
+    "docs/README.md": `# ${name} Knowledge Base
+
+Add your documents here for RAG.
+`
+  };
+  for (const [filePath, content] of Object.entries(files)) {
+    const fullPath = path.join(targetDir, filePath);
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    await fs.writeFile(fullPath, content, "utf-8");
+    console.log(`  \u2713 ${filePath}`);
+  }
+  if (options.installDeps !== false) {
+    console.log("\n\u{1F4E6} Installing dependencies...\n");
+    try {
+      execSync("npm install", { cwd: targetDir, stdio: "inherit" });
+    } catch {
+      console.warn('\n\u26A0\uFE0F  Dependency install failed. Run "npm install" manually.\n');
+    }
+  }
+  console.log(`
+\u2705 Project ready!
+
+  cd ${name}
+  cp .env.example .env     # Add your API keys
+  npm run dev              # Start the agent
+
+\u{1F4DA} Docs: https://svarajs.dev
+`);
+}
+function generatePackageJson(name) {
+  return JSON.stringify({
+    name,
+    version: "0.1.0",
+    private: true,
+    scripts: {
+      dev: "tsx watch src/index.ts",
+      build: "tsc",
+      start: "node dist/index.js"
+    },
+    dependencies: {
+      svarajs: "latest",
+      dotenv: "^16.4.5"
+    },
+    devDependencies: {
+      "@types/node": "^20.14.2",
+      tsx: "^4.15.7",
+      typescript: "^5.4.5"
+    }
+  }, null, 2);
+}
+function generateTsConfig() {
+  return JSON.stringify({
+    compilerOptions: {
+      target: "ES2022",
+      module: "CommonJS",
+      moduleResolution: "bundler",
+      outDir: "dist",
+      rootDir: "src",
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true
+    },
+    include: ["src/**/*"],
+    exclude: ["node_modules", "dist"]
+  }, null, 2);
+}
+function generateEnvExample(provider, channels) {
+  const lines = ["# SvaraJS Environment Variables", ""];
+  if (provider === "openai") {
+    lines.push("# OpenAI", "OPENAI_API_KEY=sk-...", "");
+  } else if (provider === "anthropic") {
+    lines.push("# Anthropic", "ANTHROPIC_API_KEY=sk-ant-...", "");
+  }
+  if (channels.includes("telegram")) {
+    lines.push("# Telegram", "TELEGRAM_BOT_TOKEN=...", "");
+  }
+  if (channels.includes("whatsapp")) {
+    lines.push("# WhatsApp", "WA_ACCESS_TOKEN=...", "WA_PHONE_ID=...", "WA_VERIFY_TOKEN=...", "");
+  }
+  return lines.join("\n");
+}
+function generateIndexFile(name, provider, channels) {
+  const modelMap = {
+    openai: "gpt-4o",
+    anthropic: "claude-opus-4-6",
+    ollama: "llama3"
+  };
+  const channelSetup = channels.map((ch) => {
+    if (ch === "web") return `agent.use('web', { port: 3000, cors: true });`;
+    if (ch === "telegram") return `agent.use('telegram', { token: process.env.TELEGRAM_BOT_TOKEN! });`;
+    if (ch === "whatsapp") return [
+      `agent.use('whatsapp', {`,
+      `  token: process.env.WA_ACCESS_TOKEN!,`,
+      `  phoneId: process.env.WA_PHONE_ID!,`,
+      `  verifyToken: process.env.WA_VERIFY_TOKEN!,`,
+      `});`
+    ].join("\n");
+    return "";
+  }).filter(Boolean).join("\n");
+  return `import 'dotenv/config';
+import { svara } from 'svarajs';
+
+/**
+ * ${name} \u2014 powered by SvaraJS
+ */
+const agent = svara({
+  llm: {
+    provider: '${provider}',
+    model: '${modelMap[provider] ?? "gpt-4o"}',
+  },
+  systemPrompt: \`You are a helpful AI assistant called ${name}.
+Be concise, friendly, and always try your best to help.\`,
+  memory: {
+    type: 'conversation',
+    maxMessages: 20,
+  },
+  verbose: true,
+});
+
+// \u2500\u2500 Tools \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+agent.tool('get_time', {
+  description: 'Get the current date and time',
+  parameters: {},
+  execute: async () => ({
+    datetime: new Date().toISOString(),
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+  }),
+});
+
+// \u2500\u2500 Channels \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+${channelSetup}
+
+// \u2500\u2500 Start \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+agent.start().then(() => {
+  console.log('\u{1F680} ${name} is running!');
+});
+`;
+}
+function generateGitignore() {
+  return `node_modules/
+dist/
+.env
+data/*.db
+*.log
+`;
+}
+export {
+  newProject
+};

package/dist/retriever-4QY667XF.mjs

@@ -0,0 +1,7 @@
+import {
+  VectorRetriever
+} from "./chunk-FEA5KIJN.mjs";
+import "./chunk-CIESM3BP.mjs";
+export {
+  VectorRetriever
+};

package/examples/01-basic/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @example Basic Agent
+ *
+ * The simplest possible SvaraJS agent.
+ * 10 lines. Works out of the box.
+ *
+ * Run: npx tsx index.ts
+ *
+ * curl -X POST http://localhost:3000/chat \
+ *   -H "Content-Type: application/json" \
+ *   -d '{ "message": "Hello! What can you do?" }'
+ */
+
+import 'dotenv/config';
+import { SvaraApp, SvaraAgent } from '@yesvara/svara';
+
+const app = new SvaraApp({ cors: true });
+
+const agent = new SvaraAgent({
+  name: 'Aria',
+  model: 'gpt-4o-mini',
+  systemPrompt: 'You are Aria, a friendly and helpful AI assistant. Keep responses concise.',
+});
+
+app.route('/chat', agent.handler());
+app.listen(3000);

package/examples/02-with-tools/index.ts

@@ -0,0 +1,73 @@
+/**
+ * @example Agent with Tools
+ *
+ * An agent that can call custom functions (tools).
+ * The LLM decides when to call each tool based on the conversation.
+ *
+ * Run: npx tsx index.ts
+ *
+ * curl -X POST http://localhost:3000/chat \
+ *   -H "Content-Type: application/json" \
+ *   -d '{ "message": "What time is it? Also, what is 42 * 17?", "sessionId": "user-1" }'
+ */
+
+import 'dotenv/config';
+import { SvaraApp, SvaraAgent, createTool } from '@yesvara/svara';
+
+// ── Define Tools ──────────────────────────────────────────────────────────────
+
+const getCurrentTime = createTool({
+  name: 'get_current_time',
+  description: 'Get the current date and time in a specific timezone',
+  parameters: {
+    timezone: {
+      type: 'string',
+      description: 'IANA timezone name, e.g. "Asia/Jakarta", "America/New_York"',
+    },
+  },
+  async run({ timezone = 'UTC' }) {
+    return {
+      datetime: new Date().toLocaleString('en-US', { timeZone: timezone as string }),
+      timezone,
+    };
+  },
+});
+
+const calculate = createTool({
+  name: 'calculate',
+  description: 'Evaluate a safe mathematical expression',
+  parameters: {
+    expression: {
+      type: 'string',
+      description: 'Math expression to evaluate, e.g. "42 * 17", "(100 + 50) / 3"',
+      required: true,
+    },
+  },
+  async run({ expression }) {
+    // Very simple safe eval — in production use a proper math library
+    const result = Function(`"use strict"; return (${expression as string})`)() as number;
+    return { expression, result };
+  },
+  timeout: 5_000,
+});
+
+// ── Create Agent ──────────────────────────────────────────────────────────────
+
+const agent = new SvaraAgent({
+  name: 'Calculator Bot',
+  model: 'gpt-4o-mini',
+  systemPrompt: 'You are a helpful assistant with access to real-time data and calculation tools.',
+  memory: { window: 10 },
+  tools: [getCurrentTime, calculate],
+});
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+const app = new SvaraApp({ cors: true });
+app.route('/chat', agent.handler());
+app.listen(3000);
+
+// Observe tool usage
+agent.on('tool:call', ({ tools }: { tools: string[] }) => {
+  console.log(`[Tools] Calling: ${tools.join(', ')}`);
+});

package/examples/03-rag-knowledge/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @example RAG Knowledge Base Agent
+ *
+ * An agent that answers questions from your documents.
+ * Drop files in ./docs and the agent knows everything in them.
+ *
+ * Supported: PDF, Markdown, TXT, DOCX, HTML, JSON
+ *
+ * Run: npx tsx index.ts
+ *
+ * curl -X POST http://localhost:3000/chat \
+ *   -H "Content-Type: application/json" \
+ *   -d '{ "message": "What is our refund policy?", "sessionId": "customer-42" }'
+ */
+
+import 'dotenv/config';
+import { SvaraApp, SvaraAgent } from '@yesvara/svara';
+
+const agent = new SvaraAgent({
+  name: 'Knowledge Base Bot',
+  model: 'gpt-4o-mini',
+
+  systemPrompt: `You are a helpful customer support agent.
+Answer questions using the provided documentation.
+If you don't know the answer, say so honestly — don't make things up.
+Always be friendly and professional.`,
+
+  // Point to your docs folder — any file type, glob patterns work
+  knowledge: './docs/**/*',
+
+  memory: { window: 20 },
+});
+
+// You can also add knowledge dynamically (hot reload, no restart needed)
+// await agent.addKnowledge('./new-policy-2024.pdf');
+
+const app = new SvaraApp({ cors: true });
+app.route('/chat', agent.handler());
+
+await agent.start(); // indexes documents
+app.listen(3000);

package/examples/04-multi-channel/index.ts

@@ -0,0 +1,91 @@
+/**
+ * @example Multi-Channel Agent
+ *
+ * One agent, three channels. Same conversations, everywhere.
+ * Customers can reach you on WhatsApp, Telegram, or the web —
+ * the agent handles all of them seamlessly.
+ *
+ * Setup:
+ *   1. Copy .env.example → .env and fill in your keys
+ *   2. Run: npx tsx index.ts
+ *   3. Expose with: npx localtunnel --port 3000
+ *   4. Register the tunnel URL as your Telegram/WhatsApp webhook
+ */
+
+import 'dotenv/config';
+import { SvaraAgent, createTool } from '@yesvara/svara';
+
+// ── Tools ─────────────────────────────────────────────────────────────────────
+
+const orderStatus = createTool({
+  name: 'get_order_status',
+  description: 'Look up the status of a customer order by order ID',
+  parameters: {
+    orderId: { type: 'string', description: 'The order ID', required: true },
+  },
+  async run({ orderId }) {
+    // Replace with your real database query
+    const mockOrders: Record<string, unknown> = {
+      'ORD-001': { status: 'shipped', eta: '2024-12-25', carrier: 'FedEx' },
+      'ORD-002': { status: 'processing', eta: '2024-12-27', carrier: null },
+    };
+    return mockOrders[orderId as string] ?? { error: 'Order not found' };
+  },
+});
+
+// ── Agent ─────────────────────────────────────────────────────────────────────
+
+const agent = new SvaraAgent({
+  name: 'Aria Support',
+  model: 'gpt-4o-mini',
+  knowledge: './policies',  // auto-indexed on start()
+
+  systemPrompt: `You are Aria, the customer support assistant for Acme Store.
+You are helpful, empathetic, and solution-focused.
+You can check order status and answer questions from our knowledge base.
+Always greet customers by name if they provide it.`,
+
+  memory: { window: 30 },
+  tools: [orderStatus],
+});
+
+// ── Channels ──────────────────────────────────────────────────────────────────
+
+agent
+  // Web API — for website chat widget
+  .connectChannel('web', {
+    port: 3000,
+    cors: true,
+  })
+
+  // Telegram Bot
+  .connectChannel('telegram', {
+    token: process.env.TELEGRAM_BOT_TOKEN!,
+    mode: 'polling', // use 'webhook' in production
+  })
+
+  // WhatsApp Business
+  .connectChannel('whatsapp', {
+    token: process.env.WA_ACCESS_TOKEN!,
+    phoneId: process.env.WA_PHONE_ID!,
+    verifyToken: process.env.WA_VERIFY_TOKEN!,
+  });
+
+// ── Events ────────────────────────────────────────────────────────────────────
+
+agent.on('message:received', ({ message, sessionId }: { message: string; sessionId: string }) => {
+  console.log(`[${sessionId.slice(0, 8)}] User: ${message.slice(0, 50)}...`);
+});
+
+agent.on('tool:call', ({ tools }: { tools: string[] }) => {
+  console.log(`[Tools] → ${tools.join(', ')}`);
+});
+
+agent.on('channel:ready', ({ channel }: { channel: string }) => {
+  console.log(`[Channel] ${channel} is ready`);
+});
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+await agent.start();
+console.log('\n🚀 Aria Support is live across all channels!\n');

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@yesvara/svara",
+  "version": "0.1.0",
+  "description": "Build AI agents in 15 lines of code. Multi-channel, RAG-ready, production-grade.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "svara": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --watch --format cjs",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run typecheck"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "ai", "agent", "llm", "openai", "anthropic", "rag",
+    "chatbot", "whatsapp", "telegram", "framework", "agentic"
+  ],
+  "author": "Yesvara Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yogiswara92/svara"
+  },
+  "homepage": "https://svarajs.yesvara.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "better-sqlite3": "^9.4.3",
+    "openai": "^4.47.1",
+    "@anthropic-ai/sdk": "^0.24.3",
+    "zod": "^3.23.8",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "glob": "^10.4.1",
+    "pdf-parse": "^1.1.1",
+    "mammoth": "^1.7.2",
+    "ora": "^8.0.1",
+    "inquirer": "^9.3.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/better-sqlite3": "^7.6.10",
+    "@types/node": "^20.14.2",
+    "@types/pdf-parse": "^1.1.4",
+    "tsup": "^8.1.0",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  },
+  "peerDependencies": {
+    "openai": ">=4.0.0",
+    "@anthropic-ai/sdk": ">=0.20.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": { "optional": true },
+    "@anthropic-ai/sdk": { "optional": true }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/app/index.ts

@@ -0,0 +1,176 @@
+/**
+ * @module SvaraApp
+ *
+ * The framework entry point. Wraps Express to give you a clean,
+ * AI-first HTTP server that works with zero configuration.
+ *
+ * @example
+ * ```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);
+ * // → Server running at http://localhost:3000
+ * // → POST /chat accepts { message, sessionId }
+ * // → GET  /health returns { status: 'ok' }
+ * ```
+ *
+ * @example With your own Express app
+ * ```ts
+ * import express from 'express';
+ * const expressApp = express();
+ *
+ * // Mount as middleware on any path
+ * expressApp.post('/api/chat', agent.handler());
+ * ```
+ */
+
+import express, { type Express, type RequestHandler, type Request, type Response } from 'express';
+import { createServer, type Server } from 'http';
+
+export interface AppOptions {
+  /**
+   * Enable CORS. Pass `true` for wildcard (*), or a specific origin string.
+   * @default false
+   */
+  cors?: boolean | string;
+
+  /**
+   * Require an API key in the `Authorization: Bearer <key>` header.
+   * Useful for protecting your agent endpoint.
+   */
+  apiKey?: string;
+
+  /**
+   * Request body size limit. @default '10mb'
+   */
+  bodyLimit?: string;
+}
+
+export class SvaraApp {
+  private readonly express: Express;
+  private server: Server | null = null;
+
+  constructor(options: AppOptions = {}) {
+    this.express = express();
+    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(path: string, handler: RequestHandler): this {
+    this.express.post(path, 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: RequestHandler): this {
+    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 = 3000): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.server = 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(): Promise<void> {
+    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(): Express {
+    return this.express;
+  }
+
+  // ─── Private Setup ────────────────────────────────────────────────────────
+
+  private setup(options: AppOptions): void {
+    // Parse JSON bodies
+    this.express.use(express.json({ limit: options.bodyLimit ?? '10mb' }));
+
+    // CORS
+    if (options.cors) {
+      this.express.use((_req, res, next) => {
+        const origin = options.cors === true ? '*' : options.cors as string;
+        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));
+    }
+
+    // API key auth
+    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();
+      });
+    }
+
+    // Health check — always available, no auth
+    this.express.get('/health', (_req: Request, res: Response) => {
+      res.json({
+        status: 'ok',
+        framework: '@yesvara/svara',
+        timestamp: new Date().toISOString(),
+      });
+    });
+  }
+}