npm - @yesvara/svara - Versions diffs - 0.1.0 → 0.1.2 - Mend

@yesvara/svara 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/CONTRIBUTING.md +233 -0
package/README.md +211 -23
package/SvaraJS.png +0 -0
package/dist/{chunk-FEA5KIJN.mjs → chunk-CCNWHBEI.mjs} +108 -27
package/dist/chunk-GA7LHPOF.mjs +257 -0
package/dist/cli/index.js +490 -4
package/dist/cli/index.mjs +35 -3
package/dist/db-PEMUBXAR.mjs +190 -0
package/dist/index.d.mts +18 -2
package/dist/index.d.ts +18 -2
package/dist/index.js +454 -269
package/dist/index.mjs +83 -239
package/dist/{retriever-4QY667XF.mjs → retriever-JYOGHA4F.mjs} +2 -1
package/package.json +27 -15
package/src/cli/commands/db.ts +267 -0
package/src/cli/index.ts +74 -4
package/src/core/agent.ts +89 -8
package/src/core/types.ts +14 -1
package/src/database/schema.ts +31 -6
package/src/rag/chunker.ts +1 -0
package/src/rag/retriever.ts +146 -33
package/svara@1.0.0 +0 -0
package/test-rag.ts +20 -0
package/tsx +0 -0

package/CONTRIBUTING.md ADDED Viewed

@@ -0,0 +1,233 @@
+# Contributing to SvaraJS
+Thanks for your interest in contributing! We welcome all contributions—bug reports, feature requests, documentation improvements, and pull requests.
+## Code of Conduct
+Be respectful and constructive. We're building a framework for developers, so let's keep the community welcoming.
+---
+## Getting Started
+### 1. Clone & Setup
+```bash
+git clone https://github.com/yogiswara92/svarajs.git
+cd svara
+nvm use 20  # or 22
+npm install
+```
+### 2. Development
+```bash
+npm run dev       # Watch mode for TypeScript
+npm run build     # Build for production
+npm run typecheck # Type checking
+npm test          # Run tests
+```
+### 3. Project Structure
+```
+src/
+├── core/          # Agent, LLM, types
+├── app/           # SvaraApp HTTP wrapper
+├── channels/      # Web, Telegram, WhatsApp
+├── rag/           # Document loading, chunking, retrieval
+├── memory/        # Conversation history
+├── tools/         # Tool definition & registry
+├── database/      # SQLite wrapper
+├── cli/           # CLI commands
+└── types.ts       # Public API types
+```
+---
+## Reporting Issues
+**Before opening an issue:**
+- Check [existing issues](https://github.com/yogiswara92/svarajs/issues)
+- Try the latest dev version: `npm run dev`
+**When reporting, include:**
+- Clear title + description
+- Steps to reproduce
+- Expected vs actual behavior
+- Node version, OS, environment
+- Code snippet (if applicable)
+---
+## Submitting PRs
+### Before You Start
+1. **Check existing PRs** to avoid duplicates
+2. **Open an issue first** for major changes (discuss approach)
+3. **Fork & create a branch:**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+### While Developing
+- Follow **existing code style** (no strict linter, but be consistent)
+- Keep changes **focused & minimal**
+- Write clear commit messages (see below)
+- Test locally: `npm run build && npm run typecheck`
+### Before Submitting PR
+1. **Run tests:**
+   ```bash
+   npm test
+   npm run typecheck
+   ```
+2. **Update docs** if adding/changing public APIs
+3. **Commit with clear messages:**
+   ```bash
+   git commit -m "feat: add support for custom embeddings provider"
+   git commit -m "fix: resolve memory leak in vector store"
+   git commit -m "docs: improve RAG examples in README"
+   ```
+4. **Push & open PR:**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+### PR Guidelines
+- **Title:** Start with `feat:`, `fix:`, `docs:`, `refactor:`, etc.
+- **Description:** What changed and why
+- **Link issues:** "Closes #123" in description
+- **Keep it focused:** One feature/fix per PR
+- **Minimal dependencies:** Discuss before adding packages
+---
+## Code Style
+We follow these patterns (not strict, but consistent):
+```ts
+// Imports
+import { SvaraAgent } from '../core/agent.js';
+import type { Tool } from '../types.js';
+// Exports
+export class MyClass { }
+export type { MyType };
+// Naming
+const myVariable = 'value';     // camelCase
+const MY_CONSTANT = 'VALUE';    // UPPER_SNAKE_CASE (rarely used)
+class MyClass { }               // PascalCase
+// Comments
+// Single line for brief explanation
+/**
+ * Multi-line for public API documentation.
+ * Explain what it does, not how.
+ */
+// Error handling
+throw new Error('[@yesvara/svara] Clear error message');
+// Async/await
+async function load() {
+  try {
+    return await operation();
+  } catch (error) {
+    console.error('[SvaraJS] Error message:', error);
+    throw error;
+  }
+}
+```
+---
+## Testing
+Currently minimal test suite. Before submitting:
+```bash
+npm run typecheck
+npm run build
+```
+If adding features:
+- Test locally with `npm run dev`
+- Consider adding tests in `src/__tests__/`
+---
+## Commit Message Format
+```
+<type>: <subject>
+<body (optional)>
+<footer (optional)>
+```
+**Types:**
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation
+- `refactor:` - Code restructuring (no behavior change)
+- `perf:` - Performance improvement
+- `test:` - Test-related
+- `chore:` - Dependency updates, build config, etc.
+**Examples:**
+```
+feat: add support for Groq API provider
+- Auto-detect model from "groq-" prefix
+- Support streaming responses
+- Add tests for Groq integration
+Closes #45
+```
+```
+fix: resolve memory leak in vector store
+The InMemoryVectorStore was not clearing old entries.
+Now properly clears when adding > 10k entries.
+Fixes #123
+```
+---
+## Release Process
+Maintainers only:
+```bash
+npm version minor  # or patch, major
+npm publish
+git push origin main --tags
+```
+---
+## Questions?
+- **Issues:** [GitHub Issues](https://github.com/yogiswara92/svarajs/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/yogiswara92/svarajs/discussions)
+- **Email:** yogiswaragheartha@gmail.com / admin@yesvara.com
+- **Website:** https://yesvara.com
+- **Whatsapp:** [+6285171010456](https://wa.me/6285171010456)
+- **LinkedIn:** [Yogiswara Gheartha](https://www.linkedin.com/in/igb-yogiswara-gheartha-st-mmt-969b6b117/)
+---
+Thanks for contributing to SvaraJS!

package/README.md CHANGED Viewed

@@ -1,11 +1,12 @@
 <div align="center">
+<img src="SvaraJS.png" alt="SvaraJS" width="400">
-# @yesvara/svara
+<!-- # @yesvara/svara -->
 **Build AI agents in 15 lines. Ship to production.**
-A batteries-included Node.js framework for building agentic AI backends —
-multi-channel, RAG-ready, and designed for developers who value simplicity.
+A batteries-included Node.js framework for building agentic AI backends.
+Multi-channel, RAG-ready, and designed for developers who value simplicity.
 [![npm version](https://img.shields.io/npm/v/@yesvara/svara?color=0ea5e9&label=npm)](https://www.npmjs.com/package/@yesvara/svara)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
@@ -37,7 +38,7 @@ app.listen(3000);
 ```
 That's it. No pipeline setup. No embedding boilerplate. No webhook configuration.
-**Convention over configuration — like Express, but for AI.**
+**Convention over configuration (like Express, but for AI).**
 ---
@@ -45,13 +46,16 @@ That's it. No pipeline setup. No embedding boilerplate. No webhook configuration
 | | |
 |---|---|
-| **Zero-config LLM** | Pass a model name — provider is auto-detected |
+| **Zero-config LLM** | Pass a model name, provider is auto-detected |
 | **Instant RAG** | Point to a folder, documents are indexed automatically |
 | **Multi-channel** | WhatsApp, Telegram, and Web from one agent |
 | **Tool calling** | Declarative tools with full TypeScript types |
 | **Conversation memory** | Automatic per-session history, configurable window |
 | **Express-compatible** | `agent.handler()` drops into any existing app |
-| **Built-in database** | Zero-config SQLite for state, KV store, and history |
+| **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, auto-dedup |
+| **User tracking** | Auto-tracks users and sessions with timestamps |
 | **CLI included** | `svara new`, `svara dev`, `svara build` |
 ---
@@ -101,17 +105,23 @@ npx tsx src/index.ts
 ```bash
 curl -X POST http://localhost:3000/chat \
   -H "Content-Type: application/json" \
-  -d '{ "message": "Hello! What can you do?", "sessionId": "user-1" }'
+  -d '{
+    "message": "Hello! What can you do?",
+    "userId": "user-1",
+    "sessionId": "user-1-session-1"
+  }'
 ```
 ```json
 {
   "response": "Hi! I'm Aria, your AI assistant...",
-  "sessionId": "user-1",
+  "sessionId": "user-1-session-1",
   "usage": { "totalTokens": 142 }
 }
 ```
+The agent automatically tracks users and sessions in the SQLite database.
 ---
 ## Supported Models
@@ -143,13 +153,13 @@ The central class. Configure once, use everywhere.
 ```ts
 const agent = new SvaraAgent({
   name: 'Support Bot',         // Display name (used in logs & system prompt)
-  model: 'gpt-4o-mini',        // LLM model — provider auto-detected
-  systemPrompt: 'You are...', // Optional — sensible default based on name
-  knowledge: './docs',         // Optional — folder/glob for RAG
-  memory: { window: 20 },      // Optional — conversation history window
-  tools: [myTool],             // Optional — functions the agent can call
-  temperature: 0.7,            // Optional — creativity (0–2)
-  verbose: true,               // Optional — detailed logs
+  model: 'gpt-4o-mini',        // LLM model - provider auto-detected
+  systemPrompt: 'You are...', // Optional - sensible default based on name
+  knowledge: './docs',         // Optional - folder/glob for RAG
+  memory: { window: 20 },      // Optional - conversation history window
+  tools: [myTool],             // Optional - functions the agent can call
+  temperature: 0.7,            // Optional - creativity (0–2)
+  verbose: true,               // Optional - detailed logs
 });
 ```
@@ -219,6 +229,122 @@ await agent.addKnowledge('./new-policy-2024.pdf');
 Supported formats: **PDF, Markdown, TXT, DOCX, HTML, JSON**
+**RAG Persistence & Per-Agent Isolation:**
+Vector embeddings are automatically persisted to SQLite. Each agent has its own isolated knowledge base:
+```ts
+const supportBot = new SvaraAgent({
+  name: 'SupportBot',
+  model: 'gpt-4o-mini',
+  knowledge: './docs/support',  // Knowledge base 1
+});
+const salesBot = new SvaraAgent({
+  name: 'SalesBot',
+  model: 'gpt-4o-mini',
+  knowledge: './docs/sales',    // Knowledge base 2
+});
+await supportBot.start();
+await salesBot.start();
+// Both agents run simultaneously with isolated RAG:
+// - SupportBot only searches in support docs
+// - SalesBot only searches in sales docs
+// - No cross-contamination, efficient storage
+// - Embeddings persist across restarts
+// - Duplicate content skipped per agent
+```
+**How it works:**
+- Documents are embedded and stored in SQLite with agent name
+- Each agent queries only its own chunks
+- 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.
+```ts
+// Send message with userId and sessionId
+const result = await agent.process('Help me with my order', {
+  userId: 'user-123',
+  sessionId: 'user-123-conversation-1'
+});
+// Database tracks:
+// - svara_users: user-123 (first_seen, last_seen, metadata)
+// - svara_sessions: session details, linked to user-123
+// - svara_messages: conversation history for this session
+```
+Query user data:
+```ts
+import { SvaraDB } from '@yesvara/svara';
+const db = new SvaraDB('./data/svara.db');
+// Get all users
+const users = db.query('SELECT * FROM svara_users');
+// Get sessions for a user
+const sessions = db.query(
+  'SELECT * FROM svara_sessions WHERE user_id = ?',
+  ['user-123']
+);
+// Get chat history for a session
+const messages = db.query(
+  'SELECT * FROM svara_messages WHERE session_id = ? ORDER BY created_at',
+  ['user-123-conversation-1']
+);
+// Check RAG chunks (with dedup tracking)
+const chunks = db.query(
+  'SELECT id, content, content_hash FROM svara_chunks LIMIT 10'
+);
+```
 ### Channels
 One agent, multiple platforms.
@@ -372,15 +498,30 @@ $ svara new my-app
 ## Built-in Database
-Zero-config SQLite for when you need persistent state.
+Persistent SQLite for users, sessions, conversation history, and RAG vectors.
 ```ts
 import { SvaraDB } from '@yesvara/svara';
-const db = new SvaraDB('./data/agent.db');
+const db = new SvaraDB('./data/svara.db');
-// Simple queries
-const users = db.query<User>('SELECT * FROM users WHERE active = ?', [1]);
+// Built-in tables (auto-created):
+// - svara_users: user registry with timestamps
+// - svara_sessions: conversation sessions linked to users
+// - svara_messages: conversation history
+// - svara_chunks: RAG vectors with deduplication
+// - svara_kv: key-value store for app state
+// Query users
+const activeUsers = db.query(
+  'SELECT id, display_name, last_seen FROM svara_users WHERE last_seen > unixepoch() - 86400'
+);
+// Get conversation history
+const history = db.query(
+  'SELECT role, content FROM svara_messages WHERE session_id = ? ORDER BY created_at',
+  ['session-id']
+);
 // Key-value store
 db.kv.set('feature:rag', true);
@@ -446,8 +587,8 @@ Request:
 ```json
 {
   "message": "What is the refund policy?",
-  "sessionId": "user-123",
-  "userId": "alice@example.com"
+  "userId": "alice@example.com",
+  "sessionId": "alice-session-1"
 }
 ```
@@ -455,7 +596,7 @@ Response:
 ```json
 {
   "response": "Our refund policy allows returns within 30 days...",
-  "sessionId": "user-123",
+  "sessionId": "alice-session-1",
   "usage": {
     "promptTokens": 312,
     "completionTokens": 89,
@@ -465,16 +606,63 @@ Response:
 }
 ```
+**Note:** `userId` and `sessionId` are automatically tracked in the SQLite database for user management and conversation history.
 **`GET /health`** — always returns `{ "status": "ok" }`
 ---
+## Database Schema
+SvaraJS automatically creates and manages these SQLite tables:
+| Table | Purpose | Auto-Managed |
+|-------|---------|--------------|
+| `svara_users` | User registry (first_seen, last_seen, metadata) | ✅ Yes |
+| `svara_sessions` | Conversation sessions linked to users | ✅ Yes |
+| `svara_messages` | Full conversation history per session | ✅ Yes |
+| `svara_chunks` | RAG vectors **isolated per agent** with deduplication | ✅ Yes |
+| `svara_documents` | Document registry and metadata | ✅ Yes |
+| `svara_kv` | Key-value store for app state | ✅ Yes |
+| `svara_meta` | Framework metadata and versions | ✅ Yes |
+**RAG Isolation:**
+Each agent's RAG data is stored separately using the `agent_name` column:
+```ts
+// Query RAG chunks for specific agent
+const supportChunks = db.query(
+  'SELECT COUNT(*) as count FROM svara_chunks WHERE agent_name = ?',
+  ['SupportBot']
+);
+const salesChunks = db.query(
+  'SELECT COUNT(*) as count FROM svara_chunks WHERE agent_name = ?',
+  ['SalesBot']
+);
+// Export conversation analytics
+db.query(`
+  SELECT u.id, u.display_name, COUNT(m.id) as message_count
+  FROM svara_users u
+  LEFT JOIN svara_messages m ON u.id = (
+    SELECT user_id FROM svara_sessions WHERE id = m.session_id
+  )
+  WHERE u.last_seen > unixepoch() - 86400
+  GROUP BY u.id
+  ORDER BY message_count DESC
+`);
+```
+---
 ## Contributing
 Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) first.
 ```bash
-git clone https://github.com/yesvara/svara
+git clone https://github.com/yogiswara92/svarajs
 cd svara
 npm install
 npm run dev

package/SvaraJS.png ADDED Viewed

Binary file