@devilsdev/rag-pipeline-utils 2.1.1 → 2.1.2

package/.github/release-template.md

@@ -0,0 +1,20 @@
+<!-- .github/release-template.md -->
+
+# 🔖 Release v{{VERSION}}
+
+**Published:** `{{DATE}}`  
+**Compare changes:** [View diff](https://github.com/DevilsDev/rag-pipeline-utils/compare/{{PREVIOUS_TAG}}...v{{VERSION}})  
+**Contributors:** `{{CONTRIBUTORS}}`  
+**Commits:** `{{COMMITS}}`
+
+---
+
+## 📦 What's New
+
+- Placeholder for changelog details or highlights.
+
+---
+
+## 📘 Changelog
+
+See full details in [CHANGELOG.md](../../CHANGELOG.md)

package/.github/workflows/ci.yml

@@ -1,17 +1,15 @@
 # .github/workflows/ci.yml
-# Version: 0.1.0
-# Description: GitHub Actions CI pipeline for lint, test, and coverage
+# Version: 1.0.0
+# Description: Clean CI pipeline with lint, test, fixtures, coverage, and release
 # Author: Ali Kahwaji
 
 name: CI & Release
 
 on:
   push:
-    branches:
-      - main
+    branches: [main]
   pull_request:
-    branches:
-      - main
+    branches: [main]
 
 jobs:
   build-test-release:
@@ -38,27 +36,18 @@ jobs:
       - name: ✅ Run tests with coverage
         run: npm test
 
-      - name: 🚀 Semantic Release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # 👈 critical for npm publi
-        run: npx semantic-release
-
-      - name: 🧪 Run Tests with Coverage
-        run: npm test
-
-      - name: Validate Fixtures
+      - name: 🧪 Validate Fixtures
         run: npm run validate-fixtures
-      
-      - name: Lint code
-        run: npm run lint
-      
-      
+
       - name: 📊 Upload coverage to Codecov
         uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           slug: DevilsDev/rag-pipeline-utils
 
-      
+      - name: 🚀 Semantic Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release

package/.github/workflows/docs-ci.yml

@@ -0,0 +1,44 @@
+name: Docs CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs-site
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 18
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: '**/package-lock.json'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint codebase
+        run: npm run lint
+
+      - name: Validate docs build
+        run: npm run docs:build
+
+      - name: Run tests (optional)
+        run: npm test
+        if: ${{ always() }}
+
+      - name: Upload build artifacts (optional)
+        uses: actions/upload-artifact@v4
+        with:
+          name: docusaurus-build
+          path: docs-site/build

package/.github/workflows/docs-deploy.yml

@@ -1,11 +1,12 @@
-# .github/workflows/docs-deploy.yml
-# Version: 1.1.0
-# Description: Deploys Docusaurus to GitHub Pages on changes to documentation files
+# Version: 2.1.0
+# Description: Validates lint, test, and code coverage before deploy
 # Author: Ali Kahwaji
 
-name: 📚 Deploy Docusaurus Docs
+name: 🧪 Docs CI
 
 on:
+  pull_request:
+    branches: [main]
   push:
     branches: [main]
     paths:
@@ -17,15 +18,19 @@ on:
       - 'package.json'
 
 jobs:
-  deploy:
-    name: Deploy to GitHub Pages
+  validate:
+    name: Validate Build & Test
     runs-on: ubuntu-latest
 
+    defaults:
+      run:
+        working-directory: docs-site
+
     steps:
-      - name: 📥 Checkout repository
+      - name: 📥 Checkout code
         uses: actions/checkout@v4
 
-      - name: ⚙️ Setup Node.js
+      - name: 🧰 Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 20
@@ -33,14 +38,19 @@ jobs:
       - name: 📦 Install dependencies
         run: npm ci
 
-      - name: 🛠️ Build Docusaurus site
+      - name: 🧹 Lint
+        run: npm run lint
+
+      - name: 🛠️ Build
         run: npm run docs:build
 
-      - name: 🚀 Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v4
+      - name: ✅ Test
+        run: npm test
+
+      - name: 📊 Upload coverage
+        uses: codecov/codecov-action@v4
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs-site/build
-          publish_branch: gh-pages
-          user_name: github-actions[bot]
-          user_email: 41898282+github-actions[bot]@users.noreply.github.com
+          token: ${{ secrets.CODECOV_TOKEN }}
+          directory: ./coverage
+          flags: docusaurus
+          fail_ci_if_error: true

package/.github/workflows/publish-release-blog.yml

@@ -1,6 +1,6 @@
 # .github/workflows/publish-release-blog.yml
-# Version: 1.1.0
-# Description: Auto-publish blog post from CHANGELOG or prepared .md after NPM release
+# Version: 1.4.0
+# Description: Auto-publish blog post from GitHub Release event with metadata, compare link, and authorship info
 # Author: Ali Kahwaji
 
 name: ✨ Publish Release Blog Post
@@ -18,33 +18,53 @@ jobs:
       - name: ⬇️ Checkout main branch
         uses: actions/checkout@v4
         with:
-          ref: main         # ✅ Ensures blog is committed to 'main'
+          ref: main
           fetch-depth: 0
 
-      - name: 🔧 Set up Node.js
+      - name: 🛠 Setup GitHub CLI
+        uses: cli/cli-action@v2
+
+      - name: 🔧 Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 20
 
       - name: ✏️ Generate blog post
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           VERSION=${GITHUB_REF#refs/tags/}
+          PREV_TAG=$(git tag --sort=creatordate | grep -B1 "$VERSION" | head -n1)
           DATE=$(date +'%Y-%m-%d')
           FILE="docs-site/blog/${DATE}-release-${VERSION}.md"
 
-          echo "---" > $FILE
-          echo "slug: release-${VERSION}" >> $FILE
-          echo "title: ✨ Version ${VERSION} Released" >> $FILE
-          echo "authors: [ali]" >> $FILE
-          echo "tags: [release, changelog]" >> $FILE
-          echo "---" >> $FILE
-          echo >> $FILE
-          echo "RAG Pipeline Utils v${VERSION} is now available on NPM!" >> $FILE
-          echo >> $FILE
-          echo "#### Highlights" >> $FILE
-          echo "- 🚀 Auto-published blog from GitHub release" >> $FILE
-          echo "- 📦 Version bump: ${VERSION}" >> $FILE
-          echo "- 📘 See CHANGELOG.md for full details" >> $FILE
+          COMPARE_URL="https://github.com/${{ github.repository }}/compare/${PREV_TAG}...${VERSION}"
+          COMMITS=$(gh api repos/${{ github.repository }}/compare/${PREV_TAG}...${VERSION} --jq '.total_commits')
+          CONTRIBUTORS=$(gh api repos/${{ github.repository }}/compare/${PREV_TAG}...${VERSION} --jq '[.commits[].author.login] | unique | join(", ")')
+
+          echo "---" > "$FILE"
+          echo "slug: release-${VERSION}" >> "$FILE"
+          echo "title: \"✨ Version ${VERSION} Released\"" >> "$FILE"
+          echo "authors: [ali]" >> "$FILE"
+          echo "tags: [release, changelog]" >> "$FILE"
+          echo "---" >> "$FILE"
+          echo >> "$FILE"
+          echo "🎉 **RAG Pipeline Utils \`${VERSION}\` is now available!**" >> "$FILE"
+          echo >> "$FILE"
+          echo "## 🔍 Metadata" >> "$FILE"
+          echo "| Key           | Value            |" >> "$FILE"
+          echo "|----------------|------------------|" >> "$FILE"
+          echo "| Version       | \`${VERSION}\`     |" >> "$FILE"
+          echo "| Previous Tag  | \`${PREV_TAG}\`     |" >> "$FILE"
+          echo "| Commit Count  | ${COMMITS:-N/A}   |" >> "$FILE"
+          echo "| Contributors  | ${CONTRIBUTORS:-N/A} |" >> "$FILE"
+          echo "| GitHub Diff   | [${PREV_TAG}...${VERSION}](${COMPARE_URL}) |" >> "$FILE"
+          echo >> "$FILE"
+          echo "## 🚀 Highlights" >> "$FILE"
+          echo "- Auto-published blog post from GitHub Release" >> "$FILE"
+          echo "- GitHub diff for full history: [${COMPARE_URL}](${COMPARE_URL})" >> "$FILE"
+          echo "- Semantic versioning with changelog tracking" >> "$FILE"
+          echo "- See full [CHANGELOG.md](../../CHANGELOG.md)" >> "$FILE"
 
       - name: 📋 Commit blog post
         uses: stefanzweifel/git-auto-commit-action@v5

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [2.1.2](https://github.com/DevilsDev/rag-pipeline-utils/compare/v2.1.1...v2.1.2) (2025-04-21)
+
+
+### Bug Fixes
+
+* resolve build/test errors, update jest configuration, and ensure compatibility with ECMAScript modules ([e6259f9](https://github.com/DevilsDev/rag-pipeline-utils/commit/e6259f924f38da66f9fc9cb7c01a8d6665bf5cbd))
+
 ## [2.1.1](https://github.com/DevilsDev/rag-pipeline-utils/compare/v2.1.0...v2.1.1) (2025-04-18)
 
 

package/codecov.SHA256SUM

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

package/codecov.SHA256SUM.sig

@@ -0,0 +1,16 @@
+-----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/blog/2025-04-18-architecture-overview.md

@@ -1,34 +1,16 @@
 ---
 slug: architecture-overview
-title: RAG Pipeline Architecture Overview
+title: RAG Architecture Overview
 authors: [ali]
-tags: [architecture, design, modular]
-description: A deep dive into the architecture powering RAG Pipeline Utils — from plugin interfaces to flexible pipeline composition.
+tags: [architecture, modular]
 ---
 
-Welcome to the first post in our deep dive blog series on **RAG Pipeline Utils** — a fully modular, testable, and production-grade framework for building retrieval-augmented generation pipelines.
+Explore the modular RAG pipeline architecture. Components like loaders, embedders, retrievers, and generators are pluggable and testable.
 
-## Why Modular RAG?
+<!-- truncate -->
 
-Most RAG tools are tightly coupled or opinionated. We built this utility to empower dev teams with:
+## Key Concepts
 
--  Swappable plugins for loaders, embedders, retrievers, LLMs
--  CLI tools for evaluation & schema validation
--  Docusaurus-based docs with versioned releases
--  Full CI/CD and automated NPM releases
-
-## Architecture Highlights
-
-- `PluginRegistry`: Registers and resolves all components.
-- `validateSchema`: Enforces `.ragrc.json` format across all pipelines.
-- `mocks/`: Local test doubles for every plugin interface.
-- `__tests__/`: Dual-layer coverage — unit + integration.
-
-## Try It Now
-
-```bash
-npm install @devilsdev/rag-pipeline-utils
-npx rag-utils run --config .ragrc.json
-```
-
-Stay tuned for future posts including CI validation, RAG evaluation tooling, and how to build your own dashboard for prompt scoring.
+- 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-17-release-v2.0.2.md → 2025-04-18-release-v2.1.1.md}

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

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

@@ -1,31 +1,16 @@
 ---
-title: "Prompt Engineering Best Practices for RAG"
 slug: prompt-engineering-best-practices
+title: Prompt Engineering Best Practices
 authors: [ali]
-tags: [prompt-engineering, design]
-image: /img/social/prompt-engineering-card.png
-description: "A deep dive into prompt optimization strategies for RAG pipelines using modular design."
+tags: [prompt-engineering, tutorials]
 ---
-Prompt engineering is a critical lever in maximizing the effectiveness of Retrieval-Augmented Generation (RAG) systems. In this article, we explore:
 
-## Prompting in Modular RAG Pipelines
+Design better prompts for your LLM-driven RAG workflows using templating, in-context examples, and task-specific embeddings.
 
-Your `rag-pipeline-utils` system allows swappable LLM backends and encourages prompt templates as part of the reranker or query orchestrator.
+<!-- truncate -->
 
-- Always define clear input/output expectations
-- Leverage JSON or YAML-based structured prompts where applicable
-- Evaluate with real examples using the CLI + evaluation framework
+## Tips
 
-## What to Include in Prompts
-
-- **Context injection**: retrieved chunks, metadata, source provenance
-- **Task framing**: instruction-oriented for LLM consistency
-- **Scoring heuristics**: if doing ranking, consider scoring guidelines
-
-## Prompt as Plugin (Future Feature)
-
-Eventually, we plan to support `promptTemplate` as a plugin type – enabling reusable prompt logic alongside `loader`, `retriever`, etc.
-
----
-
-Stay tuned for our upcoming prompt debugger dashboard, and follow [releases](/blog/tags/release) for versioned updates.
+- Use instructions + context
+- Dynamically inject retrieved passages
+- Validate through CLI or dashboard

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

@@ -1,23 +1,14 @@
 ---
 slug: image-showcase
-title: Blog Image Component Showcase
+title: Image Showcase with LQIP
 authors: [ali]
-tags: [tutorials, design, image]
-description: Demonstrating LQIP-powered blog images using the BlogImage component.
+tags: [image, tutorials]
 ---
 
-import BlogImage from '@site/src/components/BlogImage';
+Demonstration of how low-quality image placeholders (LQIP) improve blog UX and optimize web performance.
 
-This post demonstrates the reusable **`<BlogImage />`** component, which displays optimized blurred placeholders (LQIPs) for faster rendering.
+<!-- truncate -->
 
-## Example
+## Details
 
-<BlogImage srcKey="img_hero" alt="Hero demonstration" />
-
----
-
-## Benefits Recap
-
-- Blurred placeholder loading for faster perception
-- Fallback to default cache when missing
-- Ready for automation via `watch-images.js`
+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

@@ -0,0 +1,21 @@
+<!-- .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/tags.yml

@@ -29,3 +29,32 @@ 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/intro.mdx

@@ -0,0 +1,6 @@
+---
+id: intro
+title: Introduction
+---
+
+Welcome to RAG Pipeline Utils! This is the starting point for your documentation.

package/docs-site/docusaurus.config.js

@@ -1,7 +1,7 @@
 /**
- * Version: 0.3.0
+ * Version: 0.4.0
  * Path: /docs-site/docusaurus.config.js
- * Description: Final production config with cleaned branding and image setup
+ * Description: Tailwind integration, sticky navbar, and dark/light toggle support
  * Author: Ali Kahwaji
  */
 
@@ -9,36 +9,50 @@
 
 export default {
   title: 'RAG Pipeline Utils',
-  tagline: 'Composable RAG pipelines with Node.js',
+  tagline: 'Composable pipelines for LLMs',
   url: 'https://devilsdev.github.io',
   baseUrl: '/rag-pipeline-utils/',
   deploymentBranch: 'gh-pages',
-  onBrokenLinks: 'throw',
+  onBrokenLinks: 'warn',
   onBrokenMarkdownLinks: 'warn',
 
-  // ✅ Final favicon and social card for branding
   favicon: 'img/favicon.ico',
+
   themeConfig: {
-    
-    // algolia: {
-    //   appId: 'YOUR_APP_ID',
-    //   apiKey: 'YOUR_PUBLIC_API_KEY',
-    //   indexName: 'rag_pipeline_utils',
-    //   contextualSearch: true,
-    // },
+    metadata: [
+      { name: 'keywords', content: 'rag, llm, langchain, pipeline, openai, nodejs' },
+      { name: 'author', content: 'Ali Kahwaji' },
+      { name: 'theme-color', content: '#3EF4B6' }
+    ],
+    // ✅ OpenGraph / Twitter image
     image: 'img/social-card.jpg',
+
+    // ✅ Color mode toggle support
+    colorMode: {
+      defaultMode: 'light',
+      disableSwitch: false,
+      respectPrefersColorScheme: true
+    },
+
+    // ✅ Sticky header
     navbar: {
       title: 'RAG Utils',
+      hideOnScroll: false,
       logo: {
-        alt: '', // ✅ Clean alt to avoid raw rendering
+        alt: '',
         src: '/img/logo.svg'
       },
       items: [
         { to: '/docs/Introduction', label: 'Docs', position: 'left' },
         { to: '/blog', label: 'Blog', position: 'left' },
-        { href: 'https://github.com/DevilsDev/rag-pipeline-utils', label: 'GitHub', position: 'right' },
+        {
+          href: 'https://github.com/DevilsDev/rag-pipeline-utils',
+          label: 'GitHub',
+          position: 'right'
+        }
       ]
     },
+
     footer: {
       style: 'dark',
       copyright: `© ${new Date().getFullYear()} Ali Kahwaji`
@@ -54,14 +68,17 @@ export default {
       {
         docs: {
           sidebarPath: require.resolve('./sidebars.js'),
-          editUrl: 'https://github.com/DevilsDev/rag-pipeline-utils/edit/main/docs-site/'
+          editUrl:
+            'https://github.com/DevilsDev/rag-pipeline-utils/edit/main/docs-site/'
         },
-
         blog: {
           showReadingTime: true,
-          editUrl: 'https://github.com/DevilsDev/rag-pipeline-utils/edit/main/docs-site/blog/',
+          blogSidebarTitle: 'All Posts',
+          blogSidebarCount: 'ALL',
+          onUntruncatedBlogPosts: 'ignore',
+          editUrl:
+            'https://github.com/DevilsDev/rag-pipeline-utils/edit/main/docs-site/blog/'
         },
-        
         theme: {
           customCss: require.resolve('./src/css/custom.css')
         }