@devilsdev/rag-pipeline-utils 2.1.5 → 2.1.8

package/__tests__/unit/config/validate-schema.test.js

@@ -1,121 +0,0 @@
-/**
- * Version: 1.1.0
- * Description: Schema validation tests for .ragrc.json using AJV and external fixtures
- * Author: Ali Kahwaji
- * File: __tests__/unit/config/validate-schema.test.js
- */
-
-import { readFileSync } from 'fs';
-import { resolve } from 'path';
-import { validateRagrcSchema, validatePluginSchema } from '../../../src/config/validate-schema.js';
-
-const readFixture = (name) => {
-  const filePath = resolve('__tests__/fixtures',name.replace('.ragrc', '-ragrc'));
-  return JSON.parse(readFileSync(filePath, 'utf-8'));
-};
-
-describe('validateRagrcSchema', () => {
-  test('passes with valid structured plugin schema', () => {
-    const config = readFixture('valid-ragrc.json');
-    const result = validateRagrcSchema(config);
-    expect(result.valid).toBe(true);
-    expect(result.errors).toBeUndefined(); // updated: null => undefined
-  });
-
-  test('fails with missing pipeline', () => {
-    const config = {
-      loader: { pdf: './src/mocks/pdf-loader.js' },
-      namespace: 'no-pipeline'
-    };
-    const result = validateRagrcSchema(config);
-    expect(result.valid).toBe(false);
-    expect(result.errors).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          keyword: 'required',
-          params: expect.objectContaining({ missingProperty: 'pipeline' })
-        })
-      ])
-    );
-  });
-  
-  test('fails with non-object plugin sections', () => {
-    const config = {
-      loader: './src/invalid.js', // should be object
-      embedder: { openai: './src/mocks/openai-embedder.js' },
-      retriever: { pinecone: './src/mocks/pinecone-retriever.js' },
-      llm: { openai: './src/mocks/openai-llm.js' },
-      pipeline: ['loader'],
-      namespace: 'invalid-section'
-    };
-    const result = validateRagrcSchema(config);
-    expect(result.valid).toBe(false);
-    expect(result.errors).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({ instancePath: '/loader' })
-      ])
-    );
-  });
-
-  test('fails with non-string namespace', () => {
-    const config = {
-      loader: { pdf: './src/mocks/pdf-loader.js' },
-      embedder: { openai: './src/mocks/openai-embedder.js' },
-      retriever: { pinecone: './src/mocks/pinecone-retriever.js' },
-      llm: { openai: './src/mocks/openai-llm.js' },
-      pipeline: ['loader'],
-      namespace: 12345
-    };
-    const result = validateRagrcSchema(config);
-    expect(result.valid).toBe(false);
-    expect(result.errors).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({ instancePath: '/namespace' })
-      ])
-    );
-  });
-});
-
-describe('validatePluginSchema (subset)', () => {
-  test('passes with plugin-only valid structure', () => {
-    const config = {
-      loader: { pdf: './src/mocks/pdf-loader.js' },
-      embedder: { openai: './src/mocks/openai-embedder.js' },
-      retriever: { pinecone: './src/mocks/pinecone-retriever.js' },
-      llm: { openai: './src/mocks/openai-llm.js' }
-    };
-    const result = validatePluginSchema(config);
-    expect(result.valid).toBe(true);
-  });
-
-  test('fails when plugin section is missing', () => {
-    const config = {
-      embedder: { openai: './mock.js' },
-      retriever: { pinecone: './mock.js' },
-      llm: { openai: './mock.js' }
-    };
-    const result = validatePluginSchema(config);
-    expect(result.valid).toBe(false);
-    expect(result.errors).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({ instancePath: '', message: expect.stringContaining('must have required property') })
-      ])
-    );
-  });
-
-  test('fails when plugin paths are not strings', () => {
-    const config = {
-      loader: { pdf: 12345 },
-      embedder: { openai: './mock.js' },
-      retriever: { pinecone: './mock.js' },
-      llm: { openai: './mock.js' }
-    };
-    const result = validatePluginSchema(config);
-    expect(result.valid).toBe(false);
-    expect(result.errors).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({ instancePath: '/loader/pdf' })
-      ])
-    );
-  });
-});

package/__tests__/unit/core/plugin-registry.test.js

@@ -1,55 +0,0 @@
-/**
- * Version: 0.1.0
- * Path: /__tests__/unit/core/plugin-registry.test.js
- * Description: Unit tests for the PluginRegistry class
- * Author: Ali Kahwaji
- */
-
-import { PluginRegistry } from '../../../src/core/plugin-registry.js';
-
-describe('PluginRegistry', () => {
-  let registry;
-
-  beforeEach(() => {
-    registry = new PluginRegistry();
-  });
-
-  test('registers and retrieves a plugin successfully', () => {
-    const mockPlugin = { name: 'test-loader' };
-    registry.register('loader', 'test', mockPlugin);
-    const result = registry.get('loader', 'test');
-    expect(result).toBe(mockPlugin);
-  });
-
-  test('overwrites existing plugin under the same name', () => {
-    const firstPlugin = { name: 'first' };
-    const secondPlugin = { name: 'second' };
-    registry.register('embedder', 'dup', firstPlugin);
-    registry.register('embedder', 'dup', secondPlugin);
-    const result = registry.get('embedder', 'dup');
-    expect(result).toBe(secondPlugin);
-  });
-
-  test('throws error for unknown plugin type on registration', () => {
-    expect(() => registry.register('unknown-type', 'x', {})).toThrow(/Unknown plugin type/);
-  });
-
-  test('throws error when retrieving a nonexistent plugin', () => {
-    expect(() => registry.get('retriever', 'missing')).toThrow(/Plugin not found/);
-  });
-
-  test('lists all registered plugin names for a type', () => {
-    registry.register('llm', 'gpt-4', {});
-    registry.register('llm', 'gpt-3.5', {});
-    const list = registry.list('llm');
-    expect(list).toContain('gpt-4');
-    expect(list).toContain('gpt-3.5');
-    expect(list.length).toBe(2);
-  });
-
-  test('throws error when listing plugins for invalid type', () => {
-    expect(() => registry.list('invalid')).toThrow(/Unknown plugin type/);
-  });
-});
-
-

package/__tests__/unit/reranker/__snapshots__/reranker.snapshot.test.js.snap

@@ -1,15 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`LLMReranker output snapshot 1`] = `
-[
-  {
-    "text": "B",
-  },
-  {
-    "text": "A",
-  },
-  {
-    "text": "C",
-  },
-]
-`;

package/__tests__/unit/reranker/llm-reranker.test.js

@@ -1,18 +0,0 @@
-/**
- * File: __tests__/unit/reranker/llm-reranker.test.js
- * Version: 1.0.0
- * Description: Validates core behavior of the LLMReranker module
- * Author: @devilsdev
- */
-
-import { LLMReranker } from '../../../src/reranker/llm-reranker.js';
-
-describe('LLMReranker', () => {
-  test('returns reranked documents based on mock LLM JSON output', async () => {
-    const mockLLM = { async generate() { return '[1, 0, 2]'; } };
-    const docs = [{ text: 'A' }, { text: 'B' }, { text: 'C' }];
-    const reranker = new LLMReranker({ llm: mockLLM });
-    const result = await reranker.rerank('What is A?', docs);
-    expect(result.map(d => d.text)).toEqual(['B', 'A', 'C']);
-  });
-});

package/__tests__/unit/reranker/reranker.enriched.test.js

@@ -1,19 +0,0 @@
-/**
- * File: __tests__/unit/reranker/reranker.enriched.test.js
- * Version: 1.0.0
- * Description: Tests support for extended document structures
- * Author: @devilsdev
- */
-import { LLMReranker } from '../../../src/reranker/llm-reranker.js';
-
-test('supports documents with metadata', async () => {
-    const mockLLM = { async generate() { return '[2, 0, 1]'; } };
-    const docs = [
-      { text: 'One', source: 'alpha' },
-      { text: 'Two', source: 'beta' },
-      { text: 'Three', source: 'gamma' }
-    ];
-    const reranker = new LLMReranker({ llm: mockLLM });
-    const result = await reranker.rerank('Choose the most complete', docs);
-    expect(result[0]).toHaveProperty('source', 'gamma');
-  });

package/__tests__/unit/reranker/reranker.fallback.test.js

@@ -1,15 +0,0 @@
-/**
- * File: __tests__/unit/reranker/reranker.fallback.test.js
- * Version: 1.0.0
- * Description: Validates fallback handling for invalid LLM output
- * Author: @devilsdev
- */
-import { LLMReranker } from '../../../src/reranker/llm-reranker.js';
-
-test('gracefully handles invalid LLM output', async () => {
-    const mockLLM = { async generate() { return 'INVALID_JSON'; } };
-    const docs = [{ text: 'X' }, { text: 'Y' }, { text: 'Z' }];
-    const reranker = new LLMReranker({ llm: mockLLM });
-    const result = await reranker.rerank('Prompt?', docs);
-    expect(result.map(d => d.text)).toEqual(['X', 'Y', 'Z']);
-  });

package/__tests__/unit/reranker/reranker.snapshot.test.js

@@ -1,15 +0,0 @@
-/**
- * File: __tests__/unit/reranker/reranker.snapshot.test.js
- * Version: 1.0.0
- * Description: Captures a snapshot baseline of reranked results
- * Author: @devilsdev
- */
-import { LLMReranker } from '../../../src/reranker/llm-reranker.js';
-
-test('LLMReranker output snapshot', async () => {
-  const mockLLM = { async generate() { return '[1, 0, 2]'; } };
-  const mockDocs = [{ text: 'A' }, { text: 'B' }, { text: 'C' }];
-  const reranker = new LLMReranker({ llm: mockLLM });
-  const result = await reranker.rerank('What is A?', mockDocs);
-  expect(result).toMatchSnapshot();
-});

package/__tests__/unit/reranker/reranker.structured-output.test.js

@@ -1,17 +0,0 @@
-/**
- * File: __tests__/unit/reranker/reranker.structured-output.test.js
- * Version: 1.0.0
- * Description: Validates structured LLM output parsing
- * Author: @devilsdev
- */
-import { LLMReranker } from '../../../src/reranker/llm-reranker.js';
-
-test('parses structured LLM JSON result', async () => {
-    const mockLLM = { async generate() {
-      return JSON.stringify({ ranking: [0, 2, 1] });
-    }};
-    const docs = [{ text: 'Alpha' }, { text: 'Beta' }, { text: 'Gamma' }];
-    const reranker = new LLMReranker({ llm: mockLLM });
-    const result = await reranker.rerank('Which is alpha?', docs);
-    expect(result[0].text).toBe('Alpha');
-  });

package/codecov.SHA256SUM

@@ -1 +0,0 @@
-0f7aadde579ebde1443ad2f977beada703f562997fdda603f213faf2a8559868  codecov

package/codecov.SHA256SUM.sig

@@ -1,16 +0,0 @@
------BEGIN PGP SIGNATURE-----
-
-iQIzBAABCgAdFiEEJwNOf9uFDgu8LGL/gGuyiu13mGkFAmf1418ACgkQgGuyiu13
-mGke3w/8DpgS1CDxKdV50CKy81LmiA995bEw2ePBRc90JzNrGX7m2JcFQr/GUITs
-JofhfQ6sxnvLLxTLAyiMI8Tcbr2yN/BIjBERIhN8b20zL3KGY6kVS85czQdPs0a7
-BlY3xp7VgCv24E/SWc0m367GvBjVnanhMg+hIoaK4HQpWOx+93GzaGZWCnISl6yh
-Zn13zn/b/oXwvd3iekh3qb918kPwq3F3Ufd8gHLf71gH0usDoRIUwVIMYMjuoMeI
-ceIjZYe1BLG+hNAUkqboi1GK8IJQH66hwyB82KQxUZG0zEOTwhbvFrIijR30BSk6
-KROFxxe8s1kuEZGI/zhKPXkYkjiIdXQQvMP7emsQeLQljRb2k3prUhHw7LyFTPla
-KRK9MX1BoLr1Iol0Py/y8luSBCNvAmeCmbh6uGWS/1SJ/mj6CiZibWIO40qH9NJI
-wDY/JHrTHA2W2EsvREegny7znurxk1ORwT2scEJobu/NiLQEvpz6fvHaKiBcX45z
-53pv1v0xlTFCEF6Vfg2geywIk4Dfi4l7dxyG9hyHtb1lQ0zwcz9KaAPhMjiJCUPa
-zGh0nN/xgkD9u7TNhOW3vG01R/wNW5BF+E8+04AO+RroV230m+a/e958I6pCd9M+
-N6FtNND7ZyIVoHiVA/v/tWc+ODZ5b9K8Q1Y6a0jkCbFZ3ZeCrPI=
-=onSD
------END PGP SIGNATURE-----

package/docs-site/README.md

@@ -1,41 +0,0 @@
-# Website
-
-This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
-
-### Installation
-
-```
-$ yarn
-```
-
-### Local Development
-
-```
-$ yarn start
-```
-
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
-
-### Build
-
-```
-$ yarn build
-```
-
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
-### Deployment
-
-Using SSH:
-
-```
-$ USE_SSH=true yarn deploy
-```
-
-Not using SSH:
-
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

package/docs-site/blog/2025-04-18-architecture-overview.md

@@ -1,16 +0,0 @@
----
-slug: architecture-overview
-title: RAG Architecture Overview
-authors: [ali]
-tags: [architecture, modular]
----
-
-Explore the modular RAG pipeline architecture. Components like loaders, embedders, retrievers, and generators are pluggable and testable.
-
-<!-- truncate -->
-
-## Key Concepts
-
-- Plugin registry for clean composition
-- Evaluation layer for metrics like BLEU and recall
-- CLI integration for dev-first workflows

package/docs-site/blog/2025-04-18-release-v2.1.1.md

@@ -1,13 +0,0 @@
----
-slug: release-v2.1.1
-title: ✨ Version v2.1.1 Released
-authors: [ali]
-tags: [release, changelog]
----
-
-RAG Pipeline Utils vv2.1.1 is now available on NPM!
-
-#### Highlights
-- 🚀 Auto-published blog from GitHub release
-- 📦 Version bump: v2.1.1
-- 📘 See CHANGELOG.md for full details

package/docs-site/blog/2025-04-19-prompt-engineering-best-practices.md

@@ -1,16 +0,0 @@
----
-slug: prompt-engineering-best-practices
-title: Prompt Engineering Best Practices
-authors: [ali]
-tags: [prompt-engineering, tutorials]
----
-
-Design better prompts for your LLM-driven RAG workflows using templating, in-context examples, and task-specific embeddings.
-
-<!-- truncate -->
-
-## Tips
-
-- Use instructions + context
-- Dynamically inject retrieved passages
-- Validate through CLI or dashboard

package/docs-site/blog/2025-04-20-image-showcase.md

@@ -1,14 +0,0 @@
----
-slug: image-showcase
-title: Image Showcase with LQIP
-authors: [ali]
-tags: [image, tutorials]
----
-
-Demonstration of how low-quality image placeholders (LQIP) improve blog UX and optimize web performance.
-
-<!-- truncate -->
-
-## Details
-
-This post showcases `BlogImage` and `BlogCard` with LQIP integration via Plaiceholder and SSR-safe fallbacks.

package/docs-site/blog/2025-04-20-release-2.1.1.md

@@ -1,21 +0,0 @@
-<!-- .github/release-template.md -->
-
-# 🔖 Release v2.1.1
-
-**Published:** `2025-04-20`  
-**Compare changes:** [View diff](https://github.com/DevilsDev/rag-pipeline-utils/compare/v2.0.0...v2.1.1)  
-**Contributors:** `3`  
-**Commits:** `17`
-
----
-
-## 📦 What's New
-
-- Placeholder for changelog details or highlights.
-
----
-
-## 📘 Changelog
-
-See full details in [CHANGELOG.md](/CHANGELOG.md)
-

package/docs-site/blog/2025-04-21-release-v2.1.3.md

@@ -1,13 +0,0 @@
----
-slug: release-v2.1.3
-title: ✨ Version v2.1.3 Released
-authors: [ali]
-tags: [release, changelog]
----
-
-RAG Pipeline Utils vv2.1.3 is now available on NPM!
-
-#### Highlights
-- 🚀 Auto-published blog from GitHub Release
-- 📦 Version bump: v2.1.3
-- 📘 See CHANGELOG.md for full details

package/docs-site/blog/2025-04-21-release-v2.1.4.md

@@ -1,13 +0,0 @@
----
-slug: release-v2.1.4
-title: ✨ Version v2.1.4 Released
-authors: [ali]
-tags: [release, changelog]
----
-
-RAG Pipeline Utils vv2.1.4 is now available on NPM!
-
-#### Highlights
-- 🚀 Auto-published blog from GitHub Release
-- 📦 Version bump: v2.1.4
-- 📘 See CHANGELOG.md for full details

package/docs-site/blog/authors.yml

@@ -1,5 +0,0 @@
-ali:
-  name: Ali Kahwaji
-  title: Creator & Maintainer of RAG Pipeline Utils
-  url: https://github.com/alikahwaji
-  image_url: /img/authors/ali.jpg

package/docs-site/blog/tags.yml

@@ -1,60 +0,0 @@
-# docs-site/blog/tags.yml
-# Description: Central tag definitions for Docusaurus blog filtering and grouping
-
-release:
-  label: Release
-  permalink: /blog/tags/release
-
-architecture:
-  label: Architecture
-  permalink: /blog/tags/architecture
-
-prompt-engineering:
-  label: Prompt Engineering
-  permalink: /blog/tags/prompt-engineering
-
-evaluation:
-  label: Evaluation
-  permalink: /blog/tags/evaluation
-
-tutorials:
-  label: Tutorials
-  permalink: /blog/tags/tutorials
-
-changelog:
-  label: Changelog
-  permalink: /blog/tags/changelog
-
-design:
-  label: Design
-  permalink: /blog/tags/design
-
-rag:
-  label: RAG
-  permalink: /blog/tags/rag
-
-developer-tools:
-  label: Developer Tools
-  permalink: /blog/tags/developer-tools
-
-modular:
-  label: Modular
-  permalink: /blog/tags/modular
-
-image:
-  label: Image
-  permalink: /blog/tags/image
-
-facebook:
-  label: Facebook
-  permalink: /blog/tags/facebook
-
-hello:
-  label: Hello
-  permalink: /blog/tags/hello
-
-docusaurus:
-  label: Docusaurus
-  permalink: /blog/tags/docusaurus
-
-

package/docs-site/docs/Architecture.md

@@ -1,76 +0,0 @@
-# Architecture
-
-This page outlines the internal architecture of the RAG pipeline utilities, emphasizing modularity, plugin design, and SOLID-compliant structure.
-
----
-
-## Core Design Philosophy
-
-The architecture adheres to enterprise-grade practices:
-
-- **Single Responsibility**: Each component handles one domain concern
-- **Pluggable Interfaces**: Any layer (loader, retriever, LLM) can be swapped
-- **Streaming-Ready**: Async flows support token-based output
-- **Environment-Safe**: Config via `.ragrc.json`, not hardcoded
-- **Testable**: All modules can be mocked and unit tested
-
----
-
-## Layered Components
-
-```
-+-------------------------+
-| createRagPipeline()     |
-+-------------------------+
-        |     |     |
-        ▼     ▼     ▼
-  Loader   Embedder  Retriever
-     ▼        |         ▼
-  Chunks   Embeddings  Context
-        \     |     /
-         ▼    ▼    ▼
-           LLM Runner
-             |
-           Output
-```
-
----
-
-## Core Interfaces
-
-Each plugin is registered via the `PluginRegistry` and looked up by key.
-
-```ts
-registry.register('loader', 'pdf', new PDFLoader())
-const loader = registry.get('loader', 'pdf');
-```
-
-All plugins implement interface contracts like:
-
-```ts
-interface Loader {
-  load(path: string): Promise<{ chunk(): string[] }[]>;
-}
-
-interface Embedder {
-  embed(chunks: string[]): Vector[];
-  embedQuery(prompt: string): Vector;
-}
-
-interface Retriever {
-  store(vectors: Vector[]): Promise<void>;
-  retrieve(query: Vector): Promise<Context[]>;
-}
-```
-
----
-
-## DAG Support
-
-The `dag-engine.js` module supports chaining multiple components:
-- Example: Summarize → Retrieve → Rerank → LLM
-- Enables more complex workflows than linear ingestion/query
-
----
-
-Next → [Evaluation](./Evaluation.md)

package/docs-site/docs/CLI.md

@@ -1,69 +0,0 @@
-# CLI Reference
-
-The CLI gives you interactive access to the RAG pipeline tools via terminal.
-
-Install globally (optional):
-```bash
-npm install -g @yourorg/rag-pipeline-utils
-```
-
-Or run directly from your project:
-```bash
-npx rag-pipeline <command>
-```
-
----
-
-## Commands
-
-### `ingest`
-```bash
-rag-pipeline ingest ./docs/sample.pdf --loader pdf
-```
-- Loads and indexes documents into vector store
-
-### `query`
-```bash
-rag-pipeline query "Explain vector databases" --llm openai-gpt-4
-```
-- Retrieves context and generates response
-
-### `evaluate`
-```bash
-rag-pipeline evaluate ./fixtures/eval.json
-```
-- Runs batch evaluation with BLEU/ROUGE scoring
-
-### `rerank`
-```bash
-rag-pipeline rerank "What is RAG?" --retriever pinecone
-```
-- Reorders retrieved context using an LLM reranker
-
----
-
-## `.ragrc.json` Config
-
-Defaults can be set in a file:
-```json
-{
-  "loader": "directory",
-  "embedder": "openai",
-  "retriever": "pinecone",
-  "llm": "openai-gpt-4",
-  "useReranker": true
-}
-```
-
----
-
-##  Docker Usage
-
-```bash
-docker build -t rag-pipeline .
-docker run --rm -v $PWD:/data rag-pipeline query "What is retrieval?"
-```
-
----
-
-Next → [Architecture](./Architecture.md)