@framers/agentos 0.1.101 → 0.1.103

package/dist/memory/ingestion/LoaderRegistry.js

@@ -0,0 +1,229 @@
+/**
+ * @fileoverview LoaderRegistry — extension-to-loader routing table.
+ *
+ * The registry maintains a map of file extensions to {@link IDocumentLoader}
+ * implementations and provides a convenience `loadFile()` method that
+ * auto-detects the format from a file path before delegating to the
+ * appropriate loader.
+ *
+ * On construction the registry pre-registers five built-in loaders:
+ * {@link TextLoader}, {@link MarkdownLoader}, {@link HtmlLoader},
+ * {@link PdfLoader}, and {@link DocxLoader}.  In addition, the optional
+ * {@link OcrPdfLoader} and {@link DoclingLoader} are registered when their
+ * respective factories return non-null values (i.e. when `tesseract.js` and
+ * `python3 -m docling` are available in the environment).
+ *
+ * Additional loaders can be added at runtime via {@link LoaderRegistry.register}.
+ *
+ * @module memory/ingestion/LoaderRegistry
+ */
+import path from 'node:path';
+import { TextLoader } from './TextLoader.js';
+import { MarkdownLoader } from './MarkdownLoader.js';
+import { HtmlLoader } from './HtmlLoader.js';
+import { PdfLoader } from './PdfLoader.js';
+import { DocxLoader } from './DocxLoader.js';
+import { createOcrPdfLoader } from './OcrPdfLoader.js';
+import { createDoclingLoader } from './DoclingLoader.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Derive the normalised extension from an arbitrary string.
+ *
+ * Accepts both bare extensions (`.pdf`, `pdf`) and full file paths
+ * (`/docs/report.pdf`).  Always returns lower-cased with a leading dot, or
+ * an empty string when no extension can be determined.
+ *
+ * @param extensionOrPath - Bare extension or full file path.
+ *
+ * @example
+ * normaliseExt('.PDF')       // → '.pdf'
+ * normaliseExt('file.PDF')   // → '.pdf'
+ * normaliseExt('pdf')        // → '.pdf'
+ * normaliseExt('/notes.md')  // → '.md'
+ */
+function normaliseExt(extensionOrPath) {
+    // If the input looks like a bare extension (with or without dot), normalise
+    // it directly without treating it as a path.  A bare extension contains no
+    // directory separators and at most one dot at position 0.
+    const hasSeparator = extensionOrPath.includes('/') || extensionOrPath.includes('\\');
+    const hasDotInMiddle = extensionOrPath.lastIndexOf('.') > 0;
+    if (!hasSeparator && !hasDotInMiddle) {
+        // Bare extension like 'pdf' or '.pdf'.
+        const stripped = extensionOrPath.startsWith('.')
+            ? extensionOrPath.slice(1)
+            : extensionOrPath;
+        return stripped ? `.${stripped.toLowerCase()}` : '';
+    }
+    return path.extname(extensionOrPath).toLowerCase();
+}
+// ---------------------------------------------------------------------------
+// LoaderRegistry
+// ---------------------------------------------------------------------------
+/**
+ * Central registry mapping file extensions to {@link IDocumentLoader}
+ * implementations.
+ *
+ * ### Built-in loaders (registered automatically)
+ * | Extensions                                         | Loader                |
+ * |----------------------------------------------------|-----------------------|
+ * | `.txt`, `.csv`, `.tsv`, `.json`, `.yaml`, `.yml`  | {@link TextLoader}    |
+ * | `.md`, `.mdx`                                     | {@link MarkdownLoader} |
+ * | `.html`, `.htm`                                   | {@link HtmlLoader}    |
+ * | `.pdf`                                            | {@link PdfLoader}     |
+ * | `.docx`                                           | {@link DocxLoader}    |
+ *
+ * ### Conditional loaders (registered when available)
+ * | Condition                     | Loader                              |
+ * |-------------------------------|-------------------------------------|
+ * | `tesseract.js` installed      | {@link OcrPdfLoader} (overrides PDF) |
+ * | `python3 -m docling` available | {@link DoclingLoader} (overrides PDF + DOCX) |
+ *
+ * ### Registering a custom loader
+ * ```ts
+ * const registry = new LoaderRegistry();
+ * registry.register(new PdfLoader());
+ * const doc = await registry.loadFile('/reports/q3.pdf');
+ * ```
+ *
+ * ### Using loadFile
+ * ```ts
+ * const registry = new LoaderRegistry();
+ * const doc = await registry.loadFile('/notes/meeting.md');
+ * console.log(doc.metadata.title);
+ * ```
+ */
+export class LoaderRegistry {
+    /**
+     * Creates a new registry pre-populated with the built-in loaders.
+     *
+     * Loader registration order determines conflict resolution: later
+     * registrations override earlier ones for the same extension.
+     *
+     * Registration order:
+     * 1. {@link TextLoader}, {@link MarkdownLoader}, {@link HtmlLoader} — core text formats.
+     * 2. {@link PdfLoader} (with injected OCR + Docling loaders) — PDF extraction.
+     * 3. {@link DocxLoader} — DOCX extraction.
+     * 4. Optional: an {@link OcrPdfLoader} override when `tesseract.js` is installed.
+     * 5. Optional: a {@link DoclingLoader} override when Python Docling is available.
+     *    DoclingLoader supports both `.pdf` and `.docx`, so it supersedes both
+     *    PdfLoader and DocxLoader when present.
+     */
+    constructor() {
+        /**
+         * Internal map from lower-cased extension (with dot) to the loader
+         * responsible for that extension.
+         *
+         * When multiple loaders claim the same extension the last one registered
+         * wins (newest-registration-wins semantics), allowing callers to override
+         * built-in loaders.
+         */
+        this._loaders = new Map();
+        // Core text-format loaders.
+        this.register(new TextLoader());
+        this.register(new MarkdownLoader());
+        this.register(new HtmlLoader());
+        // Probe optional loaders before constructing PdfLoader so we can inject
+        // them as fallbacks rather than having two separate registered instances.
+        const ocrLoader = createOcrPdfLoader();
+        const doclingLoader = createDoclingLoader();
+        // PDF loader — passes optional fallbacks into the tier system.
+        this.register(new PdfLoader(ocrLoader, doclingLoader));
+        // DOCX loader.
+        this.register(new DocxLoader());
+        // When Docling is available register it separately so it also overrides
+        // the DOCX extension (Docling supports both .pdf and .docx).
+        if (doclingLoader !== null) {
+            this.register(doclingLoader);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // register
+    // -------------------------------------------------------------------------
+    /**
+     * Register a loader for all extensions it declares.
+     *
+     * If a previously registered loader already handles one of the extension,
+     * it is replaced.  This makes it trivial to swap in a higher-fidelity
+     * implementation for any format.
+     *
+     * @param loader - The loader instance to register.
+     *
+     * @example
+     * ```ts
+     * registry.register(new PdfLoader());
+     * ```
+     */
+    register(loader) {
+        for (const ext of loader.supportedExtensions) {
+            this._loaders.set(ext.toLowerCase(), loader);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // getLoader
+    // -------------------------------------------------------------------------
+    /**
+     * Retrieve the loader registered for `extensionOrPath`.
+     *
+     * Both bare extensions (`.md`, `md`) and full file paths
+     * (`/docs/guide.md`) are accepted.
+     *
+     * @param extensionOrPath - File extension or full path.
+     * @returns The matching {@link IDocumentLoader}, or `undefined` when no
+     *          loader is registered for the detected extension.
+     *
+     * @example
+     * ```ts
+     * const loader = registry.getLoader('.md');
+     * const loader2 = registry.getLoader('README.md');
+     * ```
+     */
+    getLoader(extensionOrPath) {
+        const ext = normaliseExt(extensionOrPath);
+        return this._loaders.get(ext);
+    }
+    // -------------------------------------------------------------------------
+    // getSupportedExtensions
+    // -------------------------------------------------------------------------
+    /**
+     * Return a sorted array of all extensions currently registered.
+     *
+     * Each extension is returned with a leading dot in lower-case, e.g.
+     * `['.csv', '.htm', '.html', '.json', '.md', …]`.
+     *
+     * @returns Sorted array of registered extension strings.
+     */
+    getSupportedExtensions() {
+        return [...this._loaders.keys()].sort();
+    }
+    // -------------------------------------------------------------------------
+    // loadFile
+    // -------------------------------------------------------------------------
+    /**
+     * Convenience method: detect format from `filePath`, find the matching
+     * loader, and delegate to its `load()` method.
+     *
+     * @param filePath - Absolute (or resolvable relative) file path.
+     * @param options  - Optional load hints forwarded to the loader.
+     * @returns A promise resolving to the {@link LoadedDocument}.
+     *
+     * @throws {Error} When no loader is registered for the file's extension.
+     * @throws {Error} When the underlying loader's `load()` throws.
+     *
+     * @example
+     * ```ts
+     * const doc = await registry.loadFile('/notes/architecture.md');
+     * ```
+     */
+    async loadFile(filePath, options) {
+        const loader = this.getLoader(filePath);
+        if (!loader) {
+            const ext = normaliseExt(filePath);
+            throw new Error(`LoaderRegistry: no loader registered for extension "${ext}" (file: "${filePath}"). ` +
+                `Supported extensions: ${this.getSupportedExtensions().join(', ')}.`);
+        }
+        return loader.load(filePath, options);
+    }
+}
+//# sourceMappingURL=LoaderRegistry.js.map

package/dist/memory/ingestion/LoaderRegistry.js.map

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

package/dist/memory/ingestion/MarkdownLoader.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview MarkdownLoader — loads `.md` and `.mdx` documents.
+ *
+ * Parses YAML front-matter using the `gray-matter` library, strips it from
+ * the returned content, and promotes key metadata fields (title, author,
+ * createdAt, etc.) into the {@link DocumentMetadata} shape.
+ *
+ * When no `title` key is present in the front-matter the loader falls back
+ * to extracting the first ATX heading (`# …`) from the document body.
+ *
+ * @module memory/ingestion/MarkdownLoader
+ */
+import type { IDocumentLoader } from './IDocumentLoader.js';
+import type { LoadOptions, LoadedDocument } from '../facade/types.js';
+/**
+ * Document loader for Markdown (`.md`) and MDX (`.mdx`) files.
+ *
+ * ### Front-matter handling
+ * YAML front-matter delimited by `---` is parsed via `gray-matter`.  All
+ * key-value pairs are merged into {@link DocumentMetadata} as-is, with a
+ * handful of well-known keys (`title`, `author`, `createdAt`, `modifiedAt`,
+ * `language`) mapped to the corresponding typed metadata fields.
+ *
+ * ### Title extraction fallback
+ * When the front-matter does **not** contain a `title` field the loader
+ * searches the document body for the first level-1 ATX heading (`# Title`)
+ * and uses that as the title.
+ *
+ * ### Returned content
+ * The `content` field in the returned {@link LoadedDocument} contains the
+ * Markdown body **without** the front-matter block.
+ *
+ * @implements {IDocumentLoader}
+ *
+ * @example
+ * ```ts
+ * const loader = new MarkdownLoader();
+ * const doc = await loader.load('/docs/architecture.md');
+ * console.log(doc.metadata.title); // from front-matter or first # heading
+ * ```
+ */
+export declare class MarkdownLoader implements IDocumentLoader {
+    /** @inheritdoc */
+    readonly supportedExtensions: string[];
+    /** @inheritdoc */
+    canLoad(source: string | Buffer): boolean;
+    /** @inheritdoc */
+    load(source: string | Buffer, _options?: LoadOptions): Promise<LoadedDocument>;
+}
+//# sourceMappingURL=MarkdownLoader.d.ts.map

package/dist/memory/ingestion/MarkdownLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownLoader.d.ts","sourceRoot":"","sources":["../../../src/memory/ingestion/MarkdownLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAoB,MAAM,oBAAoB,CAAC;AAoExF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,cAAe,YAAW,eAAe;IACpD,kBAAkB;IAClB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,EAAE,CAA6B;IAMnE,kBAAkB;IAClB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IAazC,kBAAkB;IACZ,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;CAqDrF"}

package/dist/memory/ingestion/MarkdownLoader.js

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview MarkdownLoader — loads `.md` and `.mdx` documents.
+ *
+ * Parses YAML front-matter using the `gray-matter` library, strips it from
+ * the returned content, and promotes key metadata fields (title, author,
+ * createdAt, etc.) into the {@link DocumentMetadata} shape.
+ *
+ * When no `title` key is present in the front-matter the loader falls back
+ * to extracting the first ATX heading (`# …`) from the document body.
+ *
+ * @module memory/ingestion/MarkdownLoader
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import matter from 'gray-matter';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Extensions handled by this loader, each with a leading dot. */
+const SUPPORTED_EXTENSIONS = ['.md', '.mdx'];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns the lower-cased extension (with dot) of a file path.
+ *
+ * @param filePath - Absolute or relative file path.
+ */
+function extOf(filePath) {
+    return path.extname(filePath).toLowerCase();
+}
+/**
+ * Approximate word count for the body text (excludes front-matter).
+ *
+ * @param text - Stripped Markdown body string.
+ */
+function wordCount(text) {
+    return text.trim() === '' ? 0 : text.trim().split(/\s+/).length;
+}
+/**
+ * Extract the first ATX heading from a Markdown body.
+ *
+ * Matches `# Title` at the beginning of a line (with optional leading
+ * whitespace) and returns the trimmed heading text.  Returns `undefined`
+ * when no heading is found.
+ *
+ * @param body - Markdown body text with front-matter already removed.
+ */
+function extractFirstHeading(body) {
+    // Match ATX headings at level 1 only (`# …`) — the most common title pattern.
+    const match = /^#{1}\s+(.+)/m.exec(body);
+    return match ? match[1].trim() : undefined;
+}
+/**
+ * Coerce a raw front-matter date value (Date object, ISO string, or number)
+ * into an ISO 8601 string, returning `undefined` when conversion is not
+ * possible.
+ *
+ * @param value - Raw value from the parsed front-matter data object.
+ */
+function toIsoString(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === 'string' || typeof value === 'number') {
+        const d = new Date(value);
+        return isNaN(d.getTime()) ? undefined : d.toISOString();
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// MarkdownLoader
+// ---------------------------------------------------------------------------
+/**
+ * Document loader for Markdown (`.md`) and MDX (`.mdx`) files.
+ *
+ * ### Front-matter handling
+ * YAML front-matter delimited by `---` is parsed via `gray-matter`.  All
+ * key-value pairs are merged into {@link DocumentMetadata} as-is, with a
+ * handful of well-known keys (`title`, `author`, `createdAt`, `modifiedAt`,
+ * `language`) mapped to the corresponding typed metadata fields.
+ *
+ * ### Title extraction fallback
+ * When the front-matter does **not** contain a `title` field the loader
+ * searches the document body for the first level-1 ATX heading (`# Title`)
+ * and uses that as the title.
+ *
+ * ### Returned content
+ * The `content` field in the returned {@link LoadedDocument} contains the
+ * Markdown body **without** the front-matter block.
+ *
+ * @implements {IDocumentLoader}
+ *
+ * @example
+ * ```ts
+ * const loader = new MarkdownLoader();
+ * const doc = await loader.load('/docs/architecture.md');
+ * console.log(doc.metadata.title); // from front-matter or first # heading
+ * ```
+ */
+export class MarkdownLoader {
+    constructor() {
+        /** @inheritdoc */
+        this.supportedExtensions = [...SUPPORTED_EXTENSIONS];
+    }
+    // -------------------------------------------------------------------------
+    // canLoad
+    // -------------------------------------------------------------------------
+    /** @inheritdoc */
+    canLoad(source) {
+        if (Buffer.isBuffer(source)) {
+            // Without an extension we tentatively accept Buffers for flexibility;
+            // callers should prefer path-based loading to ensure correct routing.
+            return false;
+        }
+        return SUPPORTED_EXTENSIONS.includes(extOf(source));
+    }
+    // -------------------------------------------------------------------------
+    // load
+    // -------------------------------------------------------------------------
+    /** @inheritdoc */
+    async load(source, _options) {
+        let raw;
+        let resolvedPath;
+        if (Buffer.isBuffer(source)) {
+            raw = source.toString('utf8');
+        }
+        else {
+            resolvedPath = source;
+            const bytes = await fs.readFile(resolvedPath);
+            raw = bytes.toString('utf8');
+        }
+        // ---- Parse front-matter ----
+        const parsed = matter(raw);
+        // `parsed.content` is the body with front-matter stripped.
+        const body = parsed.content;
+        // ---- Build metadata ----
+        const fm = parsed.data;
+        // Attempt to resolve a title from: frontmatter > first heading.
+        const fmTitle = typeof fm['title'] === 'string' ? fm['title'] : undefined;
+        const headingTitle = fmTitle === undefined ? extractFirstHeading(body) : undefined;
+        const title = fmTitle ?? headingTitle;
+        const meta = {
+            // Well-known scalar fields.
+            ...(title !== undefined ? { title } : {}),
+            ...(typeof fm['author'] === 'string' ? { author: fm['author'] } : {}),
+            ...(fm['createdAt'] !== undefined
+                ? { createdAt: toIsoString(fm['createdAt']) }
+                : {}),
+            ...(fm['modifiedAt'] !== undefined
+                ? { modifiedAt: toIsoString(fm['modifiedAt']) }
+                : {}),
+            ...(typeof fm['language'] === 'string' ? { language: fm['language'] } : {}),
+            // Spread all remaining front-matter keys as generic extras.
+            ...fm,
+            // Override title with resolved value (may differ from fm.title when
+            // extracted from heading) and add standard fields.
+            ...(title !== undefined ? { title } : {}),
+            wordCount: wordCount(body),
+            ...(resolvedPath ? { source: resolvedPath } : {}),
+        };
+        return {
+            content: body,
+            metadata: meta,
+            format: 'md',
+        };
+    }
+}
+//# sourceMappingURL=MarkdownLoader.js.map

package/dist/memory/ingestion/MarkdownLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownLoader.js","sourceRoot":"","sources":["../../../src/memory/ingestion/MarkdownLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,aAAa,CAAC;AAIjC,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,kEAAkE;AAClE,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,MAAM,CAAU,CAAC;AAEtD,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;GAIG;AACH,SAAS,KAAK,CAAC,QAAgB;IAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,mBAAmB,CAAC,IAAY;IACvC,8EAA8E;IAC9E,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;IAC7B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC3D,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,cAAc;IAA3B;QACE,kBAAkB;QACT,wBAAmB,GAAa,CAAC,GAAG,oBAAoB,CAAC,CAAC;IA0ErE,CAAC;IAxEC,4EAA4E;IAC5E,UAAU;IACV,4EAA4E;IAE5E,kBAAkB;IAClB,OAAO,CAAC,MAAuB;QAC7B,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,sEAAsE;YACtE,sEAAsE;YACtE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAQ,oBAA0C,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7E,CAAC;IAED,4EAA4E;IAC5E,OAAO;IACP,4EAA4E;IAE5E,kBAAkB;IAClB,KAAK,CAAC,IAAI,CAAC,MAAuB,EAAE,QAAsB;QACxD,IAAI,GAAW,CAAC;QAChB,IAAI,YAAgC,CAAC;QAErC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;aAAM,CAAC;YACN,YAAY,GAAG,MAAM,CAAC;YACtB,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;YAC9C,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC;QAED,+BAA+B;QAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAE3B,2DAA2D;QAC3D,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC;QAE5B,2BAA2B;QAC3B,MAAM,EAAE,GAAG,MAAM,CAAC,IAA+B,CAAC;QAElD,gEAAgE;QAChE,MAAM,OAAO,GACX,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5D,MAAM,YAAY,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACnF,MAAM,KAAK,GAAG,OAAO,IAAI,YAAY,CAAC;QAEtC,MAAM,IAAI,GAAqB;YAC7B,4BAA4B;YAC5B,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,GAAG,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrE,GAAG,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,SAAS;gBAC/B,CAAC,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE;gBAC7C,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,EAAE,CAAC,YAAY,CAAC,KAAK,SAAS;gBAChC,CAAC,CAAC,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE;gBAC/C,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,OAAO,EAAE,CAAC,UAAU,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3E,4DAA4D;YAC5D,GAAG,EAAE;YACL,oEAAoE;YACpE,mDAAmD;YACnD,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC;YAC1B,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClD,CAAC;QAEF,OAAO;YACL,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,IAAI;SACb,CAAC;IACJ,CAAC;CACF"}

package/dist/memory/ingestion/MultimodalAggregator.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview MultimodalAggregator — post-processing stage for images
+ * extracted from documents.
+ *
+ * After loaders such as {@link PdfLoader} and {@link DocxLoader} extract
+ * embedded images as {@link ExtractedImage} objects, `MultimodalAggregator`
+ * enriches them with natural-language captions by optionally calling a
+ * vision-capable LLM function supplied by the application layer.
+ *
+ * The class is intentionally thin: it holds no state beyond the optional
+ * configuration and delegates all vision intelligence to the caller-supplied
+ * `describeImage` function.  This keeps the aggregator testable without any
+ * live LLM dependencies.
+ *
+ * @module memory/ingestion/MultimodalAggregator
+ */
+import type { ExtractedImage } from '../facade/types.js';
+/**
+ * Configuration for {@link MultimodalAggregator}.
+ */
+export interface MultimodalConfig {
+    /**
+     * Async function that accepts a raw image buffer and its MIME type and
+     * returns a natural-language description of the image.
+     *
+     * When this is `undefined` the aggregator passes images through unchanged.
+     *
+     * @param imageBuffer - Raw bytes of the image (PNG, JPEG, WebP, …).
+     * @param mimeType    - MIME type of the image, e.g. `'image/png'`.
+     * @returns A promise resolving to a human-readable description string.
+     *
+     * @example
+     * ```ts
+     * async (buffer, mimeType) => {
+     *   return openaiClient.vision(buffer, mimeType);
+     * }
+     * ```
+     */
+    describeImage?: (imageBuffer: Buffer, mimeType: string) => Promise<string>;
+}
+/**
+ * Adds auto-generated captions to {@link ExtractedImage} objects that lack
+ * one, using a caller-supplied vision LLM function.
+ *
+ * Images are processed in parallel via {@link Promise.allSettled} so a single
+ * failed captioning attempt does not block the rest.  Images whose captioning
+ * fails retain their original (un-captioned) state rather than propagating the
+ * error.
+ *
+ * ### Example — with a vision LLM
+ * ```ts
+ * const aggregator = new MultimodalAggregator({
+ *   describeImage: async (buf, mime) => myVisionLLM.describe(buf, mime),
+ * });
+ *
+ * const captioned = await aggregator.processImages(doc.images ?? []);
+ * ```
+ *
+ * ### Example — passthrough (no LLM configured)
+ * ```ts
+ * const aggregator = new MultimodalAggregator();
+ * const unchanged  = await aggregator.processImages(doc.images ?? []);
+ * ```
+ */
+export declare class MultimodalAggregator {
+    private readonly config?;
+    /**
+     * @param config - Optional configuration.  Omit to use in passthrough mode.
+     */
+    constructor(config?: MultimodalConfig | undefined);
+    /**
+     * Enrich images with captions via the configured vision LLM.
+     *
+     * Only images that have no existing `caption` field are processed.  Images
+     * that already carry a caption are left unchanged to avoid redundant LLM
+     * calls.
+     *
+     * When no `describeImage` function is configured all images are returned
+     * unchanged.
+     *
+     * @param images - Array of {@link ExtractedImage} objects to process.
+     * @returns A promise resolving to the same-length array of
+     *          {@link ExtractedImage} objects, with captions filled in where
+     *          possible.
+     */
+    processImages(images: ExtractedImage[]): Promise<ExtractedImage[]>;
+}
+//# sourceMappingURL=MultimodalAggregator.d.ts.map

package/dist/memory/ingestion/MultimodalAggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MultimodalAggregator.d.ts","sourceRoot":"","sources":["../../../src/memory/ingestion/MultimodalAggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAMzD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5E;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,oBAAoB;IAInB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAHpC;;OAEG;gBAC0B,MAAM,CAAC,EAAE,gBAAgB,YAAA;IAMtD;;;;;;;;;;;;;;OAcG;IACG,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;CAiCzE"}

package/dist/memory/ingestion/MultimodalAggregator.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview MultimodalAggregator — post-processing stage for images
+ * extracted from documents.
+ *
+ * After loaders such as {@link PdfLoader} and {@link DocxLoader} extract
+ * embedded images as {@link ExtractedImage} objects, `MultimodalAggregator`
+ * enriches them with natural-language captions by optionally calling a
+ * vision-capable LLM function supplied by the application layer.
+ *
+ * The class is intentionally thin: it holds no state beyond the optional
+ * configuration and delegates all vision intelligence to the caller-supplied
+ * `describeImage` function.  This keeps the aggregator testable without any
+ * live LLM dependencies.
+ *
+ * @module memory/ingestion/MultimodalAggregator
+ */
+// ---------------------------------------------------------------------------
+// MultimodalAggregator
+// ---------------------------------------------------------------------------
+/**
+ * Adds auto-generated captions to {@link ExtractedImage} objects that lack
+ * one, using a caller-supplied vision LLM function.
+ *
+ * Images are processed in parallel via {@link Promise.allSettled} so a single
+ * failed captioning attempt does not block the rest.  Images whose captioning
+ * fails retain their original (un-captioned) state rather than propagating the
+ * error.
+ *
+ * ### Example — with a vision LLM
+ * ```ts
+ * const aggregator = new MultimodalAggregator({
+ *   describeImage: async (buf, mime) => myVisionLLM.describe(buf, mime),
+ * });
+ *
+ * const captioned = await aggregator.processImages(doc.images ?? []);
+ * ```
+ *
+ * ### Example — passthrough (no LLM configured)
+ * ```ts
+ * const aggregator = new MultimodalAggregator();
+ * const unchanged  = await aggregator.processImages(doc.images ?? []);
+ * ```
+ */
+export class MultimodalAggregator {
+    /**
+     * @param config - Optional configuration.  Omit to use in passthrough mode.
+     */
+    constructor(config) {
+        this.config = config;
+    }
+    // -------------------------------------------------------------------------
+    // processImages
+    // -------------------------------------------------------------------------
+    /**
+     * Enrich images with captions via the configured vision LLM.
+     *
+     * Only images that have no existing `caption` field are processed.  Images
+     * that already carry a caption are left unchanged to avoid redundant LLM
+     * calls.
+     *
+     * When no `describeImage` function is configured all images are returned
+     * unchanged.
+     *
+     * @param images - Array of {@link ExtractedImage} objects to process.
+     * @returns A promise resolving to the same-length array of
+     *          {@link ExtractedImage} objects, with captions filled in where
+     *          possible.
+     */
+    async processImages(images) {
+        // Fast path: no vision function configured — return a shallow copy as-is.
+        if (!this.config?.describeImage) {
+            return images.slice();
+        }
+        const describeImage = this.config.describeImage;
+        // Map each image to a settled promise so failures are isolated.
+        const results = await Promise.allSettled(images.map(async (image) => {
+            // Skip images that already have a caption.
+            if (image.caption !== undefined) {
+                return image;
+            }
+            try {
+                const caption = await describeImage(image.data, image.mimeType);
+                return { ...image, caption };
+            }
+            catch {
+                // Captioning failed — return the original image unchanged.
+                return image;
+            }
+        }));
+        // Extract the fulfilled values (allSettled always fulfils, but we spread
+        // the value for explicitness; rejected branches are unreachable here since
+        // the inner try/catch already handles errors, but typing requires it).
+        return results.map((result, index) => result.status === 'fulfilled' ? result.value : images[index]);
+    }
+}
+//# sourceMappingURL=MultimodalAggregator.js.map

package/dist/memory/ingestion/MultimodalAggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MultimodalAggregator.js","sourceRoot":"","sources":["../../../src/memory/ingestion/MultimodalAggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAgCH,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,oBAAoB;IAC/B;;OAEG;IACH,YAA6B,MAAyB;QAAzB,WAAM,GAAN,MAAM,CAAmB;IAAG,CAAC;IAE1D,4EAA4E;IAC5E,gBAAgB;IAChB,4EAA4E;IAE5E;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,aAAa,CAAC,MAAwB;QAC1C,0EAA0E;QAC1E,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC;YAChC,OAAO,MAAM,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;QAED,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;QAEhD,gEAAgE;QAChE,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACtC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAA2B,EAAE;YAClD,2CAA2C;YAC3C,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBAChC,OAAO,KAAK,CAAC;YACf,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAChE,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,CAAC;YAC/B,CAAC;YAAC,MAAM,CAAC;gBACP,2DAA2D;gBAC3D,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC,CAAC,CACH,CAAC;QAEF,yEAAyE;QACzE,2EAA2E;QAC3E,uEAAuE;QACvE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CACnC,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAC7D,CAAC;IACJ,CAAC;CACF"}