Add knowledgebases

Knowledgebases give bots RAG over documents, scoped like extensions: to particular bots, to a workspace, or to every bot, with their own button beside Tools in the composer. Documents are chunked and embedded by the file-ingest worker with the install's embedding model, which is now an install-wide setting rather than a per-bot one. - Word search runs on an FTS5 index ranked by BM25, with a scored LIKE fallback for scripts written without spaces. - Changing the embedding model re-indexes documents automatically. - Ingest jobs wait without spending attempts while every embedding model rests, fail at once on errors retrying can't fix, and keep passages searchable by words when the model refuses. - Settings > Knowledgebases shows each knowledgebase's and document's index state: spinner, warning, grey check (words only) or green check. Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-26 16:41:01 +01:00
parent 2259b6895f
commit e7b23b7454
111 changed files with 4573 additions and 148 deletions
@@ -1,3 +1,5 @@
+import grabInstallEmbeddingModel from "@/src/functions/backend/db/knowledgebases/grab-install-embedding-model";
+import reindexAfterEmbeddingChange from "@/src/functions/backend/db/knowledgebases/reindex-after-embedding-change";
 import grabSuperAdminUser from "@/src/functions/backend/backups/grab-super-admin-user";
 import deleteHarnessProvider from "@/src/functions/backend/db/harness/delete-harness-provider";
 import grabHarnessOverview from "@/src/functions/backend/db/harness/grab-harness-overview";
@@ -35,7 +37,10 @@ export const handler: BunextAPIRouteHandler<
            data: body,
        });

+        const embedding_before = await grabInstallEmbeddingModel();
+
        await deleteHarnessProvider({ provider_id });
+        await reindexAfterEmbeddingChange({ before: embedding_before });

        await logEvent({
            title: "Model provider removed",
@@ -1,3 +1,5 @@
+import grabInstallEmbeddingModel from "@/src/functions/backend/db/knowledgebases/grab-install-embedding-model";
+import reindexAfterEmbeddingChange from "@/src/functions/backend/db/knowledgebases/reindex-after-embedding-change";
 import grabSuperAdminUser from "@/src/functions/backend/backups/grab-super-admin-user";
 import grabHarnessOverview from "@/src/functions/backend/db/harness/grab-harness-overview";
 import saveHarnessProvider from "@/src/functions/backend/db/harness/save-harness-provider";
@@ -36,6 +38,7 @@ export const handler: BunextAPIRouteHandler<
            data: body,
        });

+        const embedding_before = await grabInstallEmbeddingModel();
        const provider = await saveHarnessProvider(request);

        await logEvent({
@@ -63,6 +66,12 @@ export const handler: BunextAPIRouteHandler<
            }
        }

+        const reindexing = await reindexAfterEmbeddingChange({ before: embedding_before });
+
+        if (reindexing) {
+            msg = `${msg} Reading ${reindexing} knowledgebase ${reindexing == 1 ? "document" : "documents"} again with the new embedding model.`;
+        }
+
        return {
            success: true,
            msg,
@@ -1,3 +1,5 @@
+import grabInstallEmbeddingModel from "@/src/functions/backend/db/knowledgebases/grab-install-embedding-model";
+import reindexAfterEmbeddingChange from "@/src/functions/backend/db/knowledgebases/reindex-after-embedding-change";
 import grabSuperAdminUser from "@/src/functions/backend/backups/grab-super-admin-user";
 import grabHarnessOverview from "@/src/functions/backend/db/harness/grab-harness-overview";
 import grabHarnessSetting from "@/src/functions/backend/db/harness/grab-harness-setting";
@@ -36,6 +38,8 @@ export const handler: BunextAPIRouteHandler<
            data: body,
        });

+        const embedding_before = await grabInstallEmbeddingModel();
+
        for (const setting of settings) {
            const existing = await grabHarnessSetting({ harness: setting.harness });
            const { voice, ...options } = existing.options;
@@ -65,9 +69,13 @@ export const handler: BunextAPIRouteHandler<
            ip_address: grabRequestIP(req),
        });

+        const reindexing = await reindexAfterEmbeddingChange({ before: embedding_before });
+
        return {
            success: true,
-            msg: `Saved.`,
+            msg: reindexing
+                ? `Saved. Reading ${reindexing} knowledgebase ${reindexing == 1 ? "document" : "documents"} again with the new embedding model.`
+                : `Saved.`,
            singleRes: await grabHarnessOverview(),
        };
    } catch (error: unknown) {
@@ -0,0 +1,57 @@
+import grabSuperAdminUser from "@/src/functions/backend/backups/grab-super-admin-user";
+import deleteKnowledgebaseDocument from "@/src/functions/backend/db/knowledgebases/delete-knowledgebase-document";
+import listKnowledgebaseDocuments from "@/src/functions/backend/db/knowledgebases/list-knowledgebase-documents";
+import { touchKnowledgebase } from "@/src/functions/backend/db/knowledgebases/record-knowledgebase-document";
+import logEvent, { grabRequestIP } from "@/src/functions/backend/logger";
+import { KnowledgebaseDocumentIdRequestSchema } from "@/src/schemas/knowledgebase-schema";
+import type { KnowledgebaseDocumentsPayload } from "@/src/types";
+import AppError from "@/src/utils/app-error";
+import parseWithSchema from "@/src/utils/parse-with-schema";
+import safeErrorMessage from "@/src/utils/safe-error-message";
+import type {
+    APIResponseObject,
+    BunextAPIRouteHandler,
+} from "@moduletrace/bunext/types";
+
+/**
+ * Super admin only: deletes one document from a knowledgebase. Bots stop
+ * finding it at once.
+ */
+export const handler: BunextAPIRouteHandler<
+    APIResponseObject<KnowledgebaseDocumentsPayload>
+> = async ({ req, body }) => {
+    try {
+        if (req.method != "POST") {
+            throw new AppError(`Method not allowed`);
+        }
+
+        const user = await grabSuperAdminUser({ req });
+
+        if (!user?.id) {
+            throw new AppError(`Only a super admin can do that.`);
+        }
+
+        const { document_id } = parseWithSchema({ schema: KnowledgebaseDocumentIdRequestSchema, data: body });
+        const document = await deleteKnowledgebaseDocument({ document_id });
+        const knowledgebase_id = Number(document.knowledgebase_id);
+
+        await touchKnowledgebase({ knowledgebase_id });
+
+        await logEvent({
+            title: "Knowledgebase document deleted",
+            category: "system",
+            user_id: user.id,
+            plain_text: `User #${user.id} deleted ${document.name} (#${document.id}) from the knowledgebase #${knowledgebase_id}.`,
+            metadata: { knowledgebase_id, document_id },
+            ip_address: grabRequestIP(req),
+        });
+
+        return {
+            success: true,
+            msg: `Deleted ${document.name}.`,
+            singleRes: await listKnowledgebaseDocuments({ knowledgebase_id }),
+        };
+    } catch (error: unknown) {
+        return { success: false, msg: safeErrorMessage({ error }) };
+    }
+};
@@ -0,0 +1,53 @@
+import grabSuperAdminUser from "@/src/functions/backend/backups/grab-super-admin-user";
+import deleteKnowledgebase from "@/src/functions/backend/db/knowledgebases/delete-knowledgebase";
+import grabKnowledgebasesOverview from "@/src/functions/backend/db/knowledgebases/grab-knowledgebases-overview";
+import logEvent, { grabRequestIP } from "@/src/functions/backend/logger";
+import { KnowledgebaseIdRequestSchema } from "@/src/schemas/knowledgebase-schema";
+import type { KnowledgebasesOverviewPayload } from "@/src/types";
+import AppError from "@/src/utils/app-error";
+import parseWithSchema from "@/src/utils/parse-with-schema";
+import safeErrorMessage from "@/src/utils/safe-error-message";
+import type {
+    APIResponseObject,
+    BunextAPIRouteHandler,
+} from "@moduletrace/bunext/types";
+
+/**
+ * Super admin only: deletes a knowledgebase and every document in it.
+ * Bots lose it at once.
+ */
+export const handler: BunextAPIRouteHandler<
+    APIResponseObject<KnowledgebasesOverviewPayload>
+> = async ({ req, body }) => {
+    try {
+        if (req.method != "POST") {
+            throw new AppError(`Method not allowed`);
+        }
+
+        const user = await grabSuperAdminUser({ req });
+
+        if (!user?.id) {
+            throw new AppError(`Only a super admin can do that.`);
+        }
+
+        const { knowledgebase_id } = parseWithSchema({ schema: KnowledgebaseIdRequestSchema, data: body });
+        const knowledgebase = await deleteKnowledgebase({ knowledgebase_id });
+
+        await logEvent({
+            title: "Knowledgebase deleted",
+            category: "system",
+            user_id: user.id,
+            plain_text: `User #${user.id} deleted the knowledgebase ${knowledgebase.name} (#${knowledgebase.id}).`,
+            metadata: { knowledgebase_id },
+            ip_address: grabRequestIP(req),
+        });
+
+        return {
+            success: true,
+            msg: `Deleted ${knowledgebase.name}.`,
+            singleRes: await grabKnowledgebasesOverview({ user_id: user.id }),
+        };
+    } catch (error: unknown) {
+        return { success: false, msg: safeErrorMessage({ error }) };
+    }
+};
@@ -0,0 +1,49 @@
+import userAuth from "@/src/functions/backend/auth/user-auth";
+import grabKnowledgebaseDocumentRow from "@/src/functions/backend/db/knowledgebases/grab-knowledgebase-document-row";
+import { KnowledgebaseDocumentIdRequestSchema } from "@/src/schemas/knowledgebase-schema";
+import AppError from "@/src/utils/app-error";
+import parseWithSchema from "@/src/utils/parse-with-schema";
+import canManageCrew from "@/src/utils/rbac/can-manage-crew";
+import safeErrorMessage from "@/src/utils/safe-error-message";
+import type {
+    APIResponseObject,
+    BunextAPIRouteHandler,
+} from "@moduletrace/bunext/types";
+
+/**
+ * Super admins and admins: a text document's title and content, loaded
+ * when it's opened to read or edit.
+ */
+export const handler: BunextAPIRouteHandler<
+    APIResponseObject<{ document_id: number; name: string; content: string }>
+> = async ({ req, body }) => {
+    try {
+        if (req.method != "POST") {
+            throw new AppError(`Method not allowed`);
+        }
+
+        const { user, user_types } = await userAuth({ req });
+
+        if (!user?.logged_in_status || !user.id) {
+            return { success: false, msg: `Unauthorized`, logoutUser: true };
+        }
+
+        if (!canManageCrew({ user_types })) {
+            throw new AppError(`Only an admin can do that.`);
+        }
+
+        const { document_id } = parseWithSchema({ schema: KnowledgebaseDocumentIdRequestSchema, data: body });
+        const document = await grabKnowledgebaseDocumentRow({ document_id });
+
+        if (document.source != "text") {
+            throw new AppError(`Only a text document can be opened here.`);
+        }
+
+        return {
+            success: true,
+            singleRes: { document_id: document.id, name: document.name || "", content: document.content || "" },
+        };
+    } catch (error: unknown) {
+        return { success: false, msg: safeErrorMessage({ error }) };
+    }
+};
@@ -0,0 +1,42 @@
+import userAuth from "@/src/functions/backend/auth/user-auth";
+import listKnowledgebaseDocuments from "@/src/functions/backend/db/knowledgebases/list-knowledgebase-documents";
+import { KnowledgebaseIdRequestSchema } from "@/src/schemas/knowledgebase-schema";
+import type { KnowledgebaseDocumentsPayload } from "@/src/types";
+import AppError from "@/src/utils/app-error";
+import parseWithSchema from "@/src/utils/parse-with-schema";
+import canManageCrew from "@/src/utils/rbac/can-manage-crew";
+import safeErrorMessage from "@/src/utils/safe-error-message";
+import type {
+    APIResponseObject,
+    BunextAPIRouteHandler,
+} from "@moduletrace/bunext/types";
+
+/**
+ * Super admins and admins: a knowledgebase's documents, loaded when its
+ * documents are opened on the settings page.
+ */
+export const handler: BunextAPIRouteHandler<
+    APIResponseObject<KnowledgebaseDocumentsPayload>
+> = async ({ req, body }) => {
+    try {
+        if (req.method != "POST") {
+            throw new AppError(`Method not allowed`);
+        }
+
+        const { user, user_types } = await userAuth({ req });
+
+        if (!user?.logged_in_status || !user.id) {
+            return { success: false, msg: `Unauthorized`, logoutUser: true };
+        }
+
+        if (!canManageCrew({ user_types })) {
+            throw new AppError(`Only an admin can do that.`);
+        }
+
+        const { knowledgebase_id } = parseWithSchema({ schema: KnowledgebaseIdRequestSchema, data: body });
+
+        return { success: true, singleRes: await listKnowledgebaseDocuments({ knowledgebase_id }) };
+    } catch (error: unknown) {
+        return { success: false, msg: safeErrorMessage({ error }) };
+    }
+};
@@ -0,0 +1,34 @@
+import userAuth from "@/src/functions/backend/auth/user-auth";
+import grabKnowledgebasesOverview from "@/src/functions/backend/db/knowledgebases/grab-knowledgebases-overview";
+import type { KnowledgebasesOverviewPayload } from "@/src/types";
+import AppError from "@/src/utils/app-error";
+import canManageCrew from "@/src/utils/rbac/can-manage-crew";
+import safeErrorMessage from "@/src/utils/safe-error-message";
+import type {
+    APIResponseObject,
+    BunextAPIRouteHandler,
+} from "@moduletrace/bunext/types";
+
+/**
+ * Super admins and admins: the Knowledgebases page's list again, after its
+ * documents changed (their counts and how much of each is read).
+ */
+export const handler: BunextAPIRouteHandler<
+    APIResponseObject<KnowledgebasesOverviewPayload>
+> = async ({ req }) => {
+    try {
+        const { user, user_types } = await userAuth({ req });
+
+        if (!user?.logged_in_status || !user.id) {
+            return { success: false, msg: `Unauthorized`, logoutUser: true };
+        }
+
+        if (!canManageCrew({ user_types })) {
+            throw new AppError(`Only an admin can do that.`);
+        }
+
+        return { success: true, singleRes: await grabKnowledgebasesOverview({ user_id: user.id }) };
+    } catch (error: unknown) {
+        return { success: false, msg: safeErrorMessage({ error }) };
+    }
+};
@@ -0,0 +1,53 @@
+import grabSuperAdminUser from "@/src/functions/backend/backups/grab-super-admin-user";
+import grabKnowledgebasesOverview from "@/src/functions/backend/db/knowledgebases/grab-knowledgebases-overview";
+import reindexKnowledgebase from "@/src/functions/backend/db/knowledgebases/reindex-knowledgebase";
+import logEvent, { grabRequestIP } from "@/src/functions/backend/logger";
+import { KnowledgebaseIdRequestSchema } from "@/src/schemas/knowledgebase-schema";
+import type { KnowledgebasesOverviewPayload } from "@/src/types";
+import AppError from "@/src/utils/app-error";
+import parseWithSchema from "@/src/utils/parse-with-schema";
+import safeErrorMessage from "@/src/utils/safe-error-message";
+import type {
+    APIResponseObject,
+    BunextAPIRouteHandler,
+} from "@moduletrace/bunext/types";
+
+/**
+ * Super admin only: reads every document of a knowledgebase again, with the
+ * install's embedding model as it is now.
+ */
+export const handler: BunextAPIRouteHandler<
+    APIResponseObject<KnowledgebasesOverviewPayload>
+> = async ({ req, body }) => {
+    try {
+        if (req.method != "POST") {
+            throw new AppError(`Method not allowed`);
+        }
+
+        const user = await grabSuperAdminUser({ req });
+
+        if (!user?.id) {
+            throw new AppError(`Only a super admin can do that.`);
+        }
+
+        const { knowledgebase_id } = parseWithSchema({ schema: KnowledgebaseIdRequestSchema, data: body });
+        const queued = await reindexKnowledgebase({ knowledgebase_id });
+
+        await logEvent({
+            title: "Knowledgebase re-indexed",
+            category: "system",
+            user_id: user.id,
+            plain_text: `User #${user.id} re-indexed the knowledgebase #${knowledgebase_id} (${queued} documents).`,
+            metadata: { knowledgebase_id, queued },
+            ip_address: grabRequestIP(req),
+        });
+
+        return {
+            success: true,
+            msg: queued ? `Reading ${queued} ${queued == 1 ? "document" : "documents"} again.` : "It has no documents yet.",
+            singleRes: await grabKnowledgebasesOverview({ user_id: user.id }),
+        };
+    } catch (error: unknown) {
+        return { success: false, msg: safeErrorMessage({ error }) };
+    }
+};
@@ -0,0 +1,52 @@
+import grabSuperAdminUser from "@/src/functions/backend/backups/grab-super-admin-user";
+import grabKnowledgebasesOverview from "@/src/functions/backend/db/knowledgebases/grab-knowledgebases-overview";
+import saveKnowledgebase from "@/src/functions/backend/db/knowledgebases/save-knowledgebase";
+import logEvent, { grabRequestIP } from "@/src/functions/backend/logger";
+import { SaveKnowledgebaseRequestSchema } from "@/src/schemas/knowledgebase-schema";
+import type { KnowledgebasesOverviewPayload } from "@/src/types";
+import AppError from "@/src/utils/app-error";
+import parseWithSchema from "@/src/utils/parse-with-schema";
+import safeErrorMessage from "@/src/utils/safe-error-message";
+import type {
+    APIResponseObject,
+    BunextAPIRouteHandler,
+} from "@moduletrace/bunext/types";
+
+/**
+ * Super admin only: adds or edits a knowledgebase.
+ */
+export const handler: BunextAPIRouteHandler<
+    APIResponseObject<KnowledgebasesOverviewPayload>
+> = async ({ req, body }) => {
+    try {
+        if (req.method != "POST") {
+            throw new AppError(`Method not allowed`);
+        }
+
+        const user = await grabSuperAdminUser({ req });
+
+        if (!user?.id) {
+            throw new AppError(`Only a super admin can do that.`);
+        }
+
+        const data = parseWithSchema({ schema: SaveKnowledgebaseRequestSchema, data: body });
+        const knowledgebase_id = await saveKnowledgebase({ user_id: user.id, data });
+
+        await logEvent({
+            title: data.knowledgebase_id ? "Knowledgebase changed" : "Knowledgebase added",
+            category: "system",
+            user_id: user.id,
+            plain_text: `User #${user.id} ${data.knowledgebase_id ? "changed" : "added"} the knowledgebase ${data.name} (#${knowledgebase_id}).`,
+            metadata: { knowledgebase_id },
+            ip_address: grabRequestIP(req),
+        });
+
+        return {
+            success: true,
+            msg: `Saved ${data.name}.`,
+            singleRes: await grabKnowledgebasesOverview({ user_id: user.id }),
+        };
+    } catch (error: unknown) {
+        return { success: false, msg: safeErrorMessage({ error }) };
+    }
+};
@@ -0,0 +1,53 @@
+import grabSuperAdminUser from "@/src/functions/backend/backups/grab-super-admin-user";
+import listKnowledgebaseDocuments from "@/src/functions/backend/db/knowledgebases/list-knowledgebase-documents";
+import saveKnowledgebaseText from "@/src/functions/backend/db/knowledgebases/save-knowledgebase-text";
+import logEvent, { grabRequestIP } from "@/src/functions/backend/logger";
+import { SaveKnowledgebaseTextRequestSchema } from "@/src/schemas/knowledgebase-schema";
+import type { KnowledgebaseDocumentsPayload } from "@/src/types";
+import AppError from "@/src/utils/app-error";
+import parseWithSchema from "@/src/utils/parse-with-schema";
+import safeErrorMessage from "@/src/utils/safe-error-message";
+import type {
+    APIResponseObject,
+    BunextAPIRouteHandler,
+} from "@moduletrace/bunext/types";
+
+/**
+ * Super admin only: writes a text document into a knowledgebase, or
+ * changes one.
+ */
+export const handler: BunextAPIRouteHandler<
+    APIResponseObject<KnowledgebaseDocumentsPayload>
+> = async ({ req, body }) => {
+    try {
+        if (req.method != "POST") {
+            throw new AppError(`Method not allowed`);
+        }
+
+        const user = await grabSuperAdminUser({ req });
+
+        if (!user?.id) {
+            throw new AppError(`Only a super admin can do that.`);
+        }
+
+        const data = parseWithSchema({ schema: SaveKnowledgebaseTextRequestSchema, data: body });
+        const document_id = await saveKnowledgebaseText({ user_id: user.id, data });
+
+        await logEvent({
+            title: data.document_id ? "Knowledgebase document changed" : "Knowledgebase document added",
+            category: "system",
+            user_id: user.id,
+            plain_text: `User #${user.id} ${data.document_id ? "changed" : "wrote"} ${data.name} (#${document_id}) in the knowledgebase #${data.knowledgebase_id}.`,
+            metadata: { knowledgebase_id: data.knowledgebase_id, document_id },
+            ip_address: grabRequestIP(req),
+        });
+
+        return {
+            success: true,
+            msg: `Saved ${data.name}. It's searchable once it's read.`,
+            singleRes: await listKnowledgebaseDocuments({ knowledgebase_id: data.knowledgebase_id }),
+        };
+    } catch (error: unknown) {
+        return { success: false, msg: safeErrorMessage({ error }) };
+    }
+};
@@ -0,0 +1,59 @@
+import userAuth from "@/src/functions/backend/auth/user-auth";
+import setExtensionAccess from "@/src/functions/backend/db/extensions/set-extension-access";
+import grabKnowledgebasesOverview from "@/src/functions/backend/db/knowledgebases/grab-knowledgebases-overview";
+import logEvent, { grabRequestIP } from "@/src/functions/backend/logger";
+import { SetExtensionAccessRequestSchema } from "@/src/schemas/extension-schema";
+import type { KnowledgebasesOverviewPayload } from "@/src/types";
+import AppError from "@/src/utils/app-error";
+import parseWithSchema from "@/src/utils/parse-with-schema";
+import isReadOnlyUser from "@/src/utils/rbac/is-read-only-user";
+import safeErrorMessage from "@/src/utils/safe-error-message";
+import type {
+    APIResponseObject,
+    BunextAPIRouteHandler,
+} from "@moduletrace/bunext/types";
+
+/**
+ * Super admins and admins: attaches a knowledgebase to exactly these bots
+ * and workspaces. Only a super admin sets "all bots" (`setExtensionAccess`).
+ */
+export const handler: BunextAPIRouteHandler<
+    APIResponseObject<KnowledgebasesOverviewPayload>
+> = async ({ req, body }) => {
+    try {
+        if (req.method != "POST") {
+            throw new AppError(`Method not allowed`);
+        }
+
+        const { user, user_types } = await userAuth({ req });
+
+        if (!user?.logged_in_status || !user.id) {
+            return { success: false, msg: `Unauthorized`, logoutUser: true };
+        }
+
+        if (isReadOnlyUser({ user_types: user_types || [] })) {
+            throw new AppError(`This user can only read records.`);
+        }
+
+        const access = parseWithSchema({ schema: SetExtensionAccessRequestSchema, data: body });
+
+        await setExtensionAccess({ user_id: user.id, kind: "knowledgebase", ...access });
+
+        await logEvent({
+            title: "Knowledgebase access changed",
+            category: "system",
+            user_id: user.id,
+            plain_text: `User #${user.id} changed who gets the knowledgebase #${access.id}.`,
+            metadata: access,
+            ip_address: grabRequestIP(req),
+        });
+
+        return {
+            success: true,
+            msg: `Saved who gets it.`,
+            singleRes: await grabKnowledgebasesOverview({ user_id: user.id }),
+        };
+    } catch (error: unknown) {
+        return { success: false, msg: safeErrorMessage({ error }) };
+    }
+};
@@ -0,0 +1,111 @@
+import grabSuperAdminUser from "@/src/functions/backend/backups/grab-super-admin-user";
+import listKnowledgebaseDocuments from "@/src/functions/backend/db/knowledgebases/list-knowledgebase-documents";
+import recordKnowledgebaseDocument from "@/src/functions/backend/db/knowledgebases/record-knowledgebase-document";
+import uploadAndRecordMedia from "@/src/functions/backend/db/users/media/upload-and-record-media";
+import logEvent, { grabRequestIP, logError } from "@/src/functions/backend/logger";
+import { AppData } from "@/src/data/app-data";
+import { BotTextFileExtensions } from "@/src/dict/bot-file-dict";
+import { UploadKnowledgebaseDocumentRequestSchema } from "@/src/schemas/knowledgebase-schema";
+import type { KnowledgebaseDocumentsPayload } from "@/src/types";
+import AppError from "@/src/utils/app-error";
+import attachmentFileKind from "@/src/utils/attachment-file-kind";
+import bufferFromBase64 from "@/src/utils/buffer-from-base-64";
+import canExtractText from "@/src/utils/can-extract-text";
+import parseWithSchema from "@/src/utils/parse-with-schema";
+import safeErrorMessage from "@/src/utils/safe-error-message";
+import type {
+    APIResponseObject,
+    BunextAPIRouteHandler,
+} from "@moduletrace/bunext/types";
+
+/**
+ * Super admin only: adds one file to a knowledgebase. Only documents whose
+ * text can be read are taken (PDF, DOCX, markdown, plain text and the
+ * like); the bytes are kept in private media and the document is queued to
+ * be chunked and embedded.
+ */
+export const handler: BunextAPIRouteHandler<
+    APIResponseObject<KnowledgebaseDocumentsPayload>
+> = async ({ req, body }) => {
+    try {
+        if (req.method != "POST") {
+            throw new AppError(`Method not allowed`);
+        }
+
+        const user = await grabSuperAdminUser({ req });
+
+        if (!user?.id) {
+            throw new AppError(`Only a super admin can do that.`);
+        }
+
+        const { knowledgebase_id, name, data_url } = parseWithSchema({
+            schema: UploadKnowledgebaseDocumentRequestSchema,
+            data: body,
+        });
+
+        const mime = data_url.match(/^data:([^;,]*)/)?.[1] || "";
+
+        if (!canExtractText({ name, mime_type: mime })) {
+            throw new AppError(
+                `${name} has no text to read. A knowledgebase takes ${BotTextFileExtensions.join(", ")} files.`,
+            );
+        }
+
+        const { media_type, ext } = attachmentFileKind({ mime, name });
+        const { buffer } = await bufferFromBase64(data_url);
+
+        if (!buffer.length) {
+            throw new AppError(`${name} is empty.`);
+        }
+
+        if (buffer.length > AppData.KnowledgebaseDocumentMaxBytes) {
+            throw new AppError(
+                `${name} is too big. Documents can be up to ${Math.round(AppData.KnowledgebaseDocumentMaxBytes / 1024 / 1024)} MB.`,
+            );
+        }
+
+        const media = await uploadAndRecordMedia({
+            data: buffer,
+            media_type,
+            media_mime_type: ext,
+            media_paradigms: ["knowledgebase-document"],
+            media: { title: name },
+            extract_media_text_content: true,
+            user: { id: Number(user.id) },
+        }).catch(async (error) => {
+            await logError({ title: `Knowledgebase document ${name} couldn't be saved`, error }).catch(() => {});
+            throw new AppError(`Couldn't save ${name}.`);
+        });
+
+        if (!media.singleRes?.id) {
+            throw new AppError(`Couldn't save ${name}.`);
+        }
+
+        const document_id = await recordKnowledgebaseDocument({
+            user_id: user.id,
+            knowledgebase_id,
+            name,
+            source: "file",
+            media_id: media.singleRes.id,
+            mime_type: mime,
+            size: buffer.length,
+        });
+
+        await logEvent({
+            title: "Knowledgebase document added",
+            category: "system",
+            user_id: user.id,
+            plain_text: `User #${user.id} added ${name} (#${document_id}) to the knowledgebase #${knowledgebase_id}.`,
+            metadata: { knowledgebase_id, document_id },
+            ip_address: grabRequestIP(req),
+        });
+
+        return {
+            success: true,
+            msg: `Added ${name}. It's searchable once it's read.`,
+            singleRes: await listKnowledgebaseDocuments({ knowledgebase_id }),
+        };
+    } catch (error: unknown) {
+        return { success: false, msg: safeErrorMessage({ error }) };
+    }
+};