@retrivora-ai/rag-engine 0.1.0

package/.env.example

@@ -0,0 +1,77 @@
+# ─── Project ─────────────────────────────────────────────────
+RAG_PROJECT_ID=my-project
+
+# ─── Vector Database ──────────────────────────────────────────
+# Choose: pinecone | pgvector | rest | universal_rest
+VECTOR_DB_PROVIDER=pinecone
+VECTOR_DB_INDEX=rag-index
+
+# Pinecone (if provider=pinecone)
+PINECONE_API_KEY=your-pinecone-api-key
+PINECONE_ENVIRONMENT=us-east-1
+
+# pgVector (if provider=pgvector)
+PGVECTOR_CONNECTION_STRING=postgresql://user:password@localhost:5432/ragdb
+
+# Generic REST (if provider=rest)
+VECTOR_DB_REST_URL=http://localhost:8080
+VECTOR_DB_REST_API_KEY=your-rest-api-key
+# VECTOR_DB_QUERY_PATH=/query
+# VECTOR_DB_UPSERT_PATH=/upsert
+
+# ─── LLM ──────────────────────────────────────────────────────
+# Choose: openai | anthropic | ollama | universal_rest
+LLM_PROVIDER=openai
+LLM_MODEL=gpt-4o
+LLM_MAX_TOKENS=1024
+LLM_TEMPERATURE=0.7
+LLM_SYSTEM_PROMPT=You are a helpful assistant. Use the provided context to answer questions accurately.
+
+# OpenAI (if provider=openai)
+OPENAI_API_KEY=sk-...
+
+# Anthropic (if provider=anthropic)
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Ollama (if provider=ollama)
+LLM_BASE_URL=http://localhost:11434
+
+# ── Master Universal Provider (LiteLLM, Qdrant, etc.) ─────────
+# Use 'universal_rest' for ANY model or DB via pre-set profiles.
+LLM_PROVIDER=universal_rest
+LLM_MODEL=gpt-4o
+# Profile: litellm | ollama-standard | openai-compatible
+LLM_UNIVERSAL_PROFILE=litellm
+LLM_BASE_URL=https://proxy.example.com/api
+LLM_API_KEY=your-key
+
+VECTOR_DB_PROVIDER=universal_rest
+# Profile: qdrant | chromadb
+VECTOR_UNIVERSAL_PROFILE=qdrant
+VECTOR_BASE_URL=http://localhost:6333
+VECTOR_DB_INDEX=my-index
+
+# ─── Embedding ────────────────────────────────────────────────
+# Choose: openai | ollama | custom
+EMBEDDING_PROVIDER=openai
+EMBEDDING_MODEL=text-embedding-3-small
+EMBEDDING_DIMENSIONS=1536
+# EMBEDDING_BASE_URL=http://localhost:11434  # for ollama
+# EMBEDDING_API_KEY=your-embedding-key       # for custom embedding endpoints
+
+# ─── RAG Pipeline Tuning ──────────────────────────────────────
+RAG_TOP_K=5
+RAG_SCORE_THRESHOLD=0.0
+RAG_CHUNK_SIZE=1000
+RAG_CHUNK_OVERLAP=200
+
+# ─── UI Branding (NEXT_PUBLIC_ = safe to expose to browser) ───
+NEXT_PUBLIC_PROJECT_ID=my-project
+NEXT_PUBLIC_UI_TITLE=AI Assistant
+NEXT_PUBLIC_UI_SUBTITLE=Powered by RAG
+NEXT_PUBLIC_PRIMARY_COLOR=#6366f1
+NEXT_PUBLIC_ACCENT_COLOR=#8b5cf6
+NEXT_PUBLIC_PLACEHOLDER=Ask me anything…
+NEXT_PUBLIC_SHOW_SOURCES=true
+NEXT_PUBLIC_WELCOME_MESSAGE=Hello! I'm your AI assistant. Ask me anything about your documents.
+# NEXT_PUBLIC_LOGO_URL=https://your-domain.com/logo.png

package/README.md

@@ -0,0 +1,149 @@
+# @abhinav1201/rag-ai-accelerator
+
+> **Retrivora AI is a plug-and-play AI engine for RAG chat experiences** that can be embedded into Next.js apps or used as a standalone demo app. Bring your own vector database, LLM, embeddings, and UI branding.
+
+[![NPM Version](https://img.shields.io/npm/v/@abhinav1201/rag-ai-accelerator?style=flat-square&color=10b981)](https://www.npmjs.com/package/@abhinav1201/rag-ai-accelerator)
+[![NPM Downloads](https://img.shields.io/npm/dm/@abhinav1201/rag-ai-accelerator?style=flat-square&color=3b82f6)](https://www.npmjs.com/package/@abhinav1201/rag-ai-accelerator)
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?style=flat-square&logo=github)](https://github.com/abhinav1201/ai-accelerator)
+![Next.js](https://img.shields.io/badge/Next.js-14+-black?style=flat-square&logo=next.js)
+![TailwindCSS](https://img.shields.io/badge/TailwindCSS-v4-38bdf8?style=flat-square&logo=tailwindcss)
+
+---
+
+## ✨ Features
+
+| Category | Options |
+|---|---|
+| **Vector DBs** | Pinecone, pgVector (PostgreSQL), MongoDB Atlas, ChromaDB, Qdrant, universal REST adapters |
+| **LLM Providers** | OpenAI, Anthropic Claude, Google Gemini, Ollama, LiteLLM, universal REST adapters |
+| **Document Ingestion** | Universal support for **PDF**, **DOCX**, **CSV**, **JSON**, **MD**, **TXT** |
+| **UI** | Full-page `ChatWindow` + floating `ChatWidget`, fully branded & responsive |
+| **RAG** | Configurable chunk size/overlap, top-K retrieval, score threshold, namespaced multi-tenancy |
+
+---
+
+## 🚀 How it Works
+
+Retrivora AI acts as a universal bridge between your data and your users. It normalizes different AI providers and Vector databases into a single interface.
+
+1.  **Ingest**: Upload or send documents to the `/api/upload` endpoint. They are automatically parsed, chunked, and embedded.
+2.  **Retrieve**: When a user asks a question, the system converts it to a vector and searches your configured database.
+3.  **Generate**: The retrieved context is combined with the user query and sent to your configured LLM (OpenAI, Claude, etc.) to generate a grounded response.
+
+### 📦 How to Install
+
+To integrate Retrivora AI into your existing Next.js project, simply run:
+
+```bash
+npm install @abhinav1201/rag-ai-accelerator
+```
+
+Alternatively, if you want to run the standalone demo application:
+
+```bash
+git clone https://github.com/abhinav1201/ai-accelerator
+cd ai-accelerator
+npm install
+cp .env.example .env.local
+# Fill in your API keys in .env.local
+npm run dev
+```
+
+---
+
+## NPM Package Usage
+
+### 1. Embed the ChatWidget
+
+Wrap your application in the `ConfigProvider` and add the `ChatWidget`.
+
+```tsx
+import { ConfigProvider, ChatWidget } from '@abhinav1201/rag-ai-accelerator';
+
+export default function Layout({ children }) {
+  return (
+    <ConfigProvider
+      config={{
+        projectId: 'my-project',
+        ui: {
+          title: 'Support Bot',
+          primaryColor: '#6366f1',
+          accentColor: '#8b5cf6',
+          welcomeMessage: 'Hi! How can I help you today?',
+        },
+      }}
+    >
+      {children}
+      <ChatWidget position="bottom-right" />
+    </ConfigProvider>
+  );
+}
+```
+
+### 2. Mount the API routes
+
+Create standard Next.js route handlers and plug in the library's factories.
+
+```ts
+// src/app/api/chat/route.ts
+import { createChatHandler, getRagConfig } from '@abhinav1201/rag-ai-accelerator/server';
+export const POST = createChatHandler(getRagConfig());
+
+// src/app/api/upload/route.ts (Handles PDF, DOCX, etc.)
+import { createUploadHandler, getRagConfig } from '@abhinav1201/rag-ai-accelerator/server';
+export const POST = createUploadHandler(getRagConfig());
+```
+
+### 3. Use RAGPipeline programmatically
+
+```ts
+import { RAGPipeline } from '@abhinav1201/rag-ai-accelerator/server';
+
+const pipeline = new RAGPipeline(config);
+await pipeline.ingest([{ docId: 'readme', content: 'Your document text here' }]);
+const { reply, sources } = await pipeline.ask('What is the refund policy?');
+```
+
+---
+
+## Configuration Reference
+
+The library is entirely dynamic. You can switch between providers simply by updating your environment variables.
+
+| Variable | Description |
+|---|---|
+| `RAG_PROJECT_ID` | Project namespace for data isolation |
+| `VECTOR_DB_PROVIDER` | `pinecone`, `pgvector`, `mongodb`, or `universal_rest` |
+| `VECTOR_UNIVERSAL_PROFILE` | `pinecone-rest`, `mongodb-atlas`, `chromadb`, `qdrant` |
+| `LLM_PROVIDER` | `openai`, `anthropic`, `ollama`, or `universal_rest` |
+| `LLM_UNIVERSAL_PROFILE` | `openai-compatible`, `litellm`, `anthropic-claude`, `google-gemini` |
+| `EMBEDDING_PROVIDER` | `openai`, `ollama`, or `rest` |
+
+---
+
+## Architecture
+
+```
+User Query
+   |
+   v
+[embed query]  <-- EmbeddingProvider (OpenAI / Ollama / Custom)
+   |
+   v
+[vector search]  <-- IVectorDB (Pinecone / pgVector / MongoDB / Chroma / REST)
+   |
+   v
+[build context]
+   |
+   v
+[LLM chat]  <-- ILLMProvider (OpenAI / Anthropic / Gemini / LiteLLM)
+   |
+   v
+ChatResponse { reply, sources[] }
+```
+
+---
+
+## License
+
+MIT - GSPANN Technologies

package/dist/DocumentChunker-BUrIrcPk.d.mts

@@ -0,0 +1,43 @@
+/**
+ * DocumentChunker — splits long text into overlapping chunks
+ * suitable for vector embedding and retrieval.
+ *
+ * Strategy: sentence-aware sliding window
+ *   1. Split on sentence boundaries
+ *   2. Accumulate sentences into chunks up to `chunkSize` characters
+ *   3. Carry over `chunkOverlap` characters from the previous chunk
+ */
+interface Chunk {
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+interface ChunkOptions {
+    /** Target chunk size in characters (default 1000) */
+    chunkSize?: number;
+    /** Overlap between consecutive chunks in characters (default 200) */
+    chunkOverlap?: number;
+    /** Source document identifier used as ID prefix */
+    docId?: string;
+    /** Extra metadata to attach to every chunk */
+    metadata?: Record<string, unknown>;
+}
+declare class DocumentChunker {
+    private readonly chunkSize;
+    private readonly chunkOverlap;
+    constructor(chunkSize?: number, chunkOverlap?: number);
+    /**
+     * Split a single text string into overlapping chunks.
+     */
+    chunk(text: string, options?: ChunkOptions): Chunk[];
+    /**
+     * Chunk multiple documents at once.
+     */
+    chunkMany(documents: Array<{
+        content: string;
+        docId?: string;
+        metadata?: Record<string, unknown>;
+    }>): Chunk[];
+}
+
+export { type Chunk as C, DocumentChunker as D, type ChunkOptions as a };

package/dist/DocumentChunker-BUrIrcPk.d.ts

@@ -0,0 +1,43 @@
+/**
+ * DocumentChunker — splits long text into overlapping chunks
+ * suitable for vector embedding and retrieval.
+ *
+ * Strategy: sentence-aware sliding window
+ *   1. Split on sentence boundaries
+ *   2. Accumulate sentences into chunks up to `chunkSize` characters
+ *   3. Carry over `chunkOverlap` characters from the previous chunk
+ */
+interface Chunk {
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+interface ChunkOptions {
+    /** Target chunk size in characters (default 1000) */
+    chunkSize?: number;
+    /** Overlap between consecutive chunks in characters (default 200) */
+    chunkOverlap?: number;
+    /** Source document identifier used as ID prefix */
+    docId?: string;
+    /** Extra metadata to attach to every chunk */
+    metadata?: Record<string, unknown>;
+}
+declare class DocumentChunker {
+    private readonly chunkSize;
+    private readonly chunkOverlap;
+    constructor(chunkSize?: number, chunkOverlap?: number);
+    /**
+     * Split a single text string into overlapping chunks.
+     */
+    chunk(text: string, options?: ChunkOptions): Chunk[];
+    /**
+     * Chunk multiple documents at once.
+     */
+    chunkMany(documents: Array<{
+        content: string;
+        docId?: string;
+        metadata?: Record<string, unknown>;
+    }>): Chunk[];
+}
+
+export { type Chunk as C, DocumentChunker as D, type ChunkOptions as a };

package/dist/RAGPipeline-BmkIv1HD.d.mts

@@ -0,0 +1,298 @@
+/**
+ * Generic LLM Provider interface.
+ * Covers both chat completion and embedding generation so a single
+ * provider can handle both responsibilities when appropriate.
+ */
+interface ChatMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+interface ChatOptions {
+    /** Override max tokens for this specific call */
+    maxTokens?: number;
+    /** Override temperature for this specific call */
+    temperature?: number;
+    /** Stop sequences */
+    stop?: string[];
+}
+interface EmbedOptions {
+    /** Override model for this specific embed call */
+    model?: string;
+}
+interface ILLMProvider {
+    /**
+     * Send a chat completion request.
+     * @param messages – the full conversation history
+     * @param context  – retrieved RAG context to inject
+     * @param options  – optional per-call overrides
+     * @returns        – the assistant's reply text
+     */
+    chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string>;
+    /**
+     * Generate an embedding vector for the given text.
+     * @param text    – text to embed
+     * @param options – optional overrides
+     * @returns       – float array (the embedding)
+     */
+    embed(text: string, options?: EmbedOptions): Promise<number[]>;
+    /**
+     * Generate embedding vectors for multiple texts in a single batch.
+     * @param texts   – array of texts to embed
+     * @param options – optional overrides
+     * @returns       – array of float arrays
+     */
+    batchEmbed(texts: string[], options?: EmbedOptions): Promise<number[][]>;
+    /**
+     * Check if the provider endpoint is reachable.
+     */
+    ping(): Promise<boolean>;
+}
+
+/**
+ * Generic Vector Database interface.
+ * Any adapter (Pinecone, pgVector, REST, Chroma, Qdrant, …) must implement this.
+ */
+interface VectorMatch {
+    /** Unique identifier of the stored chunk */
+    id: string;
+    /** Cosine or dot-product similarity score (0–1) */
+    score: number;
+    /** The original text content of the chunk */
+    content: string;
+    /** Arbitrary metadata attached at upsert time */
+    metadata?: Record<string, unknown>;
+}
+interface UpsertDocument {
+    id: string;
+    vector: number[];
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+interface IVectorDB {
+    /**
+     * Initialise the connection (create tables, verify index, etc.)
+     * Called once during RAGPipeline construction.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Insert or update a single vector + content pair.
+     * @param namespace – optional project/tenant namespace
+     */
+    upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
+    /**
+     * Batch upsert for efficient ingestion of many documents.
+     */
+    batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
+    /**
+     * Find the top-K most similar vectors to the query vector.
+     * @param vector     – embedding of the user query
+     * @param topK       – number of results to return
+     * @param namespace  – optional project/tenant namespace
+     * @param filter     – optional metadata filter (provider-specific shape)
+     */
+    query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]>;
+    /**
+     * Delete a stored vector by ID.
+     */
+    delete(id: string, namespace?: string): Promise<void>;
+    /**
+     * Delete all vectors in a namespace (full data reset for a project).
+     */
+    deleteNamespace(namespace: string): Promise<void>;
+    /**
+     * Check if the underlying DB is reachable.
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Gracefully close the connection.
+     */
+    disconnect(): Promise<void>;
+}
+
+/**
+ * Master configuration interface for Retrivora AI.
+ * Each consuming project provides one RagConfig object to drive
+ * vector DB selection, LLM selection, embedding, and UI branding.
+ */
+type VectorDBProvider = 'pinecone' | 'pgvector' | 'mongodb' | 'rest' | 'universal_rest' | 'custom';
+interface VectorDBConfig {
+    /** Which vector database to use */
+    provider: VectorDBProvider;
+    /** The index / table name to query */
+    indexName: string;
+    /** Provider-specific options (API keys, connection strings, etc.)
+     *
+     * For 'universal_rest', the following options are supported:
+     * - baseUrl: string
+     * - headers?: Record<string, string>
+     * - queryPath?: string
+     * - upsertPath?: string
+     * - queryPayloadTemplate?: string (e.g. '{"vector": {{vector}}, "limit": {{topK}}}')
+     * - upsertPayloadTemplate?: string (e.g. '{"id": "{{id}}", "vector": {{vector}}}')
+     * - responseExtractPath?: string (e.g. 'data.results')
+     * - idPath?: string (e.g. '_id')
+     * - scorePath?: string (e.g. 'similarity')
+     * - contentPath?: string (e.g. 'text')
+     */
+    options: Record<string, unknown>;
+}
+type LLMProvider = 'openai' | 'anthropic' | 'ollama' | 'rest' | 'universal_rest' | 'custom';
+interface LLMConfig {
+    /** Which LLM provider to use */
+    provider: LLMProvider;
+    /** Model name, e.g. "gpt-4o", "claude-3-opus-20240229", "llama3" */
+    model: string;
+    /** API key for cloud providers */
+    apiKey?: string;
+    /** Base URL — required for Ollama or self-hosted endpoints */
+    baseUrl?: string;
+    /** Custom system prompt injected before every chat */
+    systemPrompt?: string;
+    /** Max tokens in the LLM response */
+    maxTokens?: number;
+    /** Sampling temperature (0–1) */
+    temperature?: number;
+    /** Provider-specific options
+     *
+     * For 'universal_rest', the following options are supported:
+     * - headers?: Record<string, string>
+     * - chatPath?: string
+     * - chatPayloadTemplate?: string (e.g. '{"prompt": "{{prompt}}", "max_tokens": {{maxTokens}}}')
+     * - responseExtractPath?: string (e.g. 'choices[0].text' or 'response')
+     */
+    options?: Record<string, unknown>;
+}
+type EmbeddingProvider = 'openai' | 'ollama' | 'rest' | 'universal_rest' | 'custom';
+interface EmbeddingConfig {
+    /** Which embedding provider to use */
+    provider: EmbeddingProvider;
+    /** Model name, e.g. "text-embedding-ada-002", "nomic-embed-text" */
+    model: string;
+    /** API key (if needed) */
+    apiKey?: string;
+    /** Base URL for custom / Ollama embedding endpoints */
+    baseUrl?: string;
+    /** Output vector dimension — must match the index dimension */
+    dimensions?: number;
+    /** Provider-specific options for custom adapters */
+    options?: Record<string, unknown>;
+}
+interface UIConfig {
+    /** Title shown in the chat header */
+    title?: string;
+    /** Subtitle / description below the title */
+    subtitle?: string;
+    /** Primary brand colour (CSS colour string) */
+    primaryColor?: string;
+    /** Accent colour for user message bubbles */
+    accentColor?: string;
+    /** URL to a logo image */
+    logoUrl?: string;
+    /** Input placeholder text */
+    placeholder?: string;
+    /** Show source cards after each answer */
+    showSources?: boolean;
+    /** Welcome message shown on first load */
+    welcomeMessage?: string;
+    /** Whether to show the floating chat widget. Defaults to true. */
+    showWidget?: boolean;
+    /** Custom 'Powered by' text shown in the header */
+    poweredBy?: string;
+    /** Visual style: 'glass' (default) or 'solid' */
+    visualStyle?: 'glass' | 'solid';
+    /** Border radius: 'none', 'sm', 'md', 'lg', 'xl', 'full' */
+    borderRadius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+}
+interface RAGConfig {
+    /** Number of top-K chunks retrieved per query */
+    topK?: number;
+    /** Minimum similarity score to include a chunk (0–1) */
+    scoreThreshold?: number;
+    /** Target chunk size in tokens */
+    chunkSize?: number;
+    /** Overlap between adjacent chunks in tokens */
+    chunkOverlap?: number;
+}
+interface RagConfig {
+    /**
+     * Unique identifier for the consuming project.
+     * Used as the vector DB namespace to achieve multi-tenancy.
+     */
+    projectId: string;
+    /** Vector database configuration */
+    vectorDb: VectorDBConfig;
+    /** LLM configuration */
+    llm: LLMConfig;
+    /** Embedding configuration */
+    embedding: EmbeddingConfig;
+    /** Optional UI branding overrides */
+    ui?: UIConfig;
+    /** Optional RAG pipeline tuning knobs */
+    rag?: RAGConfig;
+}
+
+/**
+ * RAGPipeline — the central orchestrator for the RAG workflow.
+ *
+ * Responsibilities:
+ *  1. INGEST:  chunk → embed → upsert into vector DB
+ *  2. ASK:     embed query → retrieve top-K chunks → call LLM with context
+ *
+ * It is LLM-agnostic and vector-DB-agnostic; concrete implementations are
+ * injected via ILLMProvider and IVectorDB.
+ */
+
+interface IngestDocument {
+    /** Unique document ID (used as chunk ID prefix) */
+    docId: string;
+    /** Full text content of the document */
+    content: string;
+    /** Optional metadata stored alongside each chunk */
+    metadata?: Record<string, unknown>;
+}
+interface ChatResponse {
+    /** The LLM's answer */
+    reply: string;
+    /** Retrieved source chunks used to generate the answer */
+    sources: VectorMatch[];
+}
+declare class RAGPipeline {
+    private readonly vectorDB;
+    private readonly llmProvider;
+    private readonly embeddingProvider;
+    private readonly chunker;
+    private readonly config;
+    private initialised;
+    constructor(config: RagConfig, adapters?: {
+        vectorDB?: IVectorDB;
+        llmProvider?: ILLMProvider;
+        embeddingProvider?: ILLMProvider;
+    });
+    /** Lazily initialise the vector DB connection */
+    init(): Promise<void>;
+    /**
+     * Ingest one or more documents into the vector DB.
+     * Automatically chunks, embeds, and upserts each chunk.
+     */
+    ingest(documents: IngestDocument[], namespace?: string): Promise<{
+        docId: string;
+        chunksIngested: number;
+    }[]>;
+    /**
+     * Run a full RAG query:
+     *  1. Embed the user question
+     *  2. Retrieve top-K relevant chunks from the vector DB
+     *  3. Filter by score threshold
+     *  4. Build context string
+     *  5. Call the LLM with chat history + context
+     */
+    ask(question: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
+    health(): Promise<{
+        vectorDB: boolean;
+        llm: boolean;
+    }>;
+    deleteDocument(docId: string, namespace?: string): Promise<void>;
+    deleteProject(namespace?: string): Promise<void>;
+}
+
+export { type ChatMessage as C, type EmbedOptions as E, type ILLMProvider as I, type LLMConfig as L, type RAGConfig as R, type UIConfig as U, type VectorMatch as V, type ChatOptions as a, type ChatResponse as b, type EmbeddingConfig as c, type IVectorDB as d, type IngestDocument as e, type RagConfig as f, type UpsertDocument as g, type VectorDBConfig as h, RAGPipeline as i };