nodebb-plugin-search-agent 0.0.1

package/templates/admin/plugins/search-agent.tpl

@@ -0,0 +1,186 @@
+<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>
+
+				<!-- ── AI (OpenAI) ─────────────────────────────────────────── -->
+				<div class="mb-4">
+					<h5 class="fw-bold tracking-tight settings-header">AI-Powered Re-ranking (OpenAI)</h5>
+					<p class="lead">
+						When enabled, TF-IDF finds candidate topics and OpenAI selects the most
+						relevant ones for a smarter, semantically-aware response.
+						Leave the API key blank to use TF-IDF ranking only.
+					</p>
+
+					<div class="form-check form-switch mb-3">
+						<input type="checkbox" class="form-check-input" id="aiEnabled" name="aiEnabled">
+						<label for="aiEnabled" class="form-check-label">
+							Enable AI re-ranking
+						</label>
+					</div>
+
+					<div class="mb-3">
+						<label class="form-label" for="openaiApiKey">OpenAI API Key</label>
+						<input
+							type="password"
+							id="openaiApiKey"
+							name="openaiApiKey"
+							class="form-control"
+							placeholder="sk-…"
+							autocomplete="new-password"
+						/>
+						<div class="form-text">
+							Your secret key from
+							<a href="https://platform.openai.com/api-keys" target="_blank" rel="noopener noreferrer">
+								platform.openai.com/api-keys
+							</a>.
+							Stored server-side only; never sent to the client.
+						</div>
+					</div>
+
+					<div class="mb-3">
+						<label class="form-label" for="openaiModel">OpenAI Model</label>
+						<input
+							type="text"
+							id="openaiModel"
+							name="openaiModel"
+							class="form-control"
+							placeholder="gpt-4o-mini"
+							value="gpt-4o-mini"
+						/>
+						<div class="form-text">
+							Recommended: <code>gpt-4o-mini</code> (fast and inexpensive).
+							Use <code>gpt-4o</code> for higher accuracy.
+						</div>
+					</div>
+
+					<div class="mb-3">
+						<label class="form-label" for="aiCandidates">
+							TF-IDF candidates sent to AI
+						</label>
+						<input
+							type="number"
+							min="5"
+							max="30"
+							id="aiCandidates"
+							name="aiCandidates"
+							class="form-control"
+							placeholder="20"
+							value="20"
+						/>
+						<div class="form-text">
+							Number of TF-IDF results passed to the AI for final selection.
+							Higher = more context for the AI, but slightly more tokens used.
+						</div>
+					</div>
+				</div>
+
+				<!-- ── Visibility ─────────────────────────────────────────── -->
+				<div class="mb-4">
+					<h5 class="fw-bold tracking-tight settings-header">Visibility</h5>
+					<p class="lead">
+						Control which users can see and interact with the Search Agent widget.
+					</p>
+
+					<div class="mb-3">
+						<label class="form-label" for="visibleTo">Show widget to</label>
+						<select id="visibleTo" name="visibleTo" class="form-select">
+							<option value="all">All logged-in users</option>
+							<option value="admins">Administrators only</option>
+						</select>
+						<div class="form-text">
+							When set to "Administrators only", the widget will only be shown to
+							users with administrator privileges. Non-admin requests to the API
+							will also be rejected.
+						</div>
+					</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/test/.eslintrc

@@ -0,0 +1,9 @@
+{
+	"env": {
+		"mocha": true
+	},
+	"rules": {
+		"no-unused-vars": "off"
+	}
+}
+

package/test/index.js

@@ -0,0 +1,128 @@
+/**
+ * Run these tests from the NodeBB root:
+ *   npx mocha test/plugins-installed.js
+ *
+ * Or run just the similarity unit tests (no NodeBB runtime needed):
+ *   npx mocha node_modules/nodebb-plugin-search-agent/test/index.js
+ *
+ * To include integration tests that exercise routes / hooks, add the plugin
+ * to config.json:
+ *   { "test_plugins": ["nodebb-plugin-search-agent"] }
+ */
+
+'use strict';
+
+/* globals describe, it, before */
+
+const assert = require('assert');
+const path = require('path');
+
+// The similarity module has no NodeBB dependencies – safe to require directly.
+const { tokenize, buildIndex, query } = require(path.join(__dirname, '../lib/similarity'));
+
+// ─── Unit: tokeniser ─────────────────────────────────────────────────────────
+
+describe('similarity.tokenize', () => {
+	it('lowercases input', () => {
+		assert.deepStrictEqual(tokenize('Hello World'), ['hello', 'world']);
+	});
+
+	it('strips HTML tags', () => {
+		const tokens = tokenize('<p>Some <b>bold</b> text</p>');
+		assert.ok(tokens.includes('some'));
+		assert.ok(tokens.includes('bold'));
+		assert.ok(tokens.includes('text'));
+	});
+
+	it('removes stop-words', () => {
+		const tokens = tokenize('how do I reset my password');
+		assert.ok(!tokens.includes('how'));
+		assert.ok(!tokens.includes('do'));
+		assert.ok(!tokens.includes('my'));
+		assert.ok(tokens.includes('reset'));
+		assert.ok(tokens.includes('password'));
+	});
+
+	it('drops tokens shorter than 3 characters', () => {
+		assert.deepStrictEqual(tokenize('a ab abc abcd'), ['abc', 'abcd']);
+	});
+
+	it('returns empty array for empty string', () => {
+		assert.deepStrictEqual(tokenize(''), []);
+	});
+
+	it('returns empty array for null/undefined', () => {
+		assert.deepStrictEqual(tokenize(null), []);
+		assert.deepStrictEqual(tokenize(undefined), []);
+	});
+});
+
+// ─── Unit: index building ────────────────────────────────────────────────────
+
+describe('similarity.buildIndex', () => {
+	it('returns empty array for empty input', () => {
+		assert.deepStrictEqual(buildIndex([]), []);
+	});
+
+	it('builds an entry per topic', () => {
+		const topics = [
+			{ tid: 1, title: 'Password reset guide', slug: '1/password-reset', mainPostContent: 'How to reset your password.' },
+			{ tid: 2, title: 'Account settings',     slug: '2/account-settings', mainPostContent: 'Manage your account.' },
+		];
+		const index = buildIndex(topics);
+		assert.strictEqual(index.length, 2);
+		assert.ok(index[0].vector instanceof Map);
+		assert.ok(index[0].vector.size > 0);
+	});
+
+	it('preserves tid and slug', () => {
+		const topics = [{ tid: 42, title: 'Test topic', slug: '42/test-topic', mainPostContent: '' }];
+		const [entry] = buildIndex(topics);
+		assert.strictEqual(entry.tid, 42);
+		assert.strictEqual(entry.slug, '42/test-topic');
+	});
+});
+
+// ─── Unit: query ranking ──────────────────────────────────────────────────────
+
+describe('similarity.query', () => {
+	const topics = [
+		{ tid: 1, title: 'Password reset guide',      slug: '1/password-reset',      mainPostContent: 'Steps to reset a forgotten password.' },
+		{ tid: 2, title: 'How to change email',       slug: '2/change-email',         mainPostContent: 'Update your account email address.' },
+		{ tid: 3, title: 'NodeBB installation guide', slug: '3/nodebb-installation',  mainPostContent: 'Install NodeBB on Ubuntu server.' },
+	];
+	const index = buildIndex(topics);
+
+	it('returns an array', () => {
+		const results = query('password reset', index);
+		assert.ok(Array.isArray(results));
+	});
+
+	it('returns the most relevant topic first', () => {
+		const results = query('password reset forgotten', index);
+		assert.ok(results.length > 0);
+		assert.strictEqual(results[0].tid, 1, 'Password reset topic should rank first');
+	});
+
+	it('returns empty array for blank query', () => {
+		assert.deepStrictEqual(query('', index), []);
+		assert.deepStrictEqual(query('   ', index), []);
+	});
+
+	it('returns empty array when index is empty', () => {
+		assert.deepStrictEqual(query('anything', []), []);
+	});
+
+	it('respects topN limit', () => {
+		const all = query('guide', index, 1);
+		assert.ok(all.length <= 1);
+	});
+
+	it('scores are between 0 and 1', () => {
+		const results = query('installation guide', index, 10);
+		for (const r of results) {
+			assert.ok(r.score >= 0 && r.score <= 1, `score ${r.score} out of range`);
+		}
+	});
+});
+