@framers/agentos 0.1.101 → 0.1.102

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

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview OcrPdfLoader — optional OCR-based PDF loader using Tesseract.js.
+ *
+ * This module provides a factory function {@link createOcrPdfLoader} that
+ * attempts to lazy-load `tesseract.js` at runtime.  When the package is not
+ * installed the factory returns `null` gracefully so callers can treat OCR as
+ * fully opt-in without any hard dependency.
+ *
+ * ### Opting in
+ * ```sh
+ * pnpm add tesseract.js
+ * ```
+ *
+ * Once installed, pass the result of {@link createOcrPdfLoader} to
+ * {@link PdfLoader}'s constructor as the `ocrLoader` argument.
+ *
+ * @module memory/ingestion/OcrPdfLoader
+ */
+import type { IDocumentLoader } from './IDocumentLoader.js';
+/**
+ * Checks whether `tesseract.js` is available in the current environment and,
+ * if so, returns a new {@link OcrPdfLoader} instance; otherwise returns `null`.
+ *
+ * The check is performed by attempting to resolve the package path using
+ * Node's `createRequire`.  This avoids a full async dynamic import at call
+ * time while still being accurate.
+ *
+ * ### Usage
+ * ```ts
+ * import { createOcrPdfLoader } from './OcrPdfLoader.js';
+ * import { PdfLoader } from './PdfLoader.js';
+ *
+ * const ocrLoader = createOcrPdfLoader();
+ * const loader = new PdfLoader(ocrLoader);
+ * ```
+ *
+ * @returns An `OcrPdfLoader` instance when tesseract.js is installed, or
+ *          `null` when it is not.
+ */
+export declare function createOcrPdfLoader(): IDocumentLoader | null;
+//# sourceMappingURL=OcrPdfLoader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"OcrPdfLoader.d.ts","sourceRoot":"","sources":["../../../src/memory/ingestion/OcrPdfLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAgH5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,IAAI,CAY3D"}

package/dist/memory/ingestion/OcrPdfLoader.js

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview OcrPdfLoader — optional OCR-based PDF loader using Tesseract.js.
+ *
+ * This module provides a factory function {@link createOcrPdfLoader} that
+ * attempts to lazy-load `tesseract.js` at runtime.  When the package is not
+ * installed the factory returns `null` gracefully so callers can treat OCR as
+ * fully opt-in without any hard dependency.
+ *
+ * ### Opting in
+ * ```sh
+ * pnpm add tesseract.js
+ * ```
+ *
+ * Once installed, pass the result of {@link createOcrPdfLoader} to
+ * {@link PdfLoader}'s constructor as the `ocrLoader` argument.
+ *
+ * @module memory/ingestion/OcrPdfLoader
+ */
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Extensions this loader handles. */
+const SUPPORTED_EXTENSIONS = ['.pdf'];
+// ---------------------------------------------------------------------------
+// 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();
+}
+// ---------------------------------------------------------------------------
+// OcrPdfLoader (internal class)
+// ---------------------------------------------------------------------------
+/**
+ * Internal loader implementation.  Consumers should use {@link createOcrPdfLoader}
+ * rather than instantiating this class directly, as the factory performs the
+ * availability check and returns `null` when tesseract.js is absent.
+ *
+ * @implements {IDocumentLoader}
+ */
+class OcrPdfLoader {
+    constructor() {
+        /** @inheritdoc */
+        this.supportedExtensions = [...SUPPORTED_EXTENSIONS];
+    }
+    // -------------------------------------------------------------------------
+    // canLoad
+    // -------------------------------------------------------------------------
+    /** @inheritdoc */
+    canLoad(source) {
+        if (Buffer.isBuffer(source)) {
+            // Detect PDF magic bytes: %PDF- at offset 0.
+            return source.length >= 4 &&
+                source[0] === 0x25 && source[1] === 0x50 &&
+                source[2] === 0x44 && source[3] === 0x46;
+        }
+        return SUPPORTED_EXTENSIONS.includes(extOf(source));
+    }
+    // -------------------------------------------------------------------------
+    // load
+    // -------------------------------------------------------------------------
+    /** @inheritdoc */
+    async load(source, _options) {
+        let buffer;
+        let resolvedPath;
+        if (Buffer.isBuffer(source)) {
+            buffer = source;
+        }
+        else {
+            resolvedPath = source;
+            buffer = await fs.readFile(resolvedPath);
+        }
+        // Attempt to dynamically import tesseract.js.  The import is wrapped in
+        // try/catch so a missing package yields a clear message rather than a
+        // cryptic MODULE_NOT_FOUND stack trace.  We use `any` here so that the
+        // optional peer dependency does not require installed type declarations.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let Tesseract;
+        try {
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-expect-error — optional peer dependency; types not guaranteed to be installed
+            Tesseract = await import('tesseract.js');
+        }
+        catch {
+            throw new Error('OcrPdfLoader: tesseract.js is not installed.  ' +
+                'Run `pnpm add tesseract.js` (or the equivalent for your package manager) ' +
+                'to enable OCR-based PDF extraction.');
+        }
+        // Perform OCR on the raw PDF bytes.
+        // Tesseract.js accepts a Buffer, base64 string, Blob, or image URL.
+        // For PDF buffers we pass the raw bytes and let Tesseract handle decoding.
+        const { data: { text }, } = await Tesseract.recognize(buffer, 'eng', {
+            logger: () => { },
+        });
+        const meta = {
+            ...(resolvedPath ? { source: resolvedPath } : {}),
+        };
+        return {
+            content: text,
+            metadata: meta,
+            format: 'pdf',
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Checks whether `tesseract.js` is available in the current environment and,
+ * if so, returns a new {@link OcrPdfLoader} instance; otherwise returns `null`.
+ *
+ * The check is performed by attempting to resolve the package path using
+ * Node's `createRequire`.  This avoids a full async dynamic import at call
+ * time while still being accurate.
+ *
+ * ### Usage
+ * ```ts
+ * import { createOcrPdfLoader } from './OcrPdfLoader.js';
+ * import { PdfLoader } from './PdfLoader.js';
+ *
+ * const ocrLoader = createOcrPdfLoader();
+ * const loader = new PdfLoader(ocrLoader);
+ * ```
+ *
+ * @returns An `OcrPdfLoader` instance when tesseract.js is installed, or
+ *          `null` when it is not.
+ */
+export function createOcrPdfLoader() {
+    try {
+        // createRequire lets us resolve package paths from an ESM context without
+        // actually importing the module.  If resolve throws, the package is absent.
+        const require = createRequire(import.meta.url);
+        require.resolve('tesseract.js');
+        // Package is resolvable — return a loader instance.
+        return new OcrPdfLoader();
+    }
+    catch {
+        // Package not installed — OCR is unavailable.
+        return null;
+    }
+}
+//# sourceMappingURL=OcrPdfLoader.js.map

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

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

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

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview PdfLoader — loads `.pdf` documents using `unpdf`.
+ *
+ * Implements a tiered extraction strategy:
+ * 1. **unpdf** (Tier 1, always available) — pure-JS text extraction via
+ *    `getDocumentProxy` + `extractText`.  Fast and dependency-free.
+ * 2. **OcrPdfLoader** (Tier 2, opt-in) — Tesseract.js OCR, engaged when the
+ *    unpdf extraction produces sparse text (< 50 chars per page on average).
+ * 3. **DoclingLoader** (Tier 3, opt-in) — Python `docling` subprocess, engaged
+ *    when explicitly configured via the `docling` loader option.
+ *
+ * Both fallback loaders are optional and injected via constructor parameters;
+ * callers supply them by calling {@link createOcrPdfLoader} and
+ * {@link createDoclingLoader} and checking for non-null values.
+ *
+ * @module memory/ingestion/PdfLoader
+ */
+import type { IDocumentLoader } from './IDocumentLoader.js';
+import type { LoadOptions, LoadedDocument } from '../facade/types.js';
+/**
+ * Document loader for PDF files.
+ *
+ * ### Extraction tiers
+ * 1. **unpdf** — always used as the primary extraction engine.  Performs
+ *    pure-JS PDF text layer extraction with no native binaries required.
+ * 2. **OcrPdfLoader** (optional) — supplied at construction time and engaged
+ *    automatically when unpdf yields sparse text (< 50 chars per page on
+ *    average), indicating a scanned document.
+ * 3. **DoclingLoader** (optional) — when provided, takes precedence over both
+ *    unpdf and OCR, yielding the highest-fidelity extraction at the cost of
+ *    requiring a Python runtime.
+ *
+ * @implements {IDocumentLoader}
+ *
+ * @example
+ * ```ts
+ * const ocrLoader    = createOcrPdfLoader();   // null if tesseract.js absent
+ * const doclingLoader = createDoclingLoader(); // null if docling absent
+ * const pdfLoader = new PdfLoader(ocrLoader, doclingLoader);
+ * const doc = await pdfLoader.load('/reports/q3.pdf');
+ * ```
+ */
+export declare class PdfLoader implements IDocumentLoader {
+    /** @inheritdoc */
+    readonly supportedExtensions: string[];
+    /**
+     * Optional OCR fallback loader, engaged when primary extraction is sparse.
+     * Pass `null` to disable OCR fallback.
+     */
+    private readonly _ocrLoader;
+    /**
+     * Optional Docling loader that, when present, takes precedence over the
+     * entire unpdf + OCR pipeline.
+     * Pass `null` to disable Docling.
+     */
+    private readonly _doclingLoader;
+    /**
+     * Creates a new PdfLoader.
+     *
+     * @param ocrLoader     - Optional OCR fallback (e.g. from {@link createOcrPdfLoader}).
+     * @param doclingLoader - Optional Docling loader (e.g. from {@link createDoclingLoader}).
+     */
+    constructor(ocrLoader?: IDocumentLoader | null, doclingLoader?: IDocumentLoader | null);
+    /** @inheritdoc */
+    canLoad(source: string | Buffer): boolean;
+    /** @inheritdoc */
+    load(source: string | Buffer, options?: LoadOptions): Promise<LoadedDocument>;
+    /**
+     * Extract text from a PDF buffer using the `unpdf` package.
+     *
+     * Returns the concatenated page text, the page count, and an optional title
+     * string extracted from the PDF metadata dictionary when available.
+     *
+     * @param buffer - Raw PDF bytes.
+     */
+    private _extractWithUnpdf;
+}
+//# sourceMappingURL=PdfLoader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PdfLoader.d.ts","sourceRoot":"","sources":["../../../src/memory/ingestion/PdfLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAoB,MAAM,oBAAoB,CAAC;AA+CxF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,SAAU,YAAW,eAAe;IAC/C,kBAAkB;IAClB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,EAAE,CAA6B;IAEnE;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IAEpD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IAExD;;;;;OAKG;gBAED,SAAS,GAAE,eAAe,GAAG,IAAW,EACxC,aAAa,GAAE,eAAe,GAAG,IAAW;IAU9C,kBAAkB;IAClB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IAazC,kBAAkB;IACZ,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;IA2CnF;;;;;;;OAOG;YACW,iBAAiB;CA+BhC"}

package/dist/memory/ingestion/PdfLoader.js

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview PdfLoader — loads `.pdf` documents using `unpdf`.
+ *
+ * Implements a tiered extraction strategy:
+ * 1. **unpdf** (Tier 1, always available) — pure-JS text extraction via
+ *    `getDocumentProxy` + `extractText`.  Fast and dependency-free.
+ * 2. **OcrPdfLoader** (Tier 2, opt-in) — Tesseract.js OCR, engaged when the
+ *    unpdf extraction produces sparse text (< 50 chars per page on average).
+ * 3. **DoclingLoader** (Tier 3, opt-in) — Python `docling` subprocess, engaged
+ *    when explicitly configured via the `docling` loader option.
+ *
+ * Both fallback loaders are optional and injected via constructor parameters;
+ * callers supply them by calling {@link createOcrPdfLoader} and
+ * {@link createDoclingLoader} and checking for non-null values.
+ *
+ * @module memory/ingestion/PdfLoader
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Extensions handled by this loader, each with a leading dot. */
+const SUPPORTED_EXTENSIONS = ['.pdf'];
+/**
+ * Minimum average character count per page below which the primary extraction
+ * result is considered sparse and a fallback strategy is engaged.
+ */
+const SPARSE_THRESHOLD_CHARS_PER_PAGE = 50;
+// ---------------------------------------------------------------------------
+// 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();
+}
+/**
+ * Determine whether extracted text is considered sparse given the page count.
+ *
+ * Sparse text typically indicates a scanned PDF where textual content was not
+ * embedded during creation and OCR is required.
+ *
+ * @param text      - Full extracted text.
+ * @param pageCount - Number of pages in the document.
+ */
+function isSparse(text, pageCount) {
+    if (pageCount <= 0)
+        return false;
+    const avgCharsPerPage = text.length / pageCount;
+    return avgCharsPerPage < SPARSE_THRESHOLD_CHARS_PER_PAGE;
+}
+// ---------------------------------------------------------------------------
+// PdfLoader
+// ---------------------------------------------------------------------------
+/**
+ * Document loader for PDF files.
+ *
+ * ### Extraction tiers
+ * 1. **unpdf** — always used as the primary extraction engine.  Performs
+ *    pure-JS PDF text layer extraction with no native binaries required.
+ * 2. **OcrPdfLoader** (optional) — supplied at construction time and engaged
+ *    automatically when unpdf yields sparse text (< 50 chars per page on
+ *    average), indicating a scanned document.
+ * 3. **DoclingLoader** (optional) — when provided, takes precedence over both
+ *    unpdf and OCR, yielding the highest-fidelity extraction at the cost of
+ *    requiring a Python runtime.
+ *
+ * @implements {IDocumentLoader}
+ *
+ * @example
+ * ```ts
+ * const ocrLoader    = createOcrPdfLoader();   // null if tesseract.js absent
+ * const doclingLoader = createDoclingLoader(); // null if docling absent
+ * const pdfLoader = new PdfLoader(ocrLoader, doclingLoader);
+ * const doc = await pdfLoader.load('/reports/q3.pdf');
+ * ```
+ */
+export class PdfLoader {
+    /**
+     * Creates a new PdfLoader.
+     *
+     * @param ocrLoader     - Optional OCR fallback (e.g. from {@link createOcrPdfLoader}).
+     * @param doclingLoader - Optional Docling loader (e.g. from {@link createDoclingLoader}).
+     */
+    constructor(ocrLoader = null, doclingLoader = null) {
+        /** @inheritdoc */
+        this.supportedExtensions = [...SUPPORTED_EXTENSIONS];
+        this._ocrLoader = ocrLoader;
+        this._doclingLoader = doclingLoader;
+    }
+    // -------------------------------------------------------------------------
+    // canLoad
+    // -------------------------------------------------------------------------
+    /** @inheritdoc */
+    canLoad(source) {
+        if (Buffer.isBuffer(source)) {
+            // Detect PDF magic bytes: %PDF- at offset 0.
+            return source.length >= 4 && source[0] === 0x25 && source[1] === 0x50 &&
+                source[2] === 0x44 && source[3] === 0x46;
+        }
+        return SUPPORTED_EXTENSIONS.includes(extOf(source));
+    }
+    // -------------------------------------------------------------------------
+    // load
+    // -------------------------------------------------------------------------
+    /** @inheritdoc */
+    async load(source, options) {
+        // Prefer Docling when available — highest fidelity.
+        if (this._doclingLoader !== null) {
+            return this._doclingLoader.load(source, options);
+        }
+        // Read bytes from disk if a path was supplied.
+        let buffer;
+        let resolvedPath;
+        if (Buffer.isBuffer(source)) {
+            buffer = source;
+        }
+        else {
+            resolvedPath = source;
+            buffer = await fs.readFile(resolvedPath);
+        }
+        // Primary extraction via unpdf.
+        const { content, pageCount, title } = await this._extractWithUnpdf(buffer);
+        // If primary extraction is sparse and OCR is available, delegate entirely
+        // to the OCR loader which has access to image-level content.
+        if (isSparse(content, pageCount) && this._ocrLoader !== null) {
+            return this._ocrLoader.load(source, options);
+        }
+        const meta = {
+            pageCount,
+            ...(title ? { title } : {}),
+            ...(resolvedPath ? { source: resolvedPath } : {}),
+        };
+        return {
+            content,
+            metadata: meta,
+            format: 'pdf',
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Private: unpdf extraction
+    // -------------------------------------------------------------------------
+    /**
+     * Extract text from a PDF buffer using the `unpdf` package.
+     *
+     * Returns the concatenated page text, the page count, and an optional title
+     * string extracted from the PDF metadata dictionary when available.
+     *
+     * @param buffer - Raw PDF bytes.
+     */
+    async _extractWithUnpdf(buffer) {
+        // Dynamic import keeps unpdf tree-shakeable and avoids module-resolution
+        // errors in environments that don't bundle the package.
+        const { getDocumentProxy, extractText } = await import('unpdf');
+        // getDocumentProxy accepts a Uint8Array — wrap the Node Buffer.
+        const doc = await getDocumentProxy(new Uint8Array(buffer));
+        // Extract all pages at once.
+        const { text } = await extractText(doc, { mergePages: true });
+        // Attempt to read the Title field from the PDF info dictionary.
+        let title;
+        try {
+            const metadata = await doc.getMetadata();
+            const info = metadata?.info;
+            if (info && typeof info['Title'] === 'string' && info['Title'].trim()) {
+                title = info['Title'].trim();
+            }
+        }
+        catch {
+            // Metadata access is optional — swallow errors silently.
+        }
+        const pageCount = doc.numPages ?? 0;
+        return { content: text, pageCount, title };
+    }
+}
+//# sourceMappingURL=PdfLoader.js.map

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

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

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

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview TextLoader — loads plain-text, CSV/TSV, JSON, and YAML files.
+ *
+ * This is the most general-purpose loader in the AgentOS ingestion pipeline.
+ * It handles six extensions that all share the same fundamental operation:
+ * read raw text and attach lightweight metadata derived from the file content
+ * and extension.
+ *
+ * Supported extensions: `.txt`, `.csv`, `.tsv`, `.json`, `.yaml`, `.yml`
+ *
+ * @module memory/ingestion/TextLoader
+ */
+import type { IDocumentLoader } from './IDocumentLoader.js';
+import type { LoadOptions, LoadedDocument } from '../facade/types.js';
+/**
+ * Loader for plain-text, CSV, TSV, JSON, and YAML files.
+ *
+ * The loader performs minimal transformation:
+ * - **`.json`** — re-serialises with pretty-printing so stored content is
+ *   consistently formatted.
+ * - **`.yaml` / `.yml`** — the `yaml` package is used to parse and re-dump
+ *   for consistent formatting; falls back to raw text on parse error.
+ * - All other extensions — content is returned as-is.
+ *
+ * Metadata includes the approximate `wordCount` and a `format` label derived
+ * from the file extension.
+ *
+ * @implements {IDocumentLoader}
+ *
+ * @example
+ * ```ts
+ * const loader = new TextLoader();
+ * const doc = await loader.load('/data/notes.txt');
+ * console.log(doc.metadata.wordCount); // e.g. 312
+ * ```
+ */
+export declare class TextLoader implements IDocumentLoader {
+    /** @inheritdoc */
+    readonly supportedExtensions: string[];
+    /** @inheritdoc */
+    canLoad(source: string | Buffer): boolean;
+    /** @inheritdoc */
+    load(source: string | Buffer, _options?: LoadOptions): Promise<LoadedDocument>;
+    /**
+     * Normalises raw file content based on the detected extension.
+     *
+     * - JSON files are pretty-printed.
+     * - YAML files are parsed and re-dumped for consistent formatting.
+     * - All other formats are returned unchanged.
+     *
+     * @param raw - Raw UTF-8 string read from the source.
+     * @param ext - Lower-cased extension with leading dot.
+     */
+    private _normalise;
+    /**
+     * Parse and re-serialise YAML content for consistent formatting.
+     *
+     * Uses the `yaml` package that is already a production dependency of the
+     * `@framers/agentos` package.  Falls back to the original raw string on
+     * any parse error so the loader never throws on malformed YAML.
+     *
+     * @param raw - Raw YAML string.
+     */
+    private _prettyYaml;
+}
+//# sourceMappingURL=TextLoader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TextLoader.d.ts","sourceRoot":"","sources":["../../../src/memory/ingestion/TextLoader.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;AAsFxF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,UAAW,YAAW,eAAe;IAChD,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;IAsCpF;;;;;;;;;OASG;IACH,OAAO,CAAC,UAAU;IAelB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;CAQpB"}