libre-webui 0.24.1 → 0.26.0

package/backend/dist/utils/automationSchedule.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Recurrence math for calendar events and automations. All computation uses
+ * the server's local timezone; wall-clock trigger times stay stable across
+ * DST because candidates are built from local date components, which the
+ * Date constructor renormalizes.
+ */
+import type { AutomationTrigger } from '../types/index.js';
+export declare class InvalidTriggerError extends Error {
+    constructor(message: string);
+}
+/** Validate untrusted input into a well-formed trigger list. */
+export declare function validateTriggers(value: unknown, maximum?: number): AutomationTrigger[];
+/**
+ * The first occurrence of a trigger strictly after `after`, or null when the
+ * trigger is exhausted. The strictly-after invariant is what prevents a fired
+ * occurrence from firing again.
+ */
+export declare function nextOccurrence(trigger: AutomationTrigger, after: number): number | null;
+/** The earliest next occurrence across all triggers, or null when exhausted. */
+export declare function nextRunAt(triggers: readonly AutomationTrigger[], after: number): number | null;
+/**
+ * Every occurrence in [from, to), ascending, capped. Used to project
+ * recurring calendar events and upcoming automation runs onto a date range.
+ */
+export declare function occurrencesBetween(triggers: readonly AutomationTrigger[], from: number, to: number, cap?: number): number[];
+//# sourceMappingURL=automationSchedule.d.ts.map

package/backend/dist/utils/automationSchedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automationSchedule.d.ts","sourceRoot":"","sources":["../../src/utils/automationSchedule.ts"],"names":[],"mappings":"AAiBA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAmB3D,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,gEAAgE;AAChE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,OAAO,SAAI,GACV,iBAAiB,EAAE,CAoHrB;AAqBD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CA8Ef;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CACvB,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CASf;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,GAAG,SAAM,GACR,MAAM,EAAE,CAYV"}

package/backend/dist/utils/automationSchedule.js

@@ -0,0 +1,231 @@
+/*
+ * Libre WebUI
+ * Copyright (C) 2025 Kroonen AI, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const DAY_MS = 24 * 60 * 60 * 1000;
+const TRIGGER_KINDS = [
+    'once',
+    'hourly',
+    'daily',
+    'weekly',
+    'monthly',
+    'yearly',
+];
+const isInt = (value, min, max) => typeof value === 'number' &&
+    Number.isSafeInteger(value) &&
+    value >= min &&
+    value <= max;
+export class InvalidTriggerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidTriggerError';
+    }
+}
+/** Validate untrusted input into a well-formed trigger list. */
+export function validateTriggers(value, maximum = 5) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new InvalidTriggerError('At least one trigger is required');
+    }
+    if (value.length > maximum) {
+        throw new InvalidTriggerError(`At most ${maximum} triggers are allowed`);
+    }
+    return value.map(item => {
+        if (typeof item !== 'object' || item === null) {
+            throw new InvalidTriggerError('Each trigger must be an object');
+        }
+        const trigger = item;
+        switch (trigger.kind) {
+            case 'once': {
+                if (!isInt(trigger.at, 0, 8.64e15)) {
+                    throw new InvalidTriggerError('A once trigger needs an epoch-ms "at" time');
+                }
+                return { kind: 'once', at: trigger.at };
+            }
+            case 'hourly': {
+                if (!isInt(trigger.minute, 0, 59)) {
+                    throw new InvalidTriggerError('An hourly trigger needs a minute between 0 and 59');
+                }
+                const bounds = {};
+                if (trigger.startHour !== undefined) {
+                    if (!isInt(trigger.startHour, 0, 23)) {
+                        throw new InvalidTriggerError('startHour must be 0-23');
+                    }
+                    bounds.startHour = trigger.startHour;
+                }
+                if (trigger.endHour !== undefined) {
+                    if (!isInt(trigger.endHour, 0, 23)) {
+                        throw new InvalidTriggerError('endHour must be 0-23');
+                    }
+                    bounds.endHour = trigger.endHour;
+                }
+                if (bounds.startHour !== undefined &&
+                    bounds.endHour !== undefined &&
+                    bounds.endHour < bounds.startHour) {
+                    throw new InvalidTriggerError('endHour must not precede startHour');
+                }
+                return { kind: 'hourly', minute: trigger.minute, ...bounds };
+            }
+            case 'daily': {
+                if (!isInt(trigger.hour, 0, 23) || !isInt(trigger.minute, 0, 59)) {
+                    throw new InvalidTriggerError('A daily trigger needs an hour (0-23) and minute (0-59)');
+                }
+                return { kind: 'daily', hour: trigger.hour, minute: trigger.minute };
+            }
+            case 'weekly': {
+                if (!isInt(trigger.dayOfWeek, 0, 6) ||
+                    !isInt(trigger.hour, 0, 23) ||
+                    !isInt(trigger.minute, 0, 59)) {
+                    throw new InvalidTriggerError('A weekly trigger needs dayOfWeek (0-6), hour, and minute');
+                }
+                return {
+                    kind: 'weekly',
+                    dayOfWeek: trigger.dayOfWeek,
+                    hour: trigger.hour,
+                    minute: trigger.minute,
+                };
+            }
+            case 'monthly': {
+                if (!isInt(trigger.dayOfMonth, 1, 31) ||
+                    !isInt(trigger.hour, 0, 23) ||
+                    !isInt(trigger.minute, 0, 59)) {
+                    throw new InvalidTriggerError('A monthly trigger needs dayOfMonth (1-31), hour, and minute');
+                }
+                return {
+                    kind: 'monthly',
+                    dayOfMonth: trigger.dayOfMonth,
+                    hour: trigger.hour,
+                    minute: trigger.minute,
+                };
+            }
+            case 'yearly': {
+                if (!isInt(trigger.month, 1, 12) ||
+                    !isInt(trigger.dayOfMonth, 1, 31) ||
+                    !isInt(trigger.hour, 0, 23) ||
+                    !isInt(trigger.minute, 0, 59)) {
+                    throw new InvalidTriggerError('A yearly trigger needs month (1-12), dayOfMonth, hour, and minute');
+                }
+                return {
+                    kind: 'yearly',
+                    month: trigger.month,
+                    dayOfMonth: trigger.dayOfMonth,
+                    hour: trigger.hour,
+                    minute: trigger.minute,
+                };
+            }
+            default:
+                throw new InvalidTriggerError(`Unknown trigger kind; expected one of ${TRIGGER_KINDS.join(', ')}`);
+        }
+    });
+}
+const daysInMonth = (year, monthIndex) => new Date(year, monthIndex + 1, 0).getDate();
+const atLocalTime = (base, dayOffset, hour, minute) => new Date(base.getFullYear(), base.getMonth(), base.getDate() + dayOffset, hour, minute, 0, 0).getTime();
+/**
+ * The first occurrence of a trigger strictly after `after`, or null when the
+ * trigger is exhausted. The strictly-after invariant is what prevents a fired
+ * occurrence from firing again.
+ */
+export function nextOccurrence(trigger, after) {
+    const base = new Date(after);
+    switch (trigger.kind) {
+        case 'once':
+            return trigger.at > after ? trigger.at : null;
+        case 'hourly': {
+            const start = trigger.startHour ?? 0;
+            const end = trigger.endHour ?? 23;
+            for (let offset = 0; offset <= 1; offset += 1) {
+                const day = new Date(after + offset * DAY_MS);
+                const firstHour = offset === 0 ? 0 : start;
+                for (let hour = firstHour; hour <= 23; hour += 1) {
+                    if (hour < start || hour > end)
+                        continue;
+                    const candidate = atLocalTime(day, 0, hour, trigger.minute);
+                    if (candidate > after)
+                        return candidate;
+                }
+            }
+            return null;
+        }
+        case 'daily': {
+            for (let offset = 0; offset <= 1; offset += 1) {
+                const candidate = atLocalTime(base, offset, trigger.hour, trigger.minute);
+                if (candidate > after)
+                    return candidate;
+            }
+            return null;
+        }
+        case 'weekly': {
+            const todayDow = base.getDay();
+            let offset = (trigger.dayOfWeek - todayDow + 7) % 7;
+            let candidate = atLocalTime(base, offset, trigger.hour, trigger.minute);
+            if (candidate <= after) {
+                offset += 7;
+                candidate = atLocalTime(base, offset, trigger.hour, trigger.minute);
+            }
+            return candidate;
+        }
+        case 'monthly': {
+            for (let monthOffset = 0; monthOffset <= 1; monthOffset += 1) {
+                const year = base.getFullYear();
+                const month = base.getMonth() + monthOffset;
+                const day = Math.min(trigger.dayOfMonth, daysInMonth(year, month));
+                const candidate = new Date(year, month, day, trigger.hour, trigger.minute, 0, 0).getTime();
+                if (candidate > after)
+                    return candidate;
+            }
+            return null;
+        }
+        case 'yearly': {
+            for (let yearOffset = 0; yearOffset <= 1; yearOffset += 1) {
+                const year = base.getFullYear() + yearOffset;
+                const monthIndex = trigger.month - 1;
+                const day = Math.min(trigger.dayOfMonth, daysInMonth(year, monthIndex));
+                const candidate = new Date(year, monthIndex, day, trigger.hour, trigger.minute, 0, 0).getTime();
+                if (candidate > after)
+                    return candidate;
+            }
+            return null;
+        }
+    }
+}
+/** The earliest next occurrence across all triggers, or null when exhausted. */
+export function nextRunAt(triggers, after) {
+    let earliest = null;
+    for (const trigger of triggers) {
+        const candidate = nextOccurrence(trigger, after);
+        if (candidate !== null && (earliest === null || candidate < earliest)) {
+            earliest = candidate;
+        }
+    }
+    return earliest;
+}
+/**
+ * Every occurrence in [from, to), ascending, capped. Used to project
+ * recurring calendar events and upcoming automation runs onto a date range.
+ */
+export function occurrencesBetween(triggers, from, to, cap = 500) {
+    const occurrences = new Set();
+    for (const trigger of triggers) {
+        let cursor = from - 1;
+        while (occurrences.size < cap) {
+            const candidate = nextOccurrence(trigger, cursor);
+            if (candidate === null || candidate >= to)
+                break;
+            occurrences.add(candidate);
+            cursor = candidate;
+        }
+    }
+    return [...occurrences].sort((left, right) => left - right);
+}
+//# sourceMappingURL=automationSchedule.js.map

package/backend/dist/utils/automationSchedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"automationSchedule.js","sourceRoot":"","sources":["../../src/utils/automationSchedule.ts"],"names":[],"mappings":"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"}

package/backend/dist/utils/chatDocumentContext.d.ts

@@ -1,14 +1,39 @@
+/** One cited excerpt of a source document. */
+export interface ChatDocumentCitation {
+    chunkIndex: number;
+    /** Human-readable source location (page/slide/sheet/section). */
+    location?: string;
+    /** Retrieval score of this excerpt within the query's ranking. */
+    score?: number;
+}
 export interface ChatDocumentSource {
     id: string;
     filename: string;
+    /** Present in retrieval mode: which excerpts contributed, best first. */
+    citations?: ChatDocumentCitation[];
+    /** True when the document's full content entered context. */
+    full?: boolean;
 }
 export interface ChatDocumentContext {
     documentContext: string;
     enhancedContent: string;
     hasRelevantContext: boolean;
-    /** Documents that actually contributed chunks, deduplicated, best first. */
+    /** Documents that actually contributed, deduplicated, best first. */
     sources: ChatDocumentSource[];
+    /** How document context was assembled for this turn. */
+    mode: 'retrieval' | 'full';
+    /** Set when full-document mode was requested but exceeded the guard. */
+    fullContextSkipped?: {
+        estimatedTokens: number;
+        maxTokens: number;
+    };
 }
+/**
+ * Full-document mode sends entire extracted sources instead of retrieved
+ * excerpts, so it needs a hard token guard. Deliberately conservative:
+ * most local models run 8k-128k contexts.
+ */
+export declare const fullDocumentContextMaxTokens: () => number;
 export declare const EMPTY_CHAT_DOCUMENT_CONTEXT: (message: string) => ChatDocumentContext;
 export declare function buildChatDocumentContext(message: string, sessionId: string, userId: string, signal?: AbortSignal): Promise<ChatDocumentContext>;
 //# sourceMappingURL=chatDocumentContext.d.ts.map

package/backend/dist/utils/chatDocumentContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chatDocumentContext.d.ts","sourceRoot":"","sources":["../../src/utils/chatDocumentContext.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,4EAA4E;IAC5E,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAED,eAAO,MAAM,2BAA2B,YAC7B,MAAM,KACd,mBAKD,CAAC;AAEH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,mBAAmB,CAAC,CA6D9B"}
+{"version":3,"file":"chatDocumentContext.d.ts","sourceRoot":"","sources":["../../src/utils/chatDocumentContext.ts"],"names":[],"mappings":"AAsBA,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,SAAS,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACnC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,qEAAqE;IACrE,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,wDAAwD;IACxD,IAAI,EAAE,WAAW,GAAG,MAAM,CAAC;IAC3B,wEAAwE;IACxE,kBAAkB,CAAC,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,QAAO,MAU/C,CAAC;AAEF,eAAO,MAAM,2BAA2B,YAC7B,MAAM,KACd,mBAMD,CAAC;AA6DH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,mBAAmB,CAAC,CAkF9B"}

package/backend/dist/utils/chatDocumentContext.js

@@ -4,7 +4,7 @@
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at:
+ * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
@@ -15,48 +15,115 @@
  * limitations under the License.
  */
 import documentService from '../services/documentService.js';
+import { estimateTextTokens } from '../services/contextCompactionService.js';
 import storageService from '../storage.js';
 import { throwIfChatGenerationCancelled } from './chatCancellation.js';
+/**
+ * Full-document mode sends entire extracted sources instead of retrieved
+ * excerpts, so it needs a hard token guard. Deliberately conservative:
+ * most local models run 8k-128k contexts.
+ */
+export const fullDocumentContextMaxTokens = () => {
+    const raw = process.env.FULL_DOCUMENT_CONTEXT_MAX_TOKENS;
+    if (raw === undefined)
+        return 32000;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isSafeInteger(value) || value < 1000 || value > 2000000) {
+        throw new Error('FULL_DOCUMENT_CONTEXT_MAX_TOKENS must be between 1000 and 2000000');
+    }
+    return value;
+};
 export const EMPTY_CHAT_DOCUMENT_CONTEXT = (message) => ({
     documentContext: '',
     enhancedContent: message,
     hasRelevantContext: false,
     sources: [],
+    mode: 'retrieval',
 });
+const buildFullDocumentContext = async (message, sessionId, userId, knowledgeCollectionIds, signal) => {
+    const documents = (await documentService.getDocumentsInScope(userId, sessionId, knowledgeCollectionIds)).filter(document => (document.content ?? '').trim().length > 0);
+    throwIfChatGenerationCancelled(signal);
+    if (documents.length === 0) {
+        return { context: EMPTY_CHAT_DOCUMENT_CONTEXT(message) };
+    }
+    const maxTokens = fullDocumentContextMaxTokens();
+    const estimatedTokens = documents.reduce((total, document) => total + estimateTextTokens(document.content ?? ''), 0);
+    if (estimatedTokens > maxTokens) {
+        // Too large to send whole: fall back to retrieval, but tell the caller
+        // so the client can explain why full mode did not apply.
+        return { skipped: { estimatedTokens, maxTokens } };
+    }
+    const documentContext = '\n\n--- ATTACHED DOCUMENTS (full content) ---\n' +
+        documents
+            .map(document => `Document: ${document.filename}\n${document.content ?? ''}\n`)
+            .join('\n---\n') +
+        '\n--- END DOCUMENTS ---\n\n';
+    return {
+        context: {
+            documentContext,
+            enhancedContent: `${documentContext}User question: ${message}`,
+            hasRelevantContext: true,
+            sources: documents.map(document => ({
+                id: document.id,
+                filename: document.filename,
+                full: true,
+            })),
+            mode: 'full',
+        },
+    };
+};
 export async function buildChatDocumentContext(message, sessionId, userId, signal) {
     throwIfChatGenerationCancelled(signal);
     // Documents from knowledge collections attached to this chat join the
     // session's own uploads and the user's standing uploads in the
-    // searchable scope. searchDocuments picks semantic or keyword retrieval
+    // searchable scope. searchDocuments picks hybrid or keyword retrieval
     // by the embedding settings, so retrieval works either way.
-    const knowledgeCollectionIds = (await storageService.getSession(sessionId, userId))?.settings?.knowledgeCollectionIds;
+    const settings = (await storageService.getSession(sessionId, userId))
+        ?.settings;
+    const knowledgeCollectionIds = settings?.knowledgeCollectionIds;
+    throwIfChatGenerationCancelled(signal);
+    let fullContextSkipped;
+    if (settings?.fullDocumentContext === true) {
+        const outcome = await buildFullDocumentContext(message, sessionId, userId, knowledgeCollectionIds, signal);
+        if (outcome.context)
+            return outcome.context;
+        fullContextSkipped = outcome.skipped;
+    }
     throwIfChatGenerationCancelled(signal);
     const relevantDocuments = await documentService.searchDocuments(message, userId, sessionId, 5, knowledgeCollectionIds, signal);
     throwIfChatGenerationCancelled(signal);
     if (relevantDocuments.length === 0) {
-        return EMPTY_CHAT_DOCUMENT_CONTEXT(message);
+        return {
+            ...EMPTY_CHAT_DOCUMENT_CONTEXT(message),
+            ...(fullContextSkipped ? { fullContextSkipped } : {}),
+        };
     }
-    const documentsMap = new Map();
-    const sources = [];
+    const sourcesById = new Map();
     for (const chunk of relevantDocuments) {
         throwIfChatGenerationCancelled(signal);
-        if (!documentsMap.has(chunk.documentId)) {
-            const document = await documentService.getDocument(chunk.documentId, userId);
-            throwIfChatGenerationCancelled(signal);
-            documentsMap.set(chunk.documentId, document);
-            sources.push({
+        let source = sourcesById.get(chunk.documentId);
+        if (!source) {
+            source = {
                 id: chunk.documentId,
-                filename: document?.filename || 'Unknown Document',
-            });
+                filename: chunk.filename || 'Unknown Document',
+                citations: [],
+            };
+            sourcesById.set(chunk.documentId, source);
         }
+        source.citations.push({
+            chunkIndex: chunk.chunkIndex,
+            ...(chunk.location ? { location: chunk.location } : {}),
+            ...(chunk.score !== undefined ? { score: chunk.score } : {}),
+        });
     }
-    throwIfChatGenerationCancelled(signal);
     const documentContext = '\n\n--- RELEVANT DOCUMENTS ---\n' +
         relevantDocuments
             .map((chunk, index) => {
-            const doc = documentsMap.get(chunk.documentId);
-            const docTitle = doc ? doc.filename : 'Unknown Document';
-            return `Document ${index + 1}: ${docTitle} (chunk ${chunk.chunkIndex + 1})\n${chunk.content}\n`;
+            const docTitle = chunk.filename || 'Unknown Document';
+            const where = chunk.location
+                ? `chunk ${chunk.chunkIndex + 1}, ${chunk.location}`
+                : `chunk ${chunk.chunkIndex + 1}`;
+            return `Document ${index + 1}: ${docTitle} (${where})\n${chunk.content}\n`;
         })
             .join('\n---\n') +
         '\n--- END DOCUMENTS ---\n\n';
@@ -64,7 +131,9 @@ export async function buildChatDocumentContext(message, sessionId, userId, signa
         documentContext,
         enhancedContent: `${documentContext}User question: ${message}`,
         hasRelevantContext: true,
-        sources,
+        sources: [...sourcesById.values()],
+        mode: 'retrieval',
+        ...(fullContextSkipped ? { fullContextSkipped } : {}),
     };
 }
 //# sourceMappingURL=chatDocumentContext.js.map

package/backend/dist/utils/chatDocumentContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"chatDocumentContext.js","sourceRoot":"","sources":["../../src/utils/chatDocumentContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,eAAe,MAAM,gCAAgC,CAAC;AAC7D,OAAO,cAAc,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,8BAA8B,EAAE,MAAM,uBAAuB,CAAC;AAevE,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,OAAe,EACM,EAAE,CAAC,CAAC;IACzB,eAAe,EAAE,EAAE;IACnB,eAAe,EAAE,OAAO;IACxB,kBAAkB,EAAE,KAAK;IACzB,OAAO,EAAE,EAAE;CACZ,CAAC,CAAC;AAEH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,OAAe,EACf,SAAiB,EACjB,MAAc,EACd,MAAoB;IAEpB,8BAA8B,CAAC,MAAM,CAAC,CAAC;IACvC,sEAAsE;IACtE,+DAA+D;IAC/D,wEAAwE;IACxE,4DAA4D;IAC5D,MAAM,sBAAsB,GAAG,CAC7B,MAAM,cAAc,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CACnD,EAAE,QAAQ,EAAE,sBAAsB,CAAC;IACpC,8BAA8B,CAAC,MAAM,CAAC,CAAC;IAEvC,MAAM,iBAAiB,GAAG,MAAM,eAAe,CAAC,eAAe,CAC7D,OAAO,EACP,MAAM,EACN,SAAS,EACT,CAAC,EACD,sBAAsB,EACtB,MAAM,CACP,CAAC;IACF,8BAA8B,CAAC,MAAM,CAAC,CAAC;IAEvC,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,2BAA2B,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,GAAG,EAAE,CAAC;IAC/B,MAAM,OAAO,GAAyB,EAAE,CAAC;IACzC,KAAK,MAAM,KAAK,IAAI,iBAAiB,EAAE,CAAC;QACtC,8BAA8B,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;YACxC,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,WAAW,CAChD,KAAK,CAAC,UAAU,EAChB,MAAM,CACP,CAAC;YACF,8BAA8B,CAAC,MAAM,CAAC,CAAC;YACvC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YAC7C,OAAO,CAAC,IAAI,CAAC;gBACX,EAAE,EAAE,KAAK,CAAC,UAAU;gBACpB,QAAQ,EAAE,QAAQ,EAAE,QAAQ,IAAI,kBAAkB;aACnD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,8BAA8B,CAAC,MAAM,CAAC,CAAC;IAEvC,MAAM,eAAe,GACnB,kCAAkC;QAClC,iBAAiB;aACd,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;YACpB,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC/C,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC;YACzD,OAAO,YAAY,KAAK,GAAG,CAAC,KAAK,QAAQ,WAAW,KAAK,CAAC,UAAU,GAAG,CAAC,MAAM,KAAK,CAAC,OAAO,IAAI,CAAC;QAClG,CAAC,CAAC;aACD,IAAI,CAAC,SAAS,CAAC;QAClB,6BAA6B,CAAC;IAEhC,OAAO;QACL,eAAe;QACf,eAAe,EAAE,GAAG,eAAe,kBAAkB,OAAO,EAAE;QAC9D,kBAAkB,EAAE,IAAI;QACxB,OAAO;KACR,CAAC;AACJ,CAAC"}
+{"version":3,"file":"chatDocumentContext.js","sourceRoot":"","sources":["../../src/utils/chatDocumentContext.ts"],"names":[],"mappings":"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"}

package/backend/dist/utils/documentExtraction.d.ts

@@ -0,0 +1,69 @@
+import type { DocumentFileType } from '../types/index.js';
+/**
+ * Document extraction for knowledge ingestion.
+ *
+ * Every supported upload type resolves to one canonical `DocumentFileType`
+ * and one extractor that returns plain text plus an optional segment map.
+ * Segments record where pages, slides, sheets, and Markdown sections start
+ * and end inside the extracted text, so retrieval can cite an exact source
+ * location without a second parse of the original file.
+ *
+ * OOXML formats are unpacked with the in-repo bounded ZIP reader and a
+ * narrow text-run scan of the document XML; the goal is faithful text for
+ * retrieval, not layout fidelity. Images/OCR and audio transcription are
+ * deliberately not extracted here — they are documented boundaries until an
+ * OCR engine and a default speech-to-text route exist.
+ */
+export type { DocumentFileType } from '../types/index.js';
+export interface DocumentSegment {
+    kind: 'page' | 'slide' | 'sheet' | 'section';
+    label: string;
+    startChar: number;
+    endChar: number;
+}
+export interface ExtractedDocumentContent {
+    content: string;
+    segments: DocumentSegment[];
+}
+export declare class DocumentExtractionError extends Error {
+    constructor(message: string);
+}
+export declare const SUPPORTED_DOCUMENT_EXTENSIONS: readonly string[];
+export declare const SUPPORTED_DOCUMENT_MIME_TYPES: readonly string[];
+/**
+ * Resolves the canonical file type for an upload. The extension decides
+ * first because browsers report unreliable MIME types for Markdown, code,
+ * and OOXML files; the declared MIME type is the fallback for extensionless
+ * names. Returns null when neither identifies a supported type.
+ */
+export declare const resolveDocumentFileType: (fileName: string, mimeType: string) => DocumentFileType | null;
+/** Validates a stored document metadata segment map. */
+export declare const readDocumentSegments: (metadata: Record<string, unknown> | undefined) => DocumentSegment[];
+/**
+ * Human-readable location of a chunk inside its source, chosen as the
+ * segment with the greatest overlap of the chunk's character range.
+ * Offsets are approximate (chunking trims whitespace), so overlap rather
+ * than containment decides.
+ */
+export declare const resolveSegmentLabel: (segments: readonly DocumentSegment[], startChar: number, endChar: number) => string | undefined;
+export interface PdfExtractionApi {
+    getDocument(options: {
+        data: Uint8Array;
+    }): {
+        promise: Promise<{
+            numPages: number;
+            getPage(pageNumber: number): Promise<{
+                getTextContent(): Promise<{
+                    items: unknown[];
+                }>;
+            }>;
+        }>;
+    };
+}
+export interface DocumentExtractionOptions {
+    signal?: AbortSignal;
+    /** Lazily loaded pdfjs module; required only for PDF extraction. */
+    pdfLib?: PdfExtractionApi;
+}
+export declare const extractDocumentContentByType: (buffer: Buffer, fileType: DocumentFileType, options?: DocumentExtractionOptions) => Promise<ExtractedDocumentContent>;
+//# sourceMappingURL=documentExtraction.d.ts.map

package/backend/dist/utils/documentExtraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentExtraction.d.ts","sourceRoot":"","sources":["../../src/utils/documentExtraction.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAI1D;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AA0GD,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAE1D,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAEzD,CAAC;AASH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,aACxB,MAAM,YACN,MAAM,KACf,gBAAgB,GAAG,IAerB,CAAC;AAIF,wDAAwD;AACxD,eAAO,MAAM,oBAAoB,aACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAC5C,eAAe,EA0BjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,aACpB,SAAS,eAAe,EAAE,aACzB,MAAM,WACR,MAAM,KACd,MAAM,GAAG,SAqBX,CAAC;AAsSF,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,GAAG;QAC1C,OAAO,EAAE,OAAO,CAAC;YACf,QAAQ,EAAE,MAAM,CAAC;YACjB,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;gBACnC,cAAc,IAAI,OAAO,CAAC;oBAAE,KAAK,EAAE,OAAO,EAAE,CAAA;iBAAE,CAAC,CAAC;aACjD,CAAC,CAAC;SACJ,CAAC,CAAC;KACJ,CAAC;CACH;AAgDD,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oEAAoE;IACpE,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,eAAO,MAAM,4BAA4B,WAC/B,MAAM,YACJ,gBAAgB,YACjB,yBAAyB,KACjC,OAAO,CAAC,wBAAwB,CA4BlC,CAAC"}