Skip to content

raglite/rag-lite-ts

Repository files navigation

RAG-lite TS

Simple by default, powerful when needed

A local-first TypeScript retrieval engine for semantic search over static documents. Built to be simple to use, lightweight, and hackable with zero external run-time dependencies.

Pipeline

Table of Contents

Quick Start

Installation

npm install -g rag-lite-ts

Basic Usage

# Ingest documents
raglite ingest ./docs/

# Search your documents
raglite search "machine learning concepts"

# Get more results with reranking
raglite search "API documentation" --top-k 10 --rerank

Using Different Models

# Use higher quality model (auto-rebuilds if needed)
raglite ingest ./docs/ --model Xenova/all-mpnet-base-v2 --rebuild-if-needed

# Search automatically uses the correct model
raglite search "complex query"

Programmatic Usage

import { SearchEngine, IngestionPipeline } from 'rag-lite-ts';

// Initialize and ingest documents
const ingestion = new IngestionPipeline('./db.sqlite', './vector-index.bin');
await ingestion.ingestDirectory('./docs/');

// Search your documents
const search = new SearchEngine('./vector-index.bin', './db.sqlite');
const results = await search.search('machine learning', { top_k: 10 });

Configuration Options

import { SearchEngine, IngestionPipeline } from 'rag-lite-ts';

// Custom model configuration
const search = new SearchEngine('./vector-index.bin', './db.sqlite', {
  embeddingModel: 'Xenova/all-mpnet-base-v2',
  enableReranking: true,
  topK: 15
});

// Ingestion with custom settings
const ingestion = new IngestionPipeline('./db.sqlite', './vector-index.bin', {
  embeddingModel: 'Xenova/all-mpnet-base-v2',
  chunkSize: 400,
  chunkOverlap: 80
});

β†’ Complete CLI Reference | API Documentation

Features

  • πŸ“ Simple: Get started with just new SearchEngine() - no complex setup required
  • 🏠 Local-first: All processing happens offline on your machine
  • πŸš€ Fast: Sub-100ms queries for typical document collections
  • πŸ” Semantic: Uses embeddings for meaning-based search, not just keywords
  • πŸ› οΈ Flexible: Simple constructors for basic use, advanced options when you need them
  • πŸ“¦ Complete: CLI, programmatic API, and MCP server in one package
  • 🎯 TypeScript: Full type safety with modern ESM architecture
  • 🧠 Smart: Automatic model management and compatibility checking

How It Works

RAG-lite TS follows a simple pipeline:

  1. Document Ingestion: Reads .md, .txt, .mdx, .pdf, and .docx files
  2. Preprocessing: Cleans content (JSX components, Mermaid diagrams, code blocks)
  3. Semantic Chunking: Splits documents at natural boundaries with token limits
  4. Embedding Generation: Uses transformers.js models for semantic vectors
  5. Vector Storage: Fast similarity search with hnswlib-wasm
  6. Metadata Storage: SQLite for document info and model compatibility
  7. Search: Embeds queries and finds similar chunks using cosine similarity
  8. Reranking (optional): Cross-encoder models for improved relevance

Architecture

Documents β†’ Preprocessor β†’ Chunker β†’ Embedder β†’ Vector Index
                                        ↓
Query β†’ Embedder β†’ Vector Search β†’ SQLite Lookup β†’ Results

β†’ Document Preprocessing Guide | Model Management Details

Supported Models

RAG-lite TS supports multiple embedding models with automatic optimization:

Model Dimensions Speed Use Case
sentence-transformers/all-MiniLM-L6-v2 384 Fast General purpose (default)
Xenova/all-mpnet-base-v2 768 Slower Higher quality, complex queries

Model Features:

  • Automatic downloads: Models cached locally on first use
  • Smart compatibility: Detects model changes and prompts rebuilds
  • Offline support: Pre-download for offline environments
  • Reranking: Optional cross-encoder models for better relevance

β†’ Complete Model Guide | Performance Benchmarks

Documentation

πŸ“š Getting Started

πŸ”§ Customization & Advanced Usage

πŸ› οΈ Support

πŸ“Š Technical References

Quick Links by User Type

User Type Start Here Next Steps
New Users CLI Reference API Reference
App Developers API Reference Configuration Guide
Performance Optimizers Model Guide Performance Benchmarks
Production Deployers Configuration Guide Path Strategies
Troubleshooters Troubleshooting Guide Preprocessing Guide

MCP Server Integration

RAG-lite TS includes a Model Context Protocol (MCP) server for integration with AI agents.

# Start MCP server
raglite-mcp

MCP Configuration:

{
  "mcpServers": {
    "rag-lite": {
      "command": "raglite-mcp",
      "args": []
    }
  }
}

Available Tools: search_documents, ingest_documents, rebuild_index, get_stats

β†’ Complete MCP Integration Guide

Development

Building from Source

# Clone and setup
git clone https://github.com/your-username/rag-lite-ts.git
cd rag-lite-ts
npm install

# Build and link for development
npm run build
npm link  # Makes raglite/raglite-mcp available globally

# Run tests
npm test
npm run test:integration

Project Structure

src/
β”œβ”€β”€ index.ts              # Main exports and factory functions
β”œβ”€β”€ search.ts             # Public SearchEngine API
β”œβ”€β”€ ingestion.ts          # Public IngestionPipeline API
β”œβ”€β”€ core/                 # Model-agnostic core layer
β”‚   β”œβ”€β”€ search.ts         # Core search engine
β”‚   β”œβ”€β”€ ingestion.ts      # Core ingestion pipeline
β”‚   β”œβ”€β”€ db.ts             # SQLite operations
β”‚   β”œβ”€β”€ config.ts         # Configuration system
β”‚   └── types.ts          # Core type definitions
β”œβ”€β”€ factories/            # Factory functions for easy setup
β”‚   └── text-factory.ts   # Text-specific factories
β”œβ”€β”€ text/                 # Text-specific implementations
β”‚   β”œβ”€β”€ embedder.ts       # Text embedding generation
β”‚   β”œβ”€β”€ reranker.ts       # Text reranking
β”‚   └── tokenizer.ts      # Text tokenization
β”œβ”€β”€ cli.ts                # CLI interface
β”œβ”€β”€ mcp-server.ts         # MCP server
└── preprocessors/        # Content type processors

dist/                     # Compiled output

Design Philosophy

Simple by default, powerful when needed:

  • βœ… Simple constructors work immediately with sensible defaults
  • βœ… Configuration options available when you need customization
  • βœ… Advanced patterns available for complex use cases
  • βœ… Clean architecture with minimal dependencies
  • βœ… No ORMs or heavy frameworks - just TypeScript and SQLite
  • βœ… Extensible design for future capabilities

This approach ensures that basic usage is effortless while providing the flexibility needed for advanced scenarios.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass
  6. Submit a pull request

We welcome contributions that maintain our clean architecture principles while enhancing functionality and developer experience.

License

MIT License - see LICENSE file for details.

Related Projects

About

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published