agentfootprint 8.9.0 → 8.10.0

package/dist/rag/splitters/byHeading.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.byHeading = void 0;
+const constants_js_1 = require("./constants.js");
+const shared_js_1 = require("./shared.js");
+/** ATX headings only (`# Title`). Setext (`Title\n=====`) is rare in docs corpora. */
+const HEADING = /^(#{1,6})[ \t]+(.+?)[ \t]*$/gm;
+function byHeading(options = {}) {
+    const maxChars = options.maxChars ?? constants_js_1.DEFAULT_MAX_CHARS;
+    const overlapChars = options.overlapChars ?? constants_js_1.DEFAULT_OVERLAP_CHARS;
+    const maxLevel = options.maxLevel ?? 6;
+    return {
+        name: 'byHeading',
+        split(doc) {
+            const text = doc.text;
+            // Where each section starts, and what it is called.
+            const starts = [];
+            HEADING.lastIndex = 0;
+            let match;
+            while ((match = HEADING.exec(text)) !== null) {
+                if ((match[1] ?? '').length > maxLevel)
+                    continue;
+                starts.push({ offset: match.index, heading: match[2] });
+            }
+            // A document with no headings at all is a paragraph document; say so by
+            // doing the paragraph thing rather than returning one giant chunk.
+            if (starts.length === 0) {
+                const packed = (0, shared_js_1.packSpans)((0, shared_js_1.paragraphSpans)(text), maxChars);
+                const cut = packed.flatMap((s) => s.end - s.start > maxChars ? (0, shared_js_1.hardCut)(s, maxChars, overlapChars) : [s]);
+                return (0, shared_js_1.toPieces)(doc, (0, shared_js_1.applyOverlap)((0, shared_js_1.foldRunts)(cut), overlapChars));
+            }
+            const sections = [];
+            // Preamble before the first heading — its own section, unnamed.
+            const firstStart = starts[0]?.offset ?? 0;
+            if (firstStart > 0)
+                sections.push({ start: 0, end: firstStart });
+            for (let i = 0; i < starts.length; i++) {
+                const start = starts[i]?.offset ?? 0;
+                const end = starts[i + 1]?.offset ?? text.length;
+                const heading = starts[i]?.heading;
+                sections.push({ start, end, ...(heading !== undefined && { heading }) });
+            }
+            // Sections that fit stay whole; the rest are packed by paragraph WITHIN
+            // the section, so a boundary never merges two headings' content.
+            const spans = [];
+            for (const section of sections) {
+                if (section.end - section.start <= maxChars) {
+                    spans.push(section);
+                    continue;
+                }
+                const inner = (0, shared_js_1.paragraphSpans)(text.slice(section.start, section.end)).map((s) => ({
+                    start: section.start + s.start,
+                    end: section.start + s.end,
+                    ...(section.heading !== undefined && { heading: section.heading }),
+                }));
+                for (const packedSpan of (0, shared_js_1.packSpans)(inner, maxChars)) {
+                    if (packedSpan.end - packedSpan.start > maxChars) {
+                        spans.push(...(0, shared_js_1.hardCut)(packedSpan, maxChars, overlapChars));
+                    }
+                    else {
+                        spans.push(packedSpan);
+                    }
+                }
+            }
+            return (0, shared_js_1.toPieces)(doc, (0, shared_js_1.applyOverlap)((0, shared_js_1.foldRunts)(spans), overlapChars));
+        },
+    };
+}
+exports.byHeading = byHeading;
+//# sourceMappingURL=byHeading.js.map

package/dist/rag/splitters/byHeading.js.map

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

package/dist/rag/splitters/byParagraph.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.byParagraph = void 0;
+const constants_js_1 = require("./constants.js");
+const shared_js_1 = require("./shared.js");
+function byParagraph(options = {}) {
+    const maxChars = options.maxChars ?? constants_js_1.DEFAULT_MAX_CHARS;
+    const overlapChars = options.overlapChars ?? constants_js_1.DEFAULT_OVERLAP_CHARS;
+    return {
+        name: 'byParagraph',
+        split(doc) {
+            const paragraphs = (0, shared_js_1.paragraphSpans)(doc.text);
+            const packed = (0, shared_js_1.packSpans)(paragraphs, maxChars);
+            const cut = packed.flatMap((span) => span.end - span.start > maxChars ? (0, shared_js_1.hardCut)(span, maxChars, overlapChars) : [span]);
+            return (0, shared_js_1.toPieces)(doc, (0, shared_js_1.applyOverlap)((0, shared_js_1.foldRunts)(cut), overlapChars));
+        },
+    };
+}
+exports.byParagraph = byParagraph;
+//# sourceMappingURL=byParagraph.js.map

package/dist/rag/splitters/byParagraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"byParagraph.js","sourceRoot":"","sources":["../../../src/rag/splitters/byParagraph.ts"],"names":[],"mappings":";;;AAiBA,iDAA0E;AAC1E,2CAAoG;AASpG,SAAgB,WAAW,CAAC,UAA8B,EAAE;IAC1D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,gCAAiB,CAAC;IACvD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,oCAAqB,CAAC;IAEnE,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,KAAK,CAAC,GAAmB;YACvB,MAAM,UAAU,GAAG,IAAA,0BAAc,EAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC5C,MAAM,MAAM,GAAG,IAAA,qBAAS,EAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YAC/C,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAClC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAA,mBAAO,EAAC,IAAI,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAClF,CAAC;YACF,OAAO,IAAA,oBAAQ,EAAC,GAAG,EAAE,IAAA,wBAAY,EAAC,IAAA,qBAAS,EAAC,GAAG,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;QACnE,CAAC;KACF,CAAC;AACJ,CAAC;AAfD,kCAeC"}

package/dist/rag/splitters/constants.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * The two numbers every splitter defaults to, in one place so they cannot
+ * drift apart between strategies.
+ *
+ * See `splitters/index.ts` for the measurement they come from: `localEmbedder`
+ * truncates at 512 wordpiece tokens (~1,800–2,000 characters), silently, and
+ * 1,000 characters is ~250 tokens — comfortably inside it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_CHUNK_CHARS = exports.DEFAULT_OVERLAP_CHARS = exports.DEFAULT_MAX_CHARS = void 0;
+/** Target chunk size in characters. ~250 wordpiece tokens of English. */
+exports.DEFAULT_MAX_CHARS = 1000;
+/** Overlap between adjacent chunks, so a boundary-spanning sentence is whole somewhere. */
+exports.DEFAULT_OVERLAP_CHARS = 150;
+/**
+ * Below this, a trailing fragment is folded back into the previous chunk
+ * rather than shipped on its own. A 12-character chunk consisting of one
+ * heading and no body embeds to noise and takes a top-K slot from a real
+ * passage.
+ */
+exports.MIN_CHUNK_CHARS = 50;
+//# sourceMappingURL=constants.js.map

package/dist/rag/splitters/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/rag/splitters/constants.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,yEAAyE;AAC5D,QAAA,iBAAiB,GAAG,IAAI,CAAC;AAEtC,2FAA2F;AAC9E,QAAA,qBAAqB,GAAG,GAAG,CAAC;AAEzC;;;;;GAKG;AACU,QAAA,eAAe,GAAG,EAAE,CAAC"}

package/dist/rag/splitters/fixedWithOverlap.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fixedWithOverlap = void 0;
+const constants_js_1 = require("./constants.js");
+const shared_js_1 = require("./shared.js");
+function fixedWithOverlap(options = {}) {
+    const chars = options.chars ?? constants_js_1.DEFAULT_MAX_CHARS;
+    const overlapChars = options.overlapChars ?? constants_js_1.DEFAULT_OVERLAP_CHARS;
+    const wordWindow = options.wordWindow ?? 40;
+    return {
+        name: 'fixedWithOverlap',
+        split(doc) {
+            const text = doc.text;
+            const spans = [];
+            let start = 0;
+            while (start < text.length) {
+                let end = Math.min(text.length, start + chars);
+                // Nudge back to whitespace, but never past the window and never so far
+                // that the chunk collapses.
+                if (end < text.length && wordWindow > 0) {
+                    const floor = Math.max(start + 1, end - wordWindow);
+                    let candidate = end;
+                    while (candidate > floor && !/\s/.test(text[candidate] ?? ''))
+                        candidate -= 1;
+                    if (candidate > floor)
+                        end = candidate;
+                }
+                spans.push({ start, end });
+                if (end >= text.length)
+                    break;
+                start = end;
+            }
+            return (0, shared_js_1.toPieces)(doc, (0, shared_js_1.applyOverlap)((0, shared_js_1.foldRunts)(spans), overlapChars));
+        },
+    };
+}
+exports.fixedWithOverlap = fixedWithOverlap;
+//# sourceMappingURL=fixedWithOverlap.js.map

package/dist/rag/splitters/fixedWithOverlap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixedWithOverlap.js","sourceRoot":"","sources":["../../../src/rag/splitters/fixedWithOverlap.ts"],"names":[],"mappings":";;;AAmBA,iDAA0E;AAC1E,2CAA2E;AAc3E,SAAgB,gBAAgB,CAAC,UAAmC,EAAE;IACpE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,gCAAiB,CAAC;IACjD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,oCAAqB,CAAC;IACnE,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;IAE5C,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,KAAK,CAAC,GAAmB;YACvB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;YACtB,MAAM,KAAK,GAAW,EAAE,CAAC;YACzB,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,OAAO,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC3B,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;gBAC/C,uEAAuE;gBACvE,4BAA4B;gBAC5B,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;oBACxC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,GAAG,GAAG,UAAU,CAAC,CAAC;oBACpD,IAAI,SAAS,GAAG,GAAG,CAAC;oBACpB,OAAO,SAAS,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;wBAAE,SAAS,IAAI,CAAC,CAAC;oBAC9E,IAAI,SAAS,GAAG,KAAK;wBAAE,GAAG,GAAG,SAAS,CAAC;gBACzC,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC3B,IAAI,GAAG,IAAI,IAAI,CAAC,MAAM;oBAAE,MAAM;gBAC9B,KAAK,GAAG,GAAG,CAAC;YACd,CAAC;YACD,OAAO,IAAA,oBAAQ,EAAC,GAAG,EAAE,IAAA,wBAAY,EAAC,IAAA,qBAAS,EAAC,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;QACrE,CAAC;KACF,CAAC;AACJ,CAAC;AA5BD,4CA4BC"}

package/dist/rag/splitters/index.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OVERLAP_CHARS = exports.DEFAULT_MAX_CHARS = exports.wholeDocument = exports.fixedWithOverlap = exports.byHeading = exports.byParagraph = void 0;
+/**
+ * rag/splitters — where a document gets cut, and why there.
+ *
+ * Pattern: Strategy family (factory functions), the same shape as the window
+ *          and retrieval families. Not a `{ kind }` union: a splitter you write
+ *          yourself is the same shape as these, unused ones stay out of a
+ *          bundle, and adding one needs no switch edited anywhere.
+ * Role:    rag/ layer.
+ * Emits:   N/A.
+ *
+ * ── The defaults, and the measurement behind them ───────────────────────────
+ *
+ * `maxChars: 1000`, `overlapChars: 150`. Those numbers are chosen by
+ * CONSTRAINT, not by fashion, and the constraint is measurable:
+ *
+ * **`localEmbedder`'s default model silently truncates at 512 wordpiece
+ * tokens.** Measured directly — embed a long text, embed the same text with an
+ * unrelated tail appended, and compare. At 508 base tokens the tail still
+ * moves the vector (cosine 0.9965). At 596 it does not (cosine 0.999999): the
+ * tail was discarded and nothing said so. 512 wordpiece tokens is roughly
+ * 1,800–2,000 characters of English.
+ *
+ * A chunk of 1,000 characters is about 250 tokens. That sits comfortably
+ * inside that cliff, inside the 256-token length the sentence-transformer
+ * family was actually trained at, and trivially inside `openaiEmbedder`'s
+ * 8,191. Raise it and you approach a limit whose failure mode is silence —
+ * half your chunk embedded, full score reported.
+ *
+ * The 150-character overlap (15%) exists so a sentence spanning a boundary is
+ * whole in one of the two neighbours. It is the smallest overlap that reliably
+ * does that for English prose; there is nothing deeper claimed for it.
+ *
+ * ── Which one to use ────────────────────────────────────────────────────────
+ *
+ * | splitter | cuts on | use when |
+ * |---|---|---|
+ * | `byHeading()` | Markdown `#` lines | the document declares its own sections — **not a heuristic** |
+ * | `byParagraph()` | blank lines | prose with no headings |
+ * | `fixedWithOverlap()` | character count | text with no structure at all (transcripts, OCR) |
+ * | `wholeDocument()` | nothing | short documents that are already one idea |
+ *
+ * `byHeading` is the only one that is not guessing. The author already marked
+ * where the sections are; the others are inferring boundaries from typography.
+ * That is why it is the default for Markdown.
+ */
+var byParagraph_js_1 = require("./byParagraph.js");
+Object.defineProperty(exports, "byParagraph", { enumerable: true, get: function () { return byParagraph_js_1.byParagraph; } });
+var byHeading_js_1 = require("./byHeading.js");
+Object.defineProperty(exports, "byHeading", { enumerable: true, get: function () { return byHeading_js_1.byHeading; } });
+var fixedWithOverlap_js_1 = require("./fixedWithOverlap.js");
+Object.defineProperty(exports, "fixedWithOverlap", { enumerable: true, get: function () { return fixedWithOverlap_js_1.fixedWithOverlap; } });
+var wholeDocument_js_1 = require("./wholeDocument.js");
+Object.defineProperty(exports, "wholeDocument", { enumerable: true, get: function () { return wholeDocument_js_1.wholeDocument; } });
+var constants_js_1 = require("./constants.js");
+Object.defineProperty(exports, "DEFAULT_MAX_CHARS", { enumerable: true, get: function () { return constants_js_1.DEFAULT_MAX_CHARS; } });
+Object.defineProperty(exports, "DEFAULT_OVERLAP_CHARS", { enumerable: true, get: function () { return constants_js_1.DEFAULT_OVERLAP_CHARS; } });
+//# sourceMappingURL=index.js.map

package/dist/rag/splitters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rag/splitters/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,mDAAwE;AAA/D,6GAAA,WAAW,OAAA;AACpB,+CAAkE;AAAzD,yGAAA,SAAS,OAAA;AAClB,6DAAuF;AAA9E,uHAAA,gBAAgB,OAAA;AACzB,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AACtB,+CAA0E;AAAjE,iHAAA,iBAAiB,OAAA;AAAE,qHAAA,qBAAqB,OAAA"}

package/dist/rag/splitters/shared.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paragraphSpans = exports.hardCut = exports.toPieces = exports.foldRunts = exports.applyOverlap = exports.packSpans = exports.trimSpan = exports.pageLocator = void 0;
+const constants_js_1 = require("./constants.js");
+/**
+ * Which page an offset falls on, 1-based, or `undefined` when the document is
+ * not paginated.
+ *
+ * Pages were joined with `'\n\n'` by the loader, so the boundaries are
+ * reconstructible exactly. A chunk that straddles a page break is attributed
+ * to the page it STARTS on — one number, the one you would turn to first.
+ */
+function pageLocator(doc) {
+    const pages = doc.pages;
+    if (!pages || pages.length === 0)
+        return () => undefined;
+    const bounds = [];
+    let cursor = 0;
+    for (const page of pages) {
+        bounds.push(cursor);
+        cursor += page.length + 2; // the '\n\n' the loader joined with
+    }
+    return (offset) => {
+        let page = 1;
+        for (let i = 0; i < bounds.length; i++) {
+            if (offset >= (bounds[i] ?? 0))
+                page = i + 1;
+            else
+                break;
+        }
+        return page;
+    };
+}
+exports.pageLocator = pageLocator;
+/**
+ * Trim a span inward past leading/trailing whitespace, keeping the offsets
+ * honest.
+ *
+ * The naive version — `slice().trim()` — produces text that no longer matches
+ * its own offsets. This moves the offsets instead, so the invariant holds.
+ * Returns `undefined` when the span is entirely whitespace.
+ */
+function trimSpan(text, span) {
+    let start = span.start;
+    let end = span.end;
+    while (start < end && /\s/.test(text[start] ?? ''))
+        start += 1;
+    while (end > start && /\s/.test(text[end - 1] ?? ''))
+        end -= 1;
+    if (start >= end)
+        return undefined;
+    return {
+        start,
+        end,
+        ...(span.heading !== undefined && { heading: span.heading }),
+        ...(span.contentStart !== undefined && { contentStart: span.contentStart }),
+    };
+}
+exports.trimSpan = trimSpan;
+/**
+ * Pack consecutive units (paragraphs, lines) into spans of at most `maxChars`,
+ * then apply `overlapChars` of backward overlap.
+ *
+ * Units are never split by this function — a single unit longer than `maxChars`
+ * becomes its own oversized span, and the caller decides whether to hard-cut
+ * it. That separation matters: a 4,000-character paragraph is a real thing in
+ * real documents, and silently slicing it mid-word is a different decision from
+ * packing.
+ */
+function packSpans(units, maxChars) {
+    const out = [];
+    let current;
+    for (const unit of units) {
+        if (current === undefined) {
+            current = unit;
+            continue;
+        }
+        // Same heading, and the merged span still fits.
+        const fits = unit.end - current.start <= maxChars;
+        const sameSection = current.heading === unit.heading;
+        if (fits && sameSection) {
+            current = {
+                start: current.start,
+                end: unit.end,
+                ...(current.heading !== undefined && { heading: current.heading }),
+            };
+            continue;
+        }
+        out.push(current);
+        current = unit;
+    }
+    if (current !== undefined)
+        out.push(current);
+    return out;
+}
+exports.packSpans = packSpans;
+/**
+ * Extend each span backward by `overlapChars`, without crossing the previous
+ * span's start.
+ *
+ * Backward rather than forward so a chunk always ENDS on the boundary its
+ * strategy chose — a heading section that ends mid-sentence because of overlap
+ * would be a section that lies about where it ends.
+ */
+function applyOverlap(spans, overlapChars) {
+    if (overlapChars <= 0)
+        return [...spans];
+    return spans.map((span, i) => {
+        if (i === 0)
+            return span;
+        const floor = spans[i - 1]?.start ?? 0;
+        const start = Math.max(floor, span.start - overlapChars);
+        // Remember where the chunk's own content starts, so the page it is
+        // attributed to is the page it is ABOUT, not the page its run-up borrowed
+        // from.
+        return start === span.start ? span : { ...span, start, contentStart: span.start };
+    });
+}
+exports.applyOverlap = applyOverlap;
+/**
+ * Fold a too-small span back into its predecessor.
+ *
+ * A fragment of a few characters — a stray heading, a signature line — embeds
+ * to noise and then competes for a top-K slot with real passages.
+ *
+ * **It never folds across a heading boundary.** A merged chunk carries the
+ * FIRST span's heading, so folding a short section into the one before it
+ * would produce a chunk labelled `heading="Alpha"` whose text is Beta's — a
+ * citation that names the wrong section, which is worse than a small chunk.
+ * Two spans merge only when they are already the same section.
+ */
+function foldRunts(spans, minChars = constants_js_1.MIN_CHUNK_CHARS) {
+    const out = [];
+    for (const span of spans) {
+        const previous = out[out.length - 1];
+        const sameSection = previous !== undefined && previous.heading === span.heading;
+        if (previous !== undefined && sameSection && span.end - span.start < minChars) {
+            out[out.length - 1] = {
+                start: previous.start,
+                end: span.end,
+                ...(previous.heading !== undefined && { heading: previous.heading }),
+            };
+            continue;
+        }
+        out.push(span);
+    }
+    return out;
+}
+exports.foldRunts = foldRunts;
+/** Turn spans into pieces, slicing the text so the invariant holds by construction. */
+function toPieces(doc, spans) {
+    const pageAt = pageLocator(doc);
+    const pieces = [];
+    for (const span of spans) {
+        const trimmed = trimSpan(doc.text, span);
+        if (trimmed === undefined)
+            continue;
+        // See `Span.contentStart`: the page is the one this chunk is about.
+        const page = pageAt(span.contentStart ?? trimmed.start);
+        pieces.push({
+            // Sliced, never concatenated. This is the invariant.
+            text: doc.text.slice(trimmed.start, trimmed.end),
+            charStart: trimmed.start,
+            charEnd: trimmed.end,
+            ...(trimmed.heading !== undefined && { heading: trimmed.heading }),
+            ...(page !== undefined && { page }),
+        });
+    }
+    return pieces;
+}
+exports.toPieces = toPieces;
+/** Hard-cut a span that no packing could fit, at `maxChars` with overlap. */
+function hardCut(span, maxChars, overlapChars) {
+    const out = [];
+    const stride = Math.max(1, maxChars - overlapChars);
+    for (let start = span.start; start < span.end; start += stride) {
+        const end = Math.min(span.end, start + maxChars);
+        out.push({ start, end, ...(span.heading !== undefined && { heading: span.heading }) });
+        if (end >= span.end)
+            break;
+    }
+    return out;
+}
+exports.hardCut = hardCut;
+/** Split into paragraph spans on blank lines, keeping offsets. */
+function paragraphSpans(text) {
+    const spans = [];
+    const separator = /\n[ \t]*\n/g;
+    let cursor = 0;
+    let match;
+    while ((match = separator.exec(text)) !== null) {
+        spans.push({ start: cursor, end: match.index });
+        cursor = match.index + match[0].length;
+    }
+    spans.push({ start: cursor, end: text.length });
+    return spans.filter((s) => s.end > s.start);
+}
+exports.paragraphSpans = paragraphSpans;
+//# sourceMappingURL=shared.js.map

package/dist/rag/splitters/shared.js.map

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

package/dist/rag/splitters/wholeDocument.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wholeDocument = void 0;
+const shared_js_1 = require("./shared.js");
+function wholeDocument() {
+    return {
+        name: 'wholeDocument',
+        split(doc) {
+            return (0, shared_js_1.toPieces)(doc, [{ start: 0, end: doc.text.length }]);
+        },
+    };
+}
+exports.wholeDocument = wholeDocument;
+//# sourceMappingURL=wholeDocument.js.map

package/dist/rag/splitters/wholeDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wholeDocument.js","sourceRoot":"","sources":["../../../src/rag/splitters/wholeDocument.ts"],"names":[],"mappings":";;;AAeA,2CAAuC;AAEvC,SAAgB,aAAa;IAC3B,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,KAAK,CAAC,GAAmB;YACvB,OAAO,IAAA,oBAAQ,EAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC7D,CAAC;KACF,CAAC;AACJ,CAAC;AAPD,sCAOC"}

package/dist/rag/types.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * rag/types — the ports and value objects between a folder of documents and
+ * an answering agent.
+ *
+ * Pattern: Ports (DocumentLoader, Splitter) + value objects (LoadedDocument,
+ *          Chunk, IndexReport).
+ * Role:    rag/ layer. The law this folder exists to keep is stated once,
+ *          here, because everything downstream implements a piece of it:
+ *          **a chunk must be able to say where it came from.** Not "which
+ *          document, roughly" — which document, which characters of it, which
+ *          page, under which heading. A passage the agent read and cannot
+ *          locate is a passage nobody can check.
+ * Emits:   N/A (types only).
+ *
+ * That is why `Chunk` carries offsets rather than only text, why `LoadedDocument`
+ * keeps per-page text rather than one flattened string, and why every loader
+ * is required to preserve positions rather than normalise them away.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/rag/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/rag/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/types/doors/rag.d.ts

@@ -0,0 +1,50 @@
+/**
+ * agentfootprint/rag — turning a folder of documents into something an agent
+ * can retrieve from.
+ *
+ * Loaders (text, Markdown, HTML, PDF), splitters, and the indexing chart that
+ * runs them: everything between "I have some documents" and "the vectors are
+ * in a store".
+ *
+ * ── Why this is its own door ────────────────────────────────────────────────
+ * Index time is a different PROCESS from run time. It happens at boot, on a
+ * cron, or from a CLI; it touches the filesystem; and for PDFs it reaches for
+ * an optional peer dependency. None of that belongs in the bundle of an agent
+ * that only wants to answer a question — a browser or edge runtime importing
+ * `agentfootprint` should never resolve `node:fs`. A door is the unit at which
+ * a bundler can cut, and this is the cut.
+ *
+ * ── `defineRAG` is NOT here, deliberately ───────────────────────────────────
+ * The retriever stays on the MAIN barrel, with `indexDocuments`, because it is
+ * run-time wiring: it is registered on an agent, it runs on every turn, and it
+ * belongs beside `defineTool` and the rest of the wiring surface. This door is
+ * the other half of the story — the half that runs once, before any agent
+ * exists.
+ *
+ *   import { defineRAG, indexDocuments } from 'agentfootprint';        // wiring
+ *   import { sqliteVectorStore } from 'agentfootprint/memory';         // where it lives
+ *   import { indexFolder, byHeading } from 'agentfootprint/rag';       // building it
+ *
+ * ── Deferred, with destinations named ───────────────────────────────────────
+ * **Re-ranking and MMR** are retrieval-side concerns and belong behind
+ * `RetrievalStrategy` (`agentfootprint/memory`), not here — a re-ranker is a
+ * different rule for choosing among candidates, not a different way of
+ * building an index. **File watching** is deliberately absent: `indexCorpus`
+ * is an explicit call because magic that re-indexes behind you is magic that
+ * re-bills you. Run it at boot, from a cron, or from the CLI.
+ *
+ * @example
+ * ```ts
+ * import { indexFolder } from 'agentfootprint/rag';
+ * import { sqliteVectorStore } from 'agentfootprint/memory';
+ * import { staticEmbedder } from 'agentfootprint/providers';
+ *
+ * const report = await indexFolder('./docs', {
+ *   to: sqliteVectorStore({ file: './corpus.db' }),
+ *   embedder: staticEmbedder(),
+ * });
+ * // { discovered: 3, loaded: 3, chunks: 14, embedded: 14, skipped: 0, removed: 0, … }
+ * ```
+ */
+export * from '../rag/index.js';
+//# sourceMappingURL=rag.d.ts.map

package/dist/types/doors/rag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag.d.ts","sourceRoot":"","sources":["../../../src/doors/rag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,cAAc,iBAAiB,CAAC"}

package/dist/types/rag/hash.d.ts

@@ -0,0 +1,3 @@
+/** Hex sha-256 of the bytes or text given. */
+export declare function sha256(input: Uint8Array | string): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/types/rag/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/rag/hash.ts"],"names":[],"mappings":"AAcA,8CAA8C;AAC9C,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAMzD"}

package/dist/types/rag/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * rag/ — a folder of documents becomes an answering agent.
+ *
+ * @see ./types.ts          the ports and the value objects
+ * @see ./loadDocuments.ts  step 1 — bytes to text
+ * @see ./splitDocuments.ts step 2 — text to chunks that know where they came from
+ * @see ./indexCorpus.ts    step 3 — the chart that embeds and stores them
+ */
+export { loadDocuments, type LoadDocumentsOptions, type LoadDocumentsResult, } from './loadDocuments.js';
+export { splitDocuments, type SplitDocumentsOptions } from './splitDocuments.js';
+export { indexCorpus, buildIndexChart, type IndexCorpusConfig } from './indexCorpus.js';
+export { indexFolder, type IndexFolderOptions } from './indexFolder.js';
+export { sha256 } from './hash.js';
+export { DEFAULT_LOADERS, textLoader, markdownLoader, htmlLoader, pdfLoader, mockLoader, MissingPdfSupportError, type PdfLoaderOptions, type MockLoaderOptions, } from './loaders/index.js';
+export { stripTags } from './loaders/html.js';
+export { byParagraph, byHeading, fixedWithOverlap, wholeDocument, DEFAULT_MAX_CHARS, DEFAULT_OVERLAP_CHARS, type ByParagraphOptions, type ByHeadingOptions, type FixedWithOverlapOptions, } from './splitters/index.js';
+export type { Chunk, DocumentInput, DocumentLoader, DocumentSource, FailedDocument, IndexReport, LoadedDocument, LoadedDocumentDraft, Splitter, SplitPiece, TruncatedChunk, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/rag/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,EACL,eAAe,EACf,UAAU,EACV,cAAc,EACd,UAAU,EACV,SAAS,EACT,UAAU,EACV,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EACL,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,KAAK,EACL,aAAa,EACb,cAAc,EACd,cAAc,EACd,cAAc,EACd,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC"}