@devilsdev/rag-pipeline-utils 1.0.1 → 2.0.1

package/src/mocks/openai-embedder.js

@@ -0,0 +1,30 @@
+/**
+ * Version: 0.1.0
+ * File: /src/mocks/openai-embedder.js
+ * Description: Mock implementation of an OpenAI embedder
+ * Author: Ali Kahwaji
+ */
+
+export default class OpenAIEmbedder {
+  /**
+   * Returns static vector embeddings for input chunks
+   * @param {string[]} chunks
+   * @returns {Promise<Array<{ id: string, values: number[], metadata: { text: string } }>>}
+   */
+  async embed(chunks) {
+    return chunks.map((text, i) => ({
+      id: `v${i}`,
+      values: [0.1, 0.2, 0.3],
+      metadata: { text },
+    }));
+  }
+
+  /**
+   * Returns a static vector for the given query prompt
+   * @param {string} prompt
+   * @returns {Promise<number[]>}
+   */
+  async embedQuery(prompt) {
+    return [0.1, 0.2, 0.3];
+  }
+}

package/src/mocks/openai-llm.js

@@ -0,0 +1,18 @@
+/**
+ * Version: 0.1.0
+ * File: /src/mocks/openai-llm.js
+ * Description: Mock implementation of an OpenAI LLM
+ * Author: Ali Kahwaji
+ */
+
+export default class OpenAILLM {
+    /**
+     * Generates a static answer from input prompt and context
+     * @param {string} prompt
+     * @param {Array<{ text: string }>} context
+     * @returns {Promise<string>}
+     */
+    async generate(prompt, context) {
+      return `Generated answer using: ${context.map(d => d.text).join(', ')}`;
+    }
+  }

package/src/mocks/pdf-loader.js

@@ -0,0 +1,17 @@
+/**
+ * Version: 0.1.0
+ * File: /src/mocks/pdf-loader.js
+ * Description: Mock implementation of a PDF document loader
+ * Author: Ali Kahwaji
+ */
+
+export default class PDFLoader {
+  /**
+   * Loads a mock PDF file and returns an array of chunked content.
+   * @param {string} filePath - Path to the PDF file
+   * @returns {Promise<Array<{ chunk: () => string[] }>>}
+   */
+  async load(filePath) {
+    return [{ chunk: () => [`Test loaded: ${filePath}`] }];
+  }
+}

package/src/mocks/pinecone-retriever.js

@@ -0,0 +1,25 @@
+/**
+ * Version: 0.1.0
+ * File: /src/mocks/pinecone-retriever.js
+ * Description: Mock implementation of a Pinecone retriever
+ * Author: Ali Kahwaji
+ */
+
+export default class PineconeRetriever {
+    /**
+     * Mocks vector storage (no-op).
+     */
+    async store() {}
+  
+    /**
+     * Returns mock retrieved documents
+     * @returns {Promise<Array<{ id: string, text: string, metadata: object }>>}
+     */
+    async retrieve() {
+      return [
+        { id: 'a', text: 'Chunk about pine trees', metadata: {} },
+        { id: 'b', text: 'Chunk about vectors', metadata: {} },
+        { id: 'c', text: 'Chunk about databases', metadata: {} },
+      ];
+    }
+  }

package/src/reranker/llm-reranker.js

@@ -1,49 +1,34 @@
 /**
- * Version: 0.1.0
- * Path: /src/reranker/llm-reranker.js
- * Description: LLM-based reranker that reorders retrieved context for relevance
- * Author: Ali Kahwaji
+ * Version: 1.0.4
+ * Description: LLM reranker using LLM to reorder documents based on relevance
+ * Author: devilsdev
+ * File: src/reranker/llm-reranker.js
  */
 
-/**
- * LLMReranker ranks context chunks by relevance to a given prompt.
- * @interface
- */
 export class LLMReranker {
-    constructor({ llm }) {
-      if (!llm || typeof llm.generate !== 'function') {
-        throw new Error('LLM instance must implement generate(prompt, context)');
-      }
-      this.llm = llm;
-    }
-  
-    /**
-     * Reranks retrieved context chunks using the LLM.
-     * @param {string} prompt - The user's question or query
-     * @param {Array<{ text: string, metadata?: object }>} documents - Retrieved context chunks
-     * @param {number} [topK=5] - Number of top-ranked documents to return
-     * @returns {Promise<Array>} - Reranked top K chunks
-     */
-    async rerank(prompt, documents, topK = 5) {
-      const contextText = documents.map((d, i) => `Chunk ${i + 1}: ${d.text}`).join('\n');
-  
-      const instruction = `Rank the following document chunks by how well they answer the prompt.\n
-  Prompt: ${prompt}\n
-  Chunks:\n${contextText}\n
-  Respond with a JSON array of chunk indexes in descending order of relevance.`;
-  
-      const result = await this.llm.generate(instruction, []);
-  
-      let indexOrder = [];
-      try {
-        indexOrder = JSON.parse(result.match(/\[.*\]/s)?.[0] || '[]');
-      } catch (err) {
-        console.warn('Failed to parse reranker output:', result);
-        return documents.slice(0, topK); // fallback
-      }
-  
-      const ranked = indexOrder.map(i => documents[i]).filter(Boolean);
-      return ranked.slice(0, topK);
+  /**
+   * @param {Object} options
+   * @param {{ generate(prompt: string): Promise<string> }} options.llm - An LLM client with a `generate` method
+   */
+  constructor({ llm }) {
+    this.llm = llm;
+  }
+
+  /**
+   * Rerank documents based on the LLM output
+   * @param {string} query
+   * @param {Array<{ text: string }>} docs
+   * @returns {Promise<Array<{ text: string }>>}
+   */
+  async rerank(query, docs) {
+    const prompt = `Given the query: "${query}", rank the following documents by relevance: \n${docs.map((d, i) => `[${i}]: ${d.text}`).join('\n')}\nReturn an array of indices like [2, 0, 1]`;
+
+    try {
+      const json = await this.llm.generate(prompt);
+      const indices = JSON.parse(json);
+      return indices.map(i => docs[i]).filter(Boolean);
+    } catch (err) {
+      return docs; // Fallback if LLM response is not parsable
     }
   }
-  
+}

package/src/utils/ci/diagnostic-reporter.js

@@ -0,0 +1,36 @@
+/**
+ * Version: 1.0.0
+ * Description: Enhanced CI diagnostics for plugin mock verification
+ * Author: Ali Kahwaji
+ */
+
+import path from 'path';
+import chalk from 'chalk';
+
+/**
+ * Pretty prints CI validation errors and guidance
+ * @param {Array<{ file: string, missing: string[] }>} failures
+ */
+export function reportPluginValidationFailures(failures) {
+  if (!failures.length) return;
+
+  console.log(`\n${chalk.redBright.bold('❌ Plugin Mock Validation Failed')}`);
+
+  failures.forEach(({ file, missing }) => {
+    const fileName = path.basename(file);
+    console.log(
+      `${chalk.red(`  ✖ ${fileName}`)} ${chalk.gray(`missing: ${missing.join(', ')}`)}`
+    );
+
+    // Add method-level fix hints
+    missing.forEach(method => {
+      const pluginType = fileName.split('.')[0].split('-')[1] || 'unknown';
+      console.error(`    → Fix: implement method ${chalk.cyan(`${method}()`)} for plugin type ${chalk.yellow(pluginType)}`);
+    });
+  });
+
+  console.log(`\n${chalk.yellowBright('Recommended Fixes:')}`);
+  console.log('  • Implement all required methods defined in /src/core/plugin-contracts.js');
+  console.log(`  • Re-run: ${chalk.cyan('npm run ci')} to confirm validation`);
+  console.log(`  • Optionally use: ${chalk.cyan('scripts/repair-fixtures.js')} to auto-repair mocks\n`);
+}

package/src/utils/validate-plugin-contract.js

@@ -0,0 +1,36 @@
+/**
+ * Version: 1.0.0
+ * Description: Type-safe plugin contract validator for runtime safety
+ * Author: Ali Kahwaji
+ * File: /src/utils/validate-plugin-contract.js
+ */
+
+import { pluginContracts } from '../core/plugin-contracts.js';
+
+/**
+ * Validates that a plugin instance implements all required methods.
+ * @param {string} type - Plugin type (e.g. 'loader', 'embedder')
+ * @param {object} instance - Instantiated plugin module
+ * @param {string} filePath - Path to plugin (used in error reporting)
+ * @throws {Error} if any required method is missing or not a function
+ */
+export function validatePluginContract(type, instance, filePath) {
+  const expectedMethods = pluginContracts[type];
+  if (!expectedMethods) {
+    throw new Error(`[validatePluginContract] Unknown plugin type: ${type}`);
+  }
+
+  const missing = expectedMethods.filter(method =>
+    typeof instance[method] !== 'function'
+  );
+
+  if (missing.length > 0) {
+    throw new Error(
+      `[validatePluginContract] Plugin '${filePath}' is missing required methods for '${type}': ${missing.join(', ')}`
+    );
+  }
+}
+
+/**
+ * Optionally wraps plugin instance with a Proxy for method usage auditing (see enforcePluginProxy)
+ */

package/.github/workflows/release.yml

@@ -1,20 +0,0 @@
-name: Release
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          registry-url: 'https://registry.npmjs.org/'
-      - run: npm ci
-      - run: npx semantic-release
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/docs-site/blog/2019-05-28-first-blog-post.md

@@ -1,12 +0,0 @@
----
-slug: first-blog-post
-title: First Blog Post
-authors: [slorber, yangshun]
-tags: [hola, docusaurus]
----
-
-Lorem ipsum dolor sit amet...
-
-<!-- truncate -->
-
-...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

package/docs-site/blog/2019-05-29-long-blog-post.md

@@ -1,44 +0,0 @@
----
-slug: long-blog-post
-title: Long Blog Post
-authors: yangshun
-tags: [hello, docusaurus]
----
-
-This is the summary of a very long blog post,
-
-Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
-
-<!-- truncate -->
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

package/docs-site/blog/2021-08-01-mdx-blog-post.mdx

@@ -1,24 +0,0 @@
----
-slug: mdx-blog-post
-title: MDX Blog Post
-authors: [slorber]
-tags: [docusaurus]
----
-
-Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/).
-
-:::tip
-
-Use the power of React to create interactive blog posts.
-
-:::
-
-{/* truncate */}
-
-For example, use JSX to create an interactive button:
-
-```js
-<button onClick={() => alert('button clicked!')}>Click me!</button>
-```
-
-<button onClick={() => alert('button clicked!')}>Click me!</button>