@yesvara/svara 0.1.2 → 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

@@ -29,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());
@@ -44,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 |
@@ -359,7 +359,7 @@ agent
     verifyToken: process.env.WA_VERIFY_TOKEN,
   });
 
-await agent.start();
+await agent.start(); // Start all channels
 ```
 
 ### Events
@@ -416,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)
@@ -462,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
@@ -494,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/index.d.mts

@@ -446,6 +446,7 @@ declare class SvaraAgent extends EventEmitter {
     private retriever;
     private knowledgePaths;
     private isStarted;
+    private isKnowledgeInitialized;
     private db;
     constructor(config: AgentConfig);
     /**

package/dist/index.d.ts

@@ -446,6 +446,7 @@ declare class SvaraAgent extends EventEmitter {
     private retriever;
     private knowledgePaths;
     private isStarted;
+    private isKnowledgeInitialized;
     private db;
     constructor(config: AgentConfig);
     /**

package/dist/index.js

@@ -1701,6 +1701,7 @@ var SvaraAgent = class extends import_events.default {
   // Store VectorRetriever for retrieveChunks access
   knowledgePaths = [];
   isStarted = false;
+  isKnowledgeInitialized = false;
   db;
   constructor(config) {
     super();
@@ -1809,6 +1810,15 @@ var SvaraAgent = class extends import_events.default {
    */
   handler() {
     return async (req, res) => {
+      if (this.knowledgePaths.length > 0 && !this.isKnowledgeInitialized) {
+        try {
+          await this.initKnowledge(this.knowledgePaths);
+          this.isKnowledgeInitialized = true;
+        } catch (err) {
+          const error = err;
+          this.log("error", `Failed to initialize knowledge: ${error.message}`);
+        }
+      }
       const { message, sessionId, userId } = req.body;
       if (!message?.trim()) {
         res.status(400).json({

package/dist/index.mjs

@@ -891,6 +891,7 @@ var SvaraAgent = class extends EventEmitter {
   // Store VectorRetriever for retrieveChunks access
   knowledgePaths = [];
   isStarted = false;
+  isKnowledgeInitialized = false;
   db;
   constructor(config) {
     super();
@@ -999,6 +1000,15 @@ var SvaraAgent = class extends EventEmitter {
    */
   handler() {
     return async (req, res) => {
+      if (this.knowledgePaths.length > 0 && !this.isKnowledgeInitialized) {
+        try {
+          await this.initKnowledge(this.knowledgePaths);
+          this.isKnowledgeInitialized = true;
+        } catch (err) {
+          const error = err;
+          this.log("error", `Failed to initialize knowledge: ${error.message}`);
+        }
+      }
       const { message, sessionId, userId } = req.body;
       if (!message?.trim()) {
         res.status(400).json({

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

@@ -31,11 +31,9 @@ Always be friendly and professional.`,
   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);
+console.log('✓ Agent running on http://localhost:3000');
+console.log('  Knowledge base auto-loads on first request');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yesvara/svara",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Build AI agents in 15 lines of code. Multi-channel, RAG-ready, production-grade.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/core/agent.ts

@@ -173,6 +173,7 @@ export class SvaraAgent extends EventEmitter {
   private retriever: any = null; // Store VectorRetriever for retrieveChunks access
   private knowledgePaths: string[] = [];
   private isStarted = false;
+  private isKnowledgeInitialized = false;
   private db: SvaraDB;
 
   constructor(config: AgentConfig) {
@@ -303,6 +304,17 @@ export class SvaraAgent extends EventEmitter {
    */
   handler(): RequestHandler {
     return async (req, res) => {
+      // Auto-initialize knowledge on first request (lazy loading)
+      if (this.knowledgePaths.length > 0 && !this.isKnowledgeInitialized) {
+        try {
+          await this.initKnowledge(this.knowledgePaths);
+          this.isKnowledgeInitialized = true;
+        } catch (err) {
+          const error = err as Error;
+          this.log('error', `Failed to initialize knowledge: ${error.message}`);
+        }
+      }
+
       const { message, sessionId, userId } = req.body as {
         message?: string;
         sessionId?: string;

package/test-rag.ts

@@ -1,20 +0,0 @@
-import 'dotenv/config';
-import { SvaraApp, SvaraAgent } from './src/index.js';
-
-async function main() {
-  const app = new SvaraApp({ cors: true });
-  
-  const agent = new SvaraAgent({
-    name: 'TestAgent',
-    model: 'gpt-4o-mini',
-    knowledge: '/Users/920078/Documents/svara/contoh_folder_knowledge/**/*',
-    verbose: true,
-  });
-  
-  await agent.start();
-  app.route('/chat', agent.handler());
-  app.listen(3000);
-  console.log('✓ Test server on port 3000');
-}
-
-main().catch(console.error);