Merge pull request #1787 from rocket-admin/backend_docs_search_ai_tool

feat: add searchDocumentation tool for querying Rocketadmin documentation and update prompts for AI responses

Author: Artuomka

backend/src/ai-core/tools/database-tools.ts

@@ -53,6 +53,23 @@ export function createDatabaseTools(isMongoDB: boolean): AIToolDefinition[] {
 		},
 	};
 
+	const searchDocumentationTool: AIToolDefinition = {
+		name: 'searchDocumentation',
+		description:
+			'Searches the official Rocketadmin documentation at https://docs.rocketadmin.com and returns the most relevant pages with their titles, URLs, and content snippets. Use this when the user asks how to use Rocketadmin features (connections, dashboards, permissions, groups, master password, widgets, integrations, settings, SSO, secrets, etc.) or when a question is about the product rather than the data in the connected database.',
+		parameters: {
+			type: 'object',
+			properties: {
+				query: {
+					type: 'string',
+					description: 'A short search query describing what to look up in the Rocketadmin documentation.',
+				},
+			},
+			required: ['query'],
+			additionalProperties: false,
+		},
+	};
+
 	const tools: AIToolDefinition[] = [getTableStructureTool];
 
 	if (isMongoDB) {
@@ -61,6 +78,8 @@ export function createDatabaseTools(isMongoDB: boolean): AIToolDefinition[] {
 		tools.push(executeRawSqlTool);
 	}
 
+	tools.push(searchDocumentationTool);
+
 	return tools;
 }
 

backend/src/ai-core/tools/documentation-search.ts

@@ -0,0 +1,98 @@
+import axios from 'axios';
+
+const ALGOLIA_APP_ID = '31P3X3M1EE';
+const ALGOLIA_SEARCH_API_KEY = 'fe7422b190b4ec77f8e60c80a3a3ed8a';
+const ALGOLIA_INDEX_NAME = 'rocketadmin-docs';
+const ALGOLIA_SEARCH_URL = `https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes/${ALGOLIA_INDEX_NAME}/query`;
+
+const DEFAULT_HITS_PER_PAGE = 5;
+const MAX_HITS_PER_PAGE = 10;
+const MAX_CONTENT_LENGTH = 800;
+const REQUEST_TIMEOUT_MS = 10000;
+
+export interface DocumentationSearchHit {
+	title: string;
+	url: string;
+	content: string;
+}
+
+interface AlgoliaHierarchy {
+	lvl0?: string | null;
+	lvl1?: string | null;
+	lvl2?: string | null;
+	lvl3?: string | null;
+	lvl4?: string | null;
+	lvl5?: string | null;
+	lvl6?: string | null;
+}
+
+interface AlgoliaHit {
+	url?: string;
+	content?: string | null;
+	hierarchy?: AlgoliaHierarchy;
+	type?: string;
+}
+
+interface AlgoliaSearchResponse {
+	hits: AlgoliaHit[];
+}
+
+export async function searchDocumentation(query: string, hitsPerPage?: number): Promise<DocumentationSearchHit[]> {
+	const trimmedQuery = query?.trim();
+	if (!trimmedQuery) {
+		return [];
+	}
+
+	const limit = Math.min(Math.max(hitsPerPage ?? DEFAULT_HITS_PER_PAGE, 1), MAX_HITS_PER_PAGE);
+
+	const response = await axios.post<AlgoliaSearchResponse>(
+		ALGOLIA_SEARCH_URL,
+		{
+			query: trimmedQuery,
+			hitsPerPage: limit,
+			attributesToRetrieve: ['hierarchy', 'content', 'url', 'type'],
+			attributesToSnippet: ['content:50'],
+		},
+		{
+			headers: {
+				'X-Algolia-Application-Id': ALGOLIA_APP_ID,
+				'X-Algolia-API-Key': ALGOLIA_SEARCH_API_KEY,
+				'Content-Type': 'application/json',
+			},
+			timeout: REQUEST_TIMEOUT_MS,
+		},
+	);
+
+	const hits = response.data?.hits ?? [];
+	return hits.map(buildHit).filter((hit) => hit.url && (hit.title || hit.content));
+}
+
+function buildHit(hit: AlgoliaHit): DocumentationSearchHit {
+	const title = formatHierarchy(hit.hierarchy);
+	const rawContent = (hit.content ?? '').replace(/\s+/g, ' ').trim();
+	const content = rawContent.length > MAX_CONTENT_LENGTH ? `${rawContent.slice(0, MAX_CONTENT_LENGTH)}…` : rawContent;
+	return {
+		title,
+		url: hit.url ?? '',
+		content,
+	};
+}
+
+function formatHierarchy(hierarchy: AlgoliaHierarchy | undefined): string {
+	if (!hierarchy) {
+		return '';
+	}
+	const parts = [
+		hierarchy.lvl0,
+		hierarchy.lvl1,
+		hierarchy.lvl2,
+		hierarchy.lvl3,
+		hierarchy.lvl4,
+		hierarchy.lvl5,
+		hierarchy.lvl6,
+	]
+		.filter((part): part is string => Boolean(part))
+		.map((part) => part.replace(/​|‌|‍/g, '').trim())
+		.filter(Boolean);
+	return parts.join(' › ');
+}

backend/src/ai-core/tools/prompts.ts

@@ -16,7 +16,7 @@ Current date and time: ${currentDatetime}
 
 Tool responses are encoded in TOON (Token-Oriented Object Notation) format - a compact, human-readable format similar to YAML with CSV-style tabular arrays. Parse it naturally.
 
-Please follow these steps EXACTLY:
+Please follow these steps EXACTLY when answering data questions:
 1. First, always use the getTableStructure tool to analyze the table schema and understand available columns
 2. If the question requires data from related tables, note their relationships
 3. Generate an appropriate query that answers the user's question precisely
@@ -25,8 +25,13 @@ Please follow these steps EXACTLY:
 6. After receiving query results, explain them to the user in a clear, conversational way
 7. Include explanations of your approach when helpful
 
+When the user asks how to use Rocketadmin itself (features, configuration, connections, dashboards, permissions, groups, master password, widgets, integrations, SSO, secrets, settings, API, etc.) rather than asking about the data in their database:
+- Call the searchDocumentation tool with a concise query that captures the user's question
+- Base your answer on the returned snippets and cite the relevant documentation URLs in your response
+- You may combine searchDocumentation with the data tools when a question needs both product knowledge and data from the database
+
 IMPORTANT:
-- You MUST execute your generated queries using the appropriate tool - this is required for every question
+- You MUST execute your generated queries using the appropriate tool - this is required for every data question
 - After generating a SQL query, immediately call executeRawSql with that query
 - For MongoDB databases, call executeAggregationPipeline with the aggregation pipeline
 - The user cannot see the query results until you execute it with the appropriate tool

backend/src/entities/ai/use-cases/request-info-from-table-with-ai-v7.use.case.ts

@@ -10,6 +10,7 @@ import { AIToolCall, AIToolDefinition } from '../../../ai-core/interfaces/ai-pro
 import { AIProviderType } from '../../../ai-core/interfaces/ai-service.interface.js';
 import { AICoreService } from '../../../ai-core/services/ai-core.service.js';
 import { createDatabaseTools } from '../../../ai-core/tools/database-tools.js';
+import { searchDocumentation } from '../../../ai-core/tools/documentation-search.js';
 import { createDatabaseQuerySystemPrompt } from '../../../ai-core/tools/prompts.js';
 import { isValidMongoDbCommand, isValidSQLQuery, wrapQueryWithLimit } from '../../../ai-core/tools/query-validators.js';
 import { MessageBuilder } from '../../../ai-core/utils/message-builder.js';
@@ -275,6 +276,16 @@ export class RequestInfoFromTableWithAIUseCaseV7
 						break;
 					}
 
+					case 'searchDocumentation': {
+						const query = toolCall.arguments.query as string;
+						if (!query) {
+							throw new Error('Missing required function argument "query"');
+						}
+						const docsResults = await searchDocumentation(query);
+						result = encodeToToon({ query, results: docsResults });
+						break;
+					}
+
 					default:
 						result = encodeError({ error: `Unknown tool: ${toolCall.name}` });
 				}