nodebb-plugin-search-agent 0.0.1

package/lib/similarity.js

@@ -0,0 +1,125 @@
+'use strict';
+
+// Common stop-words (English + Hebrew) to exclude from TF-IDF vectors
+const STOP_WORDS = new Set([
+	// English
+	'a', 'an', 'the', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+	'of', 'with', 'by', 'from', 'is', 'it', 'its', 'be', 'as', 'was',
+	'are', 'were', 'been', 'have', 'has', 'had', 'do', 'does', 'did',
+	'will', 'would', 'could', 'should', 'may', 'might', 'can', 'shall',
+	'not', 'no', 'so', 'if', 'this', 'that', 'these', 'those', 'i', 'we',
+	'you', 'he', 'she', 'they', 'my', 'your', 'his', 'her', 'our', 'their',
+	'how', 'what', 'when', 'where', 'why', 'who', 'which', 'am', 'up',
+	'out', 'about', 'into', 'than', 'more', 'also', 'me', 'him', 'us', 'them',
+	// Hebrew
+	'של', 'את', 'אל', 'על', 'עם', 'הם', 'הן', 'זה', 'זו', 'זאת',
+	'כי', 'לא', 'כן', 'יש', 'אם', 'רק', 'גם', 'אבל', 'אנחנו', 'אני',
+	'אתה', 'את', 'הוא', 'היא', 'אנו', 'אתם', 'אתן', 'הם', 'הן',
+	'זה', 'זו', 'אלה', 'אלו', 'כל', 'כך', 'כבר', 'עוד', 'רק', 'כן',
+	'אחד', 'יותר', 'פה', 'שם', 'מה', 'מי', 'איך', 'מתי', 'איפה',
+	'היה', 'הייתה', 'יהיה', 'תהיה', 'הוא', 'היא', 'הם', 'הן',
+	'אסור', 'מותר', 'צריך', 'רוצה', 'יכול', 'יכולה', 'לו', 'לה',
+	'בו', 'בה', 'עליו', 'עליה', 'בין', 'כבר', 'עכשיו', 'היום',
+	'כן', 'לכן', 'כדי', 'כדאי', 'שלי', 'שלך', 'שלו', 'שלה',
+	'שלנו', 'שלכם', 'שלהם', 'שלהן', 'להם', 'להן', 'לנו', 'לכם',
+]);
+
+/**
+ * Strip HTML, lowercase, remove punctuation, drop stop-words and short tokens.
+ * @param {string|null|undefined} text
+ * @returns {string[]}
+ */
+function tokenize(text) {
+	if (!text) return [];
+	return text
+		.replace(/<[^>]*>/g, ' ')           // strip HTML tags
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}\s]/gu, ' ') // keep all Unicode letters & digits (Hebrew, Latin, etc.)
+		.split(/\s+/)
+		.filter(t => t.length >= 2 && !STOP_WORDS.has(t)); // min 2 chars to keep short Hebrew words
+}
+
+/**
+ * Build a TF-IDF index from an array of topic objects.
+ * Each topic must have: tid, slug, title, mainPostContent (optional).
+ * @param {{ tid: number|string, slug: string, title: string, mainPostContent?: string }[]} topics
+ * @returns {{ tid: number|string, slug: string, vector: Map<string, number> }[]}
+ */
+function buildIndex(topics) {
+	if (!topics || topics.length === 0) return [];
+
+	// Step 1: term frequencies per document
+	const docs = topics.map((t) => {
+		const tokens = tokenize(`${t.title || ''} ${t.mainPostContent || ''}`);
+		const tf = new Map();
+		for (const token of tokens) {
+			tf.set(token, (tf.get(token) || 0) + 1);
+		}
+		return { tid: t.tid, slug: t.slug, tf, len: tokens.length };
+	});
+
+	// Step 2: document frequency (how many docs contain each term)
+	const df = new Map();
+	for (const doc of docs) {
+		for (const term of doc.tf.keys()) {
+			df.set(term, (df.get(term) || 0) + 1);
+		}
+	}
+
+	const N = docs.length;
+
+	// Step 3: compute TF-IDF vector per document
+	return docs.map((doc) => {
+		const vector = new Map();
+		for (const [term, freq] of doc.tf) {
+			const tf = doc.len > 0 ? freq / doc.len : 0;
+			// Smoothed IDF to avoid division by zero
+			const idf = Math.log((N + 1) / (df.get(term) + 1)) + 1;
+			vector.set(term, tf * idf);
+		}
+		return { tid: doc.tid, slug: doc.slug, vector };
+	});
+}
+
+/**
+ * Rank indexed documents against a query using cosine similarity.
+ * @param {string} queryText
+ * @param {{ tid: number|string, slug: string, vector: Map<string, number> }[]} index
+ * @param {number} [topN=10]
+ * @returns {{ tid: number|string, slug: string, score: number }[]}
+ */
+function query(queryText, index, topN = 10) {
+	if (!index || index.length === 0) return [];
+
+	const qTokens = tokenize(queryText);
+	if (qTokens.length === 0) return [];
+
+	// Build raw term-count vector for the query
+	const qVec = new Map();
+	for (const token of qTokens) {
+		qVec.set(token, (qVec.get(token) || 0) + 1);
+	}
+
+	const results = [];
+	for (const doc of index) {
+		let dot = 0;
+		let docNormSq = 0;
+		let qNormSq = 0;
+
+		for (const [term, qVal] of qVec) {
+			dot += qVal * (doc.vector.get(term) || 0);
+		}
+		for (const val of doc.vector.values()) docNormSq += val * val;
+		for (const val of qVec.values()) qNormSq += val * val;
+
+		const norm = Math.sqrt(docNormSq) * Math.sqrt(qNormSq);
+		const score = norm > 0 ? dot / norm : 0;
+		if (score > 0) {
+			results.push({ tid: doc.tid, slug: doc.slug, score });
+		}
+	}
+
+	return results.sort((a, b) => b.score - a.score).slice(0, topN);
+}
+
+module.exports = { tokenize, buildIndex, query };

package/library.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const winston = require.main.require('winston');
+
+const controllers = require('./lib/controllers');
+const { invalidateCache } = require('./lib/searchHandler');
+
+const routeHelpers = require.main.require('./src/routes/helpers');
+
+const plugin = {};
+
+/**
+ * static:app.load
+ * Register admin page route and set up cache-invalidation on new topic creation.
+ */
+plugin.init = async (params) => {
+	console.log('[search-agent] plugin.init called');
+	const { router } = params;
+
+	// Admin settings page
+	routeHelpers.setupAdminPageRoute(
+		router,
+		'/admin/plugins/search-agent',
+		controllers.renderAdminPage
+	);
+
+	console.log('[search-agent] Admin route registered: /admin/plugins/search-agent');
+	winston.info('[plugins/search-agent] Initialised.');
+};
+
+/**
+ * static:api.routes
+ * Register the REST endpoint consumed by the floating chat widget.
+ *
+ * POST /api/v3/plugins/search-agent/query
+ * Body:  { "query": "how do I reset my password?" }
+ * Returns a ranked list of matching forum topics.
+ *
+ * Authentication: open to all logged-in users (uses ensureLoggedIn).
+ * To allow guests as well, remove the middleware array below.
+ */
+plugin.addRoutes = async ({ router, middleware, helpers }) => {
+	console.log('[search-agent] plugin.addRoutes called — registering API routes');
+	const middlewares = [
+		middleware.ensureLoggedIn,
+	];
+
+	routeHelpers.setupApiRoute(
+		router,
+		'post',
+		'/search-agent/query',
+		middlewares,
+		(req, res) => controllers.handleQuery(req, res, helpers)
+	);
+	console.log('[search-agent] API route registered: POST /api/v3/plugins/search-agent/query');
+
+	// Public config endpoint — no auth required so guests can read the visibility setting
+	routeHelpers.setupApiRoute(
+		router,
+		'get',
+		'/search-agent/config',
+		[],
+		(req, res) => controllers.getConfig(req, res, helpers)
+	);
+	console.log('[search-agent] API route registered: GET /api/v3/plugins/search-agent/config');
+
+	// Lightweight cache-bust endpoint (admin only)
+	routeHelpers.setupApiRoute(
+		router,
+		'post',
+		'/search-agent/cache/invalidate',
+		[middleware.ensureLoggedIn, middleware.admin.checkPrivileges],
+		(req, res) => {
+			console.log('[search-agent] Cache invalidation requested by uid:', req.uid);
+			invalidateCache();
+			helpers.formatApiResponse(200, res, { message: 'Cache invalidated.' });
+		}
+	);
+	console.log('[search-agent] API route registered: POST /api/v3/plugins/search-agent/cache/invalidate');
+};
+
+/**
+ * filter:admin.header.build
+ * Add the plugin entry to the ACP sidebar.
+ */
+plugin.addAdminNavigation = (header) => {
+	console.log('[search-agent] plugin.addAdminNavigation called — adding ACP sidebar entry');
+	header.plugins.push({
+		route: '/plugins/search-agent',
+		icon: 'fa-comments',
+		name: 'Search Agent',
+	});
+
+	return header;
+};
+
+module.exports = plugin;
+

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "nodebb-plugin-search-agent",
+  "version": "0.0.1",
+  "description": "NodeBB plugin that adds a floating chat assistant to help users find relevant forum topics using TF-IDF text similarity",
+  "main": "library.js",
+  "author": "Racheli Bayfus",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/racheliK9201/nodebb-plugin-search-agent.git"
+  },
+  "scripts": {
+    "lint": "eslint ."
+  },
+  "keywords": [
+    "nodebb",
+    "plugin",
+    "search",
+    "chat",
+    "assistant",
+    "tfidf",
+    "similarity"
+  ],
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged",
+      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+    }
+  },
+  "lint-staged": {
+    "*.js": [
+      "eslint --fix",
+      "git add"
+    ]
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/nodebb/nodebb-plugin-search-agent/issues"
+  },
+  "readmeFilename": "README.md",
+  "nbbpm": {
+    "compatibility": "^3.2.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "20.5.0",
+    "@commitlint/config-angular": "20.5.0",
+    "eslint": "10.0.3",
+    "eslint-config-nodebb": "2.0.1",
+    "husky": "9.1.7",
+    "lint-staged": "16.4.0"
+  }
+}

package/plugin.json

@@ -0,0 +1,29 @@
+{
+	"id": "nodebb-plugin-search-agent",
+	"name": "Search Agent",
+	"description": "Floating chat assistant that finds relevant forum topics using TF-IDF similarity",
+	"url": "https://github.com/NodeBB/nodebb-plugin-search-agent",
+	"library": "./library.js",
+	"hooks": [
+		{ "hook": "static:app.load", "method": "init" },
+		{ "hook": "static:api.routes", "method": "addRoutes" },
+		{ "hook": "filter:admin.header.build", "method": "addAdminNavigation" }
+	],
+	"staticDirs": {
+		"static": "./static"
+	},
+	"scss": [
+		"scss/search-agent.scss"
+	],
+	"scripts": [
+		"public/lib/main.js"
+	],
+	"acpScripts": [
+		"public/lib/acp-main.js"
+	],
+	"modules": {
+		"../admin/plugins/search-agent.js": "./public/lib/admin.js"
+	},
+	"templates": "templates",
+	"languages": "languages"
+}

package/plugins/quickstart/partials/sorted-list/form.tpl

@@ -0,0 +1,10 @@
+<form>
+    <div class="mb-3">
+        <label class="form-label" for="name">Name</label>
+        <input type="text" id="name" name="name" class="form-control" placeholder="Name" />
+    </div>
+    <div class="mb-3">
+        <label class="form-label" for="description">Description</label>
+        <input type="text" id="description" name="description" class="form-control" placeholder="Description" />
+    </div>
+</form>

package/plugins/quickstart/partials/sorted-list/item.tpl

@@ -0,0 +1,12 @@
+<li data-type="item" class="list-group-item">
+    <div class="d-flex gap-2 justify-content-between align-items-start">
+        <div class="flex-grow-1">
+            <strong>{name}</strong><br />
+            <small>{description}</small>
+        </div>
+        <div class="d-flex gap-1 flex-nowrap">
+            <button type="button" data-type="edit" class="btn btn-sm btn-info">Edit</button>
+            <button type="button" data-type="remove" class="btn btn-sm btn-danger">Delete</button>
+        </div>
+    </div>
+</li>

package/plugins/search-agent.tpl

@@ -0,0 +1,93 @@
+<div class="acp-page-container">
+	<!-- IMPORT admin/partials/settings/header.tpl -->
+
+	<div class="row m-0">
+		<div id="spy-container" class="col-12 col-md-8 px-0 mb-4" tabindex="0">
+			<form role="form" class="search-agent-settings">
+
+				<!-- ── General ─────────────────────────────────────────────── -->
+				<div class="mb-4">
+					<h5 class="fw-bold tracking-tight settings-header">General</h5>
+					<p class="lead">
+						Configure the Search Agent plugin behaviour.
+						Settings are persisted via <code>meta.settings.get('search-agent')</code>.
+					</p>
+
+					<div class="mb-3">
+						<label class="form-label" for="topicLimit">
+							Topics indexed (max topics fetched for similarity search)
+						</label>
+						<input
+							type="number"
+							min="50"
+							max="5000"
+							id="topicLimit"
+							name="topicLimit"
+							class="form-control"
+							placeholder="500"
+							value="500"
+						/>
+						<div class="form-text">
+							Higher values improve recall but increase memory usage.
+							The index is rebuilt every 5 minutes.
+						</div>
+					</div>
+
+					<div class="mb-3">
+						<label class="form-label" for="maxResults">
+							Max results returned per query
+						</label>
+						<input
+							type="number"
+							min="1"
+							max="20"
+							id="maxResults"
+							name="maxResults"
+							class="form-control"
+							placeholder="10"
+							value="10"
+						/>
+					</div>
+
+					<div class="form-check form-switch mb-3">
+						<input type="checkbox" class="form-check-input" id="guestsAllowed" name="guestsAllowed">
+						<label for="guestsAllowed" class="form-check-label">
+							Allow guests (non-logged-in users) to use the chat widget
+						</label>
+					</div>
+				</div>
+
+				<!-- ── Appearance ──────────────────────────────────────────── -->
+				<div class="mb-4">
+					<h5 class="fw-bold tracking-tight settings-header">Appearance</h5>
+
+					<div class="mb-3 d-flex gap-2 align-items-center">
+						<label class="form-label mb-0" for="primaryColor">Primary colour</label>
+						<input
+							data-settings="colorpicker"
+							type="color"
+							id="primaryColor"
+							name="primaryColor"
+							class="form-control p-1"
+							value="#0f7ee8"
+							style="width:64px;"
+						/>
+					</div>
+				</div>
+
+			</form>
+		</div>
+
+		<!-- ── Sticky save / table of contents ─────────────────────────────── -->
+		<div class="col-12 col-md-4 px-0 mb-4 acp-sidebar">
+			<div class="card sticky-top">
+				<div class="card-header">Save Changes</div>
+				<div class="card-body">
+					<button class="btn btn-primary btn-sm fw-semibold" data-action="save">
+						Save Settings
+					</button>
+				</div>
+			</div>
+		</div>
+	</div>
+</div>

package/public/lib/acp-main.js

@@ -0,0 +1,38 @@
+'use strict';
+
+$(document).ready(function () {
+	/*
+	 * Admin CP frontend for nodebb-plugin-search-agent.
+	 * Handles saving settings via NodeBB's standard ACP settings API.
+	 */
+	console.log('[search-agent] acp-main.js: DOM ready');
+
+	$(window).on('action:ajaxify.end', function (ev, data) {
+		console.log('[search-agent] acp-main.js: ajaxify.end — url:', data.url);
+		if (data.url === 'admin/plugins/search-agent') {
+			console.log('[search-agent] acp-main.js: search-agent admin page detected — running setupAdminPage()');
+			setupAdminPage();
+		}
+	});
+
+	function setupAdminPage() {
+		console.log('[search-agent] setupAdminPage: binding save button and loading current settings');
+		// NodeBB's settings module is auto-loaded for the ACP.
+		// The [data-action="save"] button triggers NodeBB's built-in settings save.
+		$('[data-action="save"]').on('click', function () {
+			console.log('[search-agent] setupAdminPage: save button clicked');
+			require(['settings'], function (Settings) {
+				Settings.save('search-agent', $('form.search-agent-settings'), function () {
+					console.log('[search-agent] setupAdminPage: settings saved successfully');
+					app.alertSuccess('Settings saved!');
+				});
+			});
+		});
+
+		require(['settings'], function (Settings) {
+			console.log('[search-agent] setupAdminPage: loading settings into form');
+			Settings.load('search-agent', $('form.search-agent-settings'));
+		});
+	}
+});
+

package/public/lib/admin.js

@@ -0,0 +1,26 @@
+'use strict';
+
+/*
+	This module is loaded when the user navigates to /admin/plugins/search-agent.
+	It handles loading and saving plugin settings via NodeBB's settings module.
+*/
+
+import { save, load } from 'settings';
+
+export function init() {
+	console.log('[search-agent] admin.js: init() called');
+	handleSettingsForm();
+}
+
+function handleSettingsForm() {
+	console.log('[search-agent] admin.js: handleSettingsForm() — loading settings into form');
+	// Load current settings into the form fields
+	load('search-agent', $('.search-agent-settings'));
+
+	// Save settings when the button is clicked
+	$('[data-action="save"]').on('click', () => {
+		console.log('[search-agent] admin.js: save button clicked — persisting settings');
+		save('search-agent', $('.search-agent-settings'));
+	});
+}
+