Repository navigation
Releases
Quick RAG v2.5.3
This release focuses on stability, packaging correctness, and test reliability.
Highlights:
- Fixed the
quick-rag/reactsubpath to exportuseRAG,initRAG, andcreateBrowserModelClient - Corrected BM25 synchronization in hybrid search so the full in-memory dataset is indexed
- Made
SmartRetrievercompatible with retriever-style array results while preserving decision metadata - Serialized conversation auto-summarization to reduce race conditions during rapid message updates
- Added core smoke tests and a live Ollama integration test validated with
qwen3.5:9bandqwen3-embedding:0.6b - Stabilized npm script execution on Windows by pinning the script shell to
cmd.exe - Refined ignore rules and release metadata for cleaner packaging and publishing
Validation:
npm run buildnpm testnpm run test:integration
Full Changelog: v2.5.2...v2.5.3
v2.5.2
Quick RAG v2.5.2
Fixed
- React subpath export fixed:
quick-rag/reactnow resolves correctly tosrc/react/useRag.js useRAGnon-stream flow aligned with moderngenerateWithRAG(client, model, query, docs, options)usage- Type definitions aligned with runtime for
generateWithRAGreturn shape:{ docs, response, prompt }
Changed
- Ollama base chat model standardized to
granite4:3bacross examples and integration-oriented tests initRAGnow supportsbaseEmbeddingOptions.createEmbeddingfor deterministic/custom embedding injectioninitRAGtests made deterministic for default test runs (external provider smoke test remains opt-in withRUN_INTEGRATION_TESTS=true)- Documentation refreshed for current defaults:
- Ollama embedding:
qwen3-embedding:0.6b - LM Studio embedding:
text-embedding-qwen3-embedding-0.6b - Ollama chat:
granite4:3b
- Ollama embedding:
Verification
npm testpassed- Package published:
quick-rag@2.5.2
What's New in v2.1.0
💾 Embedded Persistence (SQLite)
Store your vectors locally without setting up a complex database server!
Zero Setup: Just provide a file path (./rag.db)
Fast: Built on better-sqlite3
Full Features: Batch insert, metadata filtering, CRUD
🛡️ Advanced Error Handling
Never crash without knowing why. New error system provides:
Specific Error Types: RAGError, EmbeddingError, RetrievalError, etc.
Error Codes: Programmatic handling
Recovery Hints: Actionable suggestions in error messages
📊 Metrics & Logging
Monitor your RAG pipeline in production:
Performance Tracking: Embedding time, search latency, generation speed
Structured Logs: JSON format for easy parsing
Prometheus Support: Export metrics for monitoring dashboards Advanced filtering with custom logic - filter documents using JavaScript functions:
Full Changelog: v1.1.10...v2.1.0
Quick RAG v1.1.0 - Query Explainability & Dynamic Prompts 🎉
Two industry-first features that make Quick RAG the most advanced RAG library for JavaScript!
🆕 What's New
🔍 Query Explainability
Understand WHY documents were retrieved - A capability not found in any other RAG library!
Now you can see detailed explanations for every retrieved document:
const results = await retriever.getRelevant('What is Ollama?', 3, {
explain: true // Enable explanations
});
// Each result includes:
{
text: "Ollama is a local AI platform...",
score: 0.856,
explanation: {
queryTerms: ["ollama", "local", "ai"], // Extracted from query
matchedTerms: ["ollama", "local"], // Found in document
matchCount: 2, // Number of matches
matchRatio: 0.67, // 67% coverage
cosineSimilarity: 0.856, // Semantic similarity
relevanceFactors: {
termMatches: 2,
semanticSimilarity: 0.856,
coverage: "67%"
}
}
}Use Cases:
- 🐛 Debug unexpected search results
- 📊 Understand semantic vs keyword matching
- ✅ Validate retrieval accuracy
- 📈 Optimize query quality
- 💡 Explain results to end users
Example: example/08-explain-scores.js - Full demo with Ollama & LM Studio
🎨 Dynamic Prompt Management
10 built-in templates + full customization for perfect responses every time!
Built-in Templates
Choose from 10 professionally-crafted templates:
default- Standard RAG formatconversational- Chat-style responsestechnical- Technical documentation formatacademic- Research/scholarly stylecode- Code-focused responses with examplesconcise- Brief, to-the-point answersdetailed- Comprehensive, thorough responsesqa- Clean question-answer formatinstructional- Step-by-step guidescreative- Creative writing style
Quick Usage
// 1. Simple template selection
await generateWithRAG(client, model, query, docs, {
template: 'conversational'
});
// 2. Add system prompts
await generateWithRAG(client, model, query, docs, {
systemPrompt: 'You are a helpful programming tutor',
template: 'instructional'
});
// 3. Context formatting options
await generateWithRAG(client, model, query, docs, {
context: {
includeScores: true, // Show similarity scores
includeMetadata: true, // Show document metadata
maxLength: 500 // Limit context length
}
});Advanced: PromptManager
For reusable configurations:
import { createPromptManager } from 'quick-rag';
const promptMgr = createPromptManager({
systemPrompt: 'You are an expert software engineer with 10 years experience',
template: 'technical',
variables: { company: 'TechCorp' }
});
// Add custom formatters
promptMgr.addContextFormatter('numbered', (context, docs) => {
return docs.map((doc, i) => `${i + 1}. ${doc.text}`).join('\n');
});
// Use it
await generateWithRAG(client, model, query, docs, {
promptManager: promptMgr
});
// Clone and modify
const tutorMode = promptMgr.clone({
template: 'conversational',
systemPrompt: 'You are a friendly tutor'
});Custom Templates
Full control with function-based templates:
const customTemplate = (query, context) => `
╔══════════════════════════════════════╗
║ KNOWLEDGE BASE QUERY ║
╚══════════════════════════════════════╝
📚 Available Information:
${context}
❓ User Question:
${query}
💡 Expert Analysis:
`;
await generateWithRAG(client, model, query, docs, {
template: customTemplate
});Use Cases:
- 🎭 Different response styles per feature
- 👤 Role-based assistants (tutor, expert, analyst)
- 🏢 Multi-tenant applications
- 🧪 A/B test prompt effectiveness
- 🎯 Domain-specific formatting
Example: example/09-prompt-management.js - Complete guide with all features
🔧 Improvements
- Enhanced API:
retriever.getRelevant()now acceptsexplainoption - Enhanced API:
generateWithRAG()now accepts fulloptionsparameter - Better Context: Automatic formatting of scores and metadata
- Optional React: React imports no longer required for Node.js usage
- Better Errors: More helpful error messages
📦 Installation
npm install quick-rag@1.1.0Or update existing installation:
npm update quick-rag🔄 Migration from v1.0.0
Zero breaking changes! All v1.0.0 code works unchanged. New features are opt-in:
// v1.0.0 - still works perfectly
const results = await retriever.getRelevant(query, 3);
await generateWithRAG(client, model, query, docs);
// v1.1.0 - enhanced with new options
const results = await retriever.getRelevant(query, 3, { explain: true });
await generateWithRAG(client, model, query, docs, {
template: 'conversational',
systemPrompt: 'You are a helpful assistant'
});✅ Testing
All features thoroughly tested:
- ✅ Query Explainability with Ollama
- ✅ Query Explainability with LM Studio
- ✅ All 10 prompt templates
- ✅ System prompts
- ✅ Context formatting options
- ✅ PromptManager functionality
- ✅ Custom templates
- ✅ Backward compatibility
Run tests yourself:
npm test📚 Documentation
- CHANGELOG: CHANGELOG.md - Complete changelog
- README: README.md - Updated with v1.1.0 features
- Examples:
- 08-explain-scores.js - Query Explainability
- 09-prompt-management.js - Dynamic Prompts
🎯 Why Quick RAG v1.1.0?
Unique Features
- ✅ Query Explainability - Not found in LangChain, LlamaIndex, or any competitor
- ✅ 10 Prompt Templates - Most flexible prompt system in any RAG library
- ✅ PromptManager - Enterprise-grade prompt configuration
- ✅ Full Customization - Function-based templates for unlimited flexibility
Production Ready
- ✅ Official Ollama & LM Studio SDKs
- ✅ Comprehensive testing
- ✅ TypeScript support
- ✅ Backward compatible
- ✅ Clean, documented code
Developer Experience
- ✅ Clear, helpful error messages
- ✅ Complete examples for every feature
- ✅ Well-documented API
- ✅ Active development
🙏 Thank You
To all contributors and users who made this release possible! Your feedback drives innovation.
What's Next?
Vote on upcoming features:
- Hybrid Search (BM25 + semantic)
- Persistent Vector Store
- Query Analytics & Insights
- Multi-modal RAG (images, audio)
- Streaming Explainability
Join the discussion on GitHub Issues!
📦 Full Changelog
See CHANGELOG.md for complete details.
Made with ❤️ for the JavaScript & AI community
Support: GitHub Issues
Docs: README.md
NPM: quick-rag
Full Changelog: v1.0.0...v1.1.0
🎉 Quick RAG v1.0.0 - Production Ready
We're excited to announce Quick RAG v1.0.0 - the first production-ready release!
🚀 What's New
✨ Production Ready
- Thoroughly tested - All features tested with both Ollama and LM Studio
- Clean examples - 10 focused examples (5 for Ollama + 5 for LM Studio)
- Complete documentation - Full API docs and usage guides
- Stable API - No breaking changes planned
📄 Document Loaders
Load various document formats for RAG:
- PDF -
loadPDF()with pdf-parse - Word -
loadWord()for .docx files - Excel -
loadExcel()for .xlsx files - Text, JSON, Markdown - Built-in loaders
- Web Content -
loadURL(),loadURLs(),loadSitemap()
🔪 Smart Chunking
4 different chunking strategies:
chunkText()- Character-based with overlapchunkBySentences()- Semantic sentence splittingchunkDocuments()- Intelligent document chunkingchunkMarkdown()- Markdown-aware splitting
🏷️ Metadata Filtering
Filter documents by any metadata field + minimum score threshold.
🎨 Dual Provider Support
Works seamlessly with both Ollama and LM Studio:
- Auto-detection of available providers
- Consistent API across both platforms
- Full SDK feature access (streaming, tool calling, etc.)
🔧 Bug Fixes
- Fixed LM Studio
listLoaded()API call - Fixed embedding model caching issue
- Removed unused imports from examples
- Cleaned up example directory structure
📦 Installation
npm install quick-ragOptional dependencies (install as needed):
npm install pdf-parse # PDF support
npm install mammoth # Word support
npm install xlsx # Excel support🚀 Quick Start
Ollama
import {
OllamaRAGClient,
createOllamaRAGEmbedding,
InMemoryVectorStore
} from 'quick-rag';
const client = new OllamaRAGClient();
const embed = createOllamaRAGEmbedding(client, 'embeddinggemma');
const store = new InMemoryVectorStore(embed);
await store.addDocuments([{ text: 'Your knowledge here' }]);LM Studio
import {
LMStudioRAGClient,
createLMStudioRAGEmbedding,
InMemoryVectorStore
} from 'quick-rag';
const client = new LMStudioRAGClient();
const embed = createLMStudioRAGEmbedding(client, 'nomic-embed-text-v1.5');
const store = new InMemoryVectorStore(embed);
await store.addDocuments([{ text: 'Your knowledge here' }]);📚 Examples
Check out the example/ directory for:
- Basic usage - Get started quickly
- Document loading - Load PDFs, Word, Excel
- Metadata filtering - Advanced filtering
- Streaming - Real-time responses
- Test both providers - Verify your setup
🙏 Acknowledgments
Thank you to everyone who provided feedback and helped test this release!
📖 Documentation
Full Changelog: v0.7.2...v1.0.0
🚀 Quick RAG v0.7.2 - Official SDK Integration & Stability Release
The easiest way to add RAG to your JavaScript apps with local AI
What's New
Official SDK Integration
We've completely rewritten the core to use official SDKs from Ollama and LM Studio, giving you access to all their powerful features:
- Real-time streaming - Token-by-token response generation
- Tool calling & function execution - Build autonomous AI agents
- Vision model support - Process images alongside text
- Web search & fetch - Access web content (Ollama account required)
- Model management - List, pull, push, create, delete models
- Advanced configuration - Full control over generation parameters
Package Rebranding
- New name:
quick-rag(previouslyjs-rag-local-llm) - More memorable and easier to discover
- Cleaner branding and better SEO
Dual API Support
We support both modern and legacy APIs for smooth migration:
New API (Recommended):
import { OllamaRAGClient, createOllamaRAGEmbedding } from 'quick-rag';
const client = new OllamaRAGClient();
const embed = createOllamaRAGEmbedding(client, 'embeddinggemma');
const vectorStore = new InMemoryVectorStore(embed);Legacy API (Still Supported):
import { OllamaClient, createOllamaEmbedding } from 'quick-rag';
// Your existing code continues to workExample Organization
- Cleaned up examples - From 14 scattered files to 5 focused examples
- Advanced examples - Moved to
example/advanced/for power users - Better documentation - Step-by-step guides for beginners
Bug Fixes
v0.7.2 (Latest)
- Fixed
generateWithRAG()compatibility with both Ollama and LM Studio - Added smart client detection for proper API usage
- Dual API support (new + legacy) for backward compatibility
- All README examples tested and verified working
v0.7.1
- Corrected all code examples in documentation
- Fixed API inconsistencies (
vectorStore.addDocuments(),retriever.getRelevant()) - Updated to use recommended client names (
OllamaRAGClient,LMStudioRAGClient)
Installation
npm install quick-ragQuick Start
Ollama (3 steps!)
import {
OllamaRAGClient,
createOllamaRAGEmbedding,
InMemoryVectorStore,
Retriever
} from 'quick-rag';
// 1. Setup
const client = new OllamaRAGClient();
const embed = createOllamaRAGEmbedding(client, 'embeddinggemma');
const vectorStore = new InMemoryVectorStore(embed);
const retriever = new Retriever(vectorStore);
// 2. Add documents
await vectorStore.addDocuments([
{ text: 'JavaScript is a programming language.' },
{ text: 'Python is great for data science.' }
]);
// 3. Query with streaming
const results = await retriever.getRelevant('What is JavaScript?', 2);
const response = await client.chat({
model: 'granite4:tiny-h',
messages: [{
role: 'user',
content: `Context: ${results.map(d => d.text).join('\n')}\n\nQuestion: What is JavaScript?`
}],
stream: true // Real-time streaming!
});
for await (const part of response) {
process.stdout.write(part.message.content);
}LM Studio (Also 3 steps!)
import {
LMStudioRAGClient,
createLMStudioRAGEmbedding,
InMemoryVectorStore,
Retriever
} from 'quick-rag';
const client = new LMStudioRAGClient();
const embed = createLMStudioRAGEmbedding(client, 'nomic-embed-text-v1.5');
const vectorStore = new InMemoryVectorStore(embed);
const retriever = new Retriever(vectorStore);
// Add your documents and query - same API!What's Supported
Frameworks
- React (Vite, CRA)
- Next.js (App Router, Pages Router)
- Node.js (Pure JavaScript/TypeScript)
- Browser (with proxy)
AI Providers
- Ollama (via official SDK v0.6.2)
- LM Studio (via official SDK v1.5.0)
Features
- Vector search with cosine similarity
- CRUD operations (add, update, delete documents)
- Dynamic topK retrieval
- Batch embedding (5x faster)
- Streaming responses
- React hooks (
useRAG) - TypeScript support
Migration Guide
From js-rag-local-llm to quick-rag
# 1. Update package
npm uninstall js-rag-local-llm
npm install quick-rag
# 2. Update imports (find & replace in your code)
# From: 'js-rag-local-llm'
# To: 'quick-rag'API Changes:
- Use
OllamaRAGClientinstead ofOllamaClient(recommended) - Use
createOllamaRAGEmbeddinginstead ofcreateOllamaEmbedding(recommended) - Use
vectorStore.addDocuments()notretriever.addDocuments() - Use
retriever.getRelevant()notretriever.retrieve()
Good News: Legacy APIs still work! Migrate at your own pace.
Performance
- 5x faster batch embedding
- ~10ms vector search (10K documents)
- Real-time streaming with official SDKs
- Zero latency - everything runs locally
Links
Acknowledgments
Built on top of these amazing projects:
- ollama - Official Ollama
- ollama-js - Official Ollama JavaScript SDK
- lmstudio-js - Official LM Studio TypeScript SDK
What's Next?
- More embedding models
- Persistent storage adapters
- Advanced reranking
- Multi-query support
Made with ⚡ by the Quick RAG team
If you find this useful, please ⭐ star the repo!
Full Changelog: https://github.com/emredeveloper/quick-rag/commits/v0.7.2