@warlock.js/ai 4.8.2 → 4.9.1

package/esm/rag/chunk/fixed.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"fixed.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/chunk/fixed.ts"],"sourcesContent":["import type { Chunk } from \"../contracts/chunk-options.type\";\n\n/**\n * Fixed-window character splitter.\n *\n * The simplest strategy: slices the text into back-to-back windows of\n * `size` characters, stepping forward by `size - overlap` so adjacent\n * windows share `overlap` characters. Boundary-unaware — it will cut\n * mid-word — but deterministic and dep-free. Spans are exact by\n * construction.\n */\nexport function fixedChunk(text: string, size: number, overlap: number): Chunk[] {\n  if (text.length === 0) {\n    return [];\n  }\n\n  const step = Math.max(1, size - overlap);\n  const chunks: Chunk[] = [];\n  let index = 0;\n\n  for (let cursor = 0; cursor < text.length; cursor += step) {\n    const start = cursor;\n    const end = Math.min(cursor + size, text.length);\n\n    chunks.push({ text: text.slice(start, end), index, span: [start, end] });\n    index += 1;\n\n    if (end >= text.length) {\n      break;\n    }\n  }\n\n  return chunks;\n}\n"],"mappings":";;;;;;;;;;AAWA,SAAgB,WAAW,MAAc,MAAc,SAA0B;CAC/E,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAGV,MAAM,OAAO,KAAK,IAAI,GAAG,OAAO,OAAO;CACvC,MAAM,SAAkB,CAAC;CACzB,IAAI,QAAQ;CAEZ,KAAK,IAAI,SAAS,GAAG,SAAS,KAAK,QAAQ,UAAU,MAAM;EACzD,MAAM,QAAQ;EACd,MAAM,MAAM,KAAK,IAAI,SAAS,MAAM,KAAK,MAAM;EAE/C,OAAO,KAAK;GAAE,MAAM,KAAK,MAAM,OAAO,GAAG;GAAG;GAAO,MAAM,CAAC,OAAO,GAAG;EAAE,CAAC;EACvE,SAAS;EAET,IAAI,OAAO,KAAK,QACd;CAEJ;CAEA,OAAO;AACT"}
+{"version":3,"file":"fixed.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/chunk/fixed.ts"],"sourcesContent":["import type { Chunk } from \"../contracts/chunk-options.type\";\n\n/**\n * Fixed-window character splitter.\n *\n * The simplest strategy: slices the text into back-to-back windows of\n * `size` characters, stepping forward by `size - overlap` so adjacent\n * windows share `overlap` characters. Boundary-unaware — it will cut\n * mid-word — but deterministic and dep-free. Spans are exact by\n * construction.\n */\nexport function fixedChunk(text: string, size: number, overlap: number): Chunk[] {\n  if (text.length === 0) {\n    return [];\n  }\n\n  const step = Math.max(1, size - overlap);\n  const chunks: Chunk[] = [];\n  let index = 0;\n\n  for (let cursor = 0; cursor < text.length; cursor += step) {\n    const start = cursor;\n    const end = Math.min(cursor + size, text.length);\n\n    chunks.push({ text: text.slice(start, end), index, span: [start, end] });\n    index += 1;\n\n    if (end >= text.length) {\n      break;\n    }\n  }\n\n  return chunks;\n}\n"],"mappings":";;;;;;;;;;AAWA,SAAgB,WAAW,MAAc,MAAc,SAA0B;CAC/E,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAGV,MAAM,OAAO,KAAK,IAAI,GAAG,OAAO,OAAO;CACvC,MAAM,SAAkB,CAAC;CACzB,IAAI,QAAQ;CAEZ,KAAK,IAAI,SAAS,GAAG,SAAS,KAAK,QAAQ,UAAU,MAAM;EACzD,MAAM,QAAQ;EACd,MAAM,MAAM,KAAK,IAAI,SAAS,MAAM,KAAK,MAAM;EAE/C,OAAO,KAAK;GAAE,MAAM,KAAK,MAAM,OAAO,GAAG;GAAG;GAAO,MAAM,CAAC,OAAO,GAAG;EAAE,CAAC;EACvE,SAAS;EAET,IAAI,OAAO,KAAK,QACd;CAEJ;CAEA,OAAO;AACT"}

package/esm/rag/chunk/markdown.mjs

@@ -1,6 +1,6 @@
 import { DEFAULT_SEPARATORS, recursiveChunk } from "./recursive.mjs";
 
-//#region ../@warlock.js/ai/src/rag/chunk/markdown.ts
+//#region ../ai/src/rag/chunk/markdown.ts
 /** Matches an ATX Markdown heading line (`#` … `######`) at line start. */
 const HEADING_LINE = /^#{1,6}[ \t].*$/gm;
 /**

package/esm/rag/chunk/markdown.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/chunk/markdown.ts"],"sourcesContent":["import type { Chunk } from \"../contracts/chunk-options.type\";\nimport { DEFAULT_SEPARATORS, recursiveChunk } from \"./recursive\";\n\n/** Matches an ATX Markdown heading line (`#` … `######`) at line start. */\nconst HEADING_LINE = /^#{1,6}[ \\t].*$/gm;\n\n/**\n * Markdown heading/section-aware splitter.\n *\n * Splits the document on ATX heading boundaries (`#`…`######`) first so a\n * section's heading stays glued to its body, then applies the recursive\n * character splitter WITHIN each section so any section larger than `size`\n * is broken down further. Sections at or under `size` are emitted whole.\n * Spans are exact relative to the original document.\n */\nexport function markdownChunk(\n  text: string,\n  size: number,\n  overlap: number,\n  separators: string[] = DEFAULT_SEPARATORS,\n): Chunk[] {\n  if (text.length === 0) {\n    return [];\n  }\n\n  const sections = splitSections(text);\n  const chunks: Chunk[] = [];\n  let index = 0;\n\n  for (const section of sections) {\n    const body = text.slice(section.start, section.end);\n\n    if (body.trim().length === 0) {\n      continue;\n    }\n\n    if (body.length <= size) {\n      chunks.push({\n        text: body,\n        index,\n        span: [section.start, section.end],\n      });\n      index += 1;\n\n      continue;\n    }\n\n    // Recurse within the section, then shift the relative spans to\n    // absolute document offsets and renumber sequentially.\n    const inner = recursiveChunk(body, size, overlap, separators);\n\n    for (const piece of inner) {\n      chunks.push({\n        text: piece.text,\n        index,\n        span: [section.start + piece.span[0], section.start + piece.span[1]],\n      });\n      index += 1;\n    }\n  }\n\n  return chunks;\n}\n\n/** A section's absolute `[start, end)` span (heading line + body until next heading). */\ntype SectionSpan = {\n  start: number;\n  end: number;\n};\n\n/**\n * Carve the document into sections, each beginning at a heading line and\n * running until the next heading (the preamble before the first heading is\n * its own section). Spans cover the whole document with no gaps.\n */\nfunction splitSections(text: string): SectionSpan[] {\n  const starts: number[] = [];\n  let match: RegExpExecArray | null;\n\n  HEADING_LINE.lastIndex = 0;\n\n  while ((match = HEADING_LINE.exec(text)) !== null) {\n    starts.push(match.index);\n  }\n\n  // No headings at all — the whole document is one section.\n  if (starts.length === 0) {\n    return [{ start: 0, end: text.length }];\n  }\n\n  const sections: SectionSpan[] = [];\n\n  // Preamble before the first heading, if any.\n  if (starts[0] > 0) {\n    sections.push({ start: 0, end: starts[0] });\n  }\n\n  starts.forEach((start, position) => {\n    const end = position + 1 < starts.length ? starts[position + 1] : text.length;\n\n    sections.push({ start, end });\n  });\n\n  return sections;\n}\n"],"mappings":";;;;AAIA,MAAM,eAAe;;;;;;;;;;AAWrB,SAAgB,cACd,MACA,MACA,SACA,aAAuB,oBACd;CACT,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAGV,MAAM,WAAW,cAAc,IAAI;CACnC,MAAM,SAAkB,CAAC;CACzB,IAAI,QAAQ;CAEZ,KAAK,MAAM,WAAW,UAAU;EAC9B,MAAM,OAAO,KAAK,MAAM,QAAQ,OAAO,QAAQ,GAAG;EAElD,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GACzB;EAGF,IAAI,KAAK,UAAU,MAAM;GACvB,OAAO,KAAK;IACV,MAAM;IACN;IACA,MAAM,CAAC,QAAQ,OAAO,QAAQ,GAAG;GACnC,CAAC;GACD,SAAS;GAET;EACF;EAIA,MAAM,QAAQ,eAAe,MAAM,MAAM,SAAS,UAAU;EAE5D,KAAK,MAAM,SAAS,OAAO;GACzB,OAAO,KAAK;IACV,MAAM,MAAM;IACZ;IACA,MAAM,CAAC,QAAQ,QAAQ,MAAM,KAAK,IAAI,QAAQ,QAAQ,MAAM,KAAK,EAAE;GACrE,CAAC;GACD,SAAS;EACX;CACF;CAEA,OAAO;AACT;;;;;;AAaA,SAAS,cAAc,MAA6B;CAClD,MAAM,SAAmB,CAAC;CAC1B,IAAI;CAEJ,aAAa,YAAY;CAEzB,QAAQ,QAAQ,aAAa,KAAK,IAAI,OAAO,MAC3C,OAAO,KAAK,MAAM,KAAK;CAIzB,IAAI,OAAO,WAAW,GACpB,OAAO,CAAC;EAAE,OAAO;EAAG,KAAK,KAAK;CAAO,CAAC;CAGxC,MAAM,WAA0B,CAAC;CAGjC,IAAI,OAAO,KAAK,GACd,SAAS,KAAK;EAAE,OAAO;EAAG,KAAK,OAAO;CAAG,CAAC;CAG5C,OAAO,SAAS,OAAO,aAAa;EAClC,MAAM,MAAM,WAAW,IAAI,OAAO,SAAS,OAAO,WAAW,KAAK,KAAK;EAEvE,SAAS,KAAK;GAAE;GAAO;EAAI,CAAC;CAC9B,CAAC;CAED,OAAO;AACT"}
+{"version":3,"file":"markdown.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/chunk/markdown.ts"],"sourcesContent":["import type { Chunk } from \"../contracts/chunk-options.type\";\nimport { DEFAULT_SEPARATORS, recursiveChunk } from \"./recursive\";\n\n/** Matches an ATX Markdown heading line (`#` … `######`) at line start. */\nconst HEADING_LINE = /^#{1,6}[ \\t].*$/gm;\n\n/**\n * Markdown heading/section-aware splitter.\n *\n * Splits the document on ATX heading boundaries (`#`…`######`) first so a\n * section's heading stays glued to its body, then applies the recursive\n * character splitter WITHIN each section so any section larger than `size`\n * is broken down further. Sections at or under `size` are emitted whole.\n * Spans are exact relative to the original document.\n */\nexport function markdownChunk(\n  text: string,\n  size: number,\n  overlap: number,\n  separators: string[] = DEFAULT_SEPARATORS,\n): Chunk[] {\n  if (text.length === 0) {\n    return [];\n  }\n\n  const sections = splitSections(text);\n  const chunks: Chunk[] = [];\n  let index = 0;\n\n  for (const section of sections) {\n    const body = text.slice(section.start, section.end);\n\n    if (body.trim().length === 0) {\n      continue;\n    }\n\n    if (body.length <= size) {\n      chunks.push({\n        text: body,\n        index,\n        span: [section.start, section.end],\n      });\n      index += 1;\n\n      continue;\n    }\n\n    // Recurse within the section, then shift the relative spans to\n    // absolute document offsets and renumber sequentially.\n    const inner = recursiveChunk(body, size, overlap, separators);\n\n    for (const piece of inner) {\n      chunks.push({\n        text: piece.text,\n        index,\n        span: [section.start + piece.span[0], section.start + piece.span[1]],\n      });\n      index += 1;\n    }\n  }\n\n  return chunks;\n}\n\n/** A section's absolute `[start, end)` span (heading line + body until next heading). */\ntype SectionSpan = {\n  start: number;\n  end: number;\n};\n\n/**\n * Carve the document into sections, each beginning at a heading line and\n * running until the next heading (the preamble before the first heading is\n * its own section). Spans cover the whole document with no gaps.\n */\nfunction splitSections(text: string): SectionSpan[] {\n  const starts: number[] = [];\n  let match: RegExpExecArray | null;\n\n  HEADING_LINE.lastIndex = 0;\n\n  while ((match = HEADING_LINE.exec(text)) !== null) {\n    starts.push(match.index);\n  }\n\n  // No headings at all — the whole document is one section.\n  if (starts.length === 0) {\n    return [{ start: 0, end: text.length }];\n  }\n\n  const sections: SectionSpan[] = [];\n\n  // Preamble before the first heading, if any.\n  if (starts[0] > 0) {\n    sections.push({ start: 0, end: starts[0] });\n  }\n\n  starts.forEach((start, position) => {\n    const end = position + 1 < starts.length ? starts[position + 1] : text.length;\n\n    sections.push({ start, end });\n  });\n\n  return sections;\n}\n"],"mappings":";;;;AAIA,MAAM,eAAe;;;;;;;;;;AAWrB,SAAgB,cACd,MACA,MACA,SACA,aAAuB,oBACd;CACT,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAGV,MAAM,WAAW,cAAc,IAAI;CACnC,MAAM,SAAkB,CAAC;CACzB,IAAI,QAAQ;CAEZ,KAAK,MAAM,WAAW,UAAU;EAC9B,MAAM,OAAO,KAAK,MAAM,QAAQ,OAAO,QAAQ,GAAG;EAElD,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GACzB;EAGF,IAAI,KAAK,UAAU,MAAM;GACvB,OAAO,KAAK;IACV,MAAM;IACN;IACA,MAAM,CAAC,QAAQ,OAAO,QAAQ,GAAG;GACnC,CAAC;GACD,SAAS;GAET;EACF;EAIA,MAAM,QAAQ,eAAe,MAAM,MAAM,SAAS,UAAU;EAE5D,KAAK,MAAM,SAAS,OAAO;GACzB,OAAO,KAAK;IACV,MAAM,MAAM;IACZ;IACA,MAAM,CAAC,QAAQ,QAAQ,MAAM,KAAK,IAAI,QAAQ,QAAQ,MAAM,KAAK,EAAE;GACrE,CAAC;GACD,SAAS;EACX;CACF;CAEA,OAAO;AACT;;;;;;AAaA,SAAS,cAAc,MAA6B;CAClD,MAAM,SAAmB,CAAC;CAC1B,IAAI;CAEJ,aAAa,YAAY;CAEzB,QAAQ,QAAQ,aAAa,KAAK,IAAI,OAAO,MAC3C,OAAO,KAAK,MAAM,KAAK;CAIzB,IAAI,OAAO,WAAW,GACpB,OAAO,CAAC;EAAE,OAAO;EAAG,KAAK,KAAK;CAAO,CAAC;CAGxC,MAAM,WAA0B,CAAC;CAGjC,IAAI,OAAO,KAAK,GACd,SAAS,KAAK;EAAE,OAAO;EAAG,KAAK,OAAO;CAAG,CAAC;CAG5C,OAAO,SAAS,OAAO,aAAa;EAClC,MAAM,MAAM,WAAW,IAAI,OAAO,SAAS,OAAO,WAAW,KAAK,KAAK;EAEvE,SAAS,KAAK;GAAE;GAAO;EAAI,CAAC;CAC9B,CAAC;CAED,OAAO;AACT"}

package/esm/rag/chunk/recursive.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/chunk/recursive.ts
+//#region ../ai/src/rag/chunk/recursive.ts
 /** Default separators for the recursive splitter, tried largest-unit first. */
 const DEFAULT_SEPARATORS = [
 	"\n\n",

package/esm/rag/chunk/recursive.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"recursive.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/chunk/recursive.ts"],"sourcesContent":["import type { Chunk } from \"../contracts/chunk-options.type\";\n\n/** Default separators for the recursive splitter, tried largest-unit first. */\nexport const DEFAULT_SEPARATORS: string[] = [\"\\n\\n\", \"\\n\", \". \", \" \", \"\"];\n\n/**\n * Recursive character splitter (the default strategy).\n *\n * Walks `separators` largest-unit-first: it splits the text on the first\n * separator, then packs the resulting pieces into chunks up to `size`\n * characters, carrying `overlap` characters forward between adjacent\n * chunks. Any single piece that is itself larger than `size` is split\n * again on the next-finer separator, recursing until a piece fits (the\n * `\"\"` separator is the final char-by-char fallback).\n *\n * Every emitted chunk records its exact `[start, end)` character span in\n * the ORIGINAL text so a citation can point back precisely — spans are\n * tracked by index-of search as packed pieces are joined.\n *\n * Character-based and deliberately tokenizer-free.\n */\nexport function recursiveChunk(\n  text: string,\n  size: number,\n  overlap: number,\n  separators: string[] = DEFAULT_SEPARATORS,\n): Chunk[] {\n  const pieces = splitToPieces(text, size, separators);\n\n  // Re-anchor each packed piece to its absolute offset in `text`. Pieces\n  // are non-overlapping and in document order, so a forward cursor finds\n  // each one's true start even when the same substring repeats.\n  const spans = anchorPieces(text, pieces);\n\n  return packPieces(text, spans, size, overlap);\n}\n\n/**\n * Recursively split `text` into pieces no larger than `size` using the\n * ordered separator list. Pieces preserve original characters (no\n * trimming) so downstream span anchoring stays exact.\n */\nfunction splitToPieces(text: string, size: number, separators: string[]): string[] {\n  if (text.length <= size) {\n    return text.length > 0 ? [text] : [];\n  }\n\n  const [separator, ...rest] = separators;\n\n  // Exhausted every separator (or hit the char fallback) — hard-split by\n  // size so an oversize unit never blows the budget.\n  if (separator === undefined || separator === \"\") {\n    return hardSplit(text, size);\n  }\n\n  const segments = splitKeepingSeparator(text, separator);\n  const pieces: string[] = [];\n\n  for (const segment of segments) {\n    if (segment.length === 0) {\n      continue;\n    }\n\n    if (segment.length <= size) {\n      pieces.push(segment);\n\n      continue;\n    }\n\n    pieces.push(...splitToPieces(segment, size, rest));\n  }\n\n  return pieces;\n}\n\n/**\n * Split on `separator` but re-attach the separator to the end of each\n * preceding segment, so concatenating the segments reconstructs the\n * original text verbatim (keeping spans exact).\n */\nfunction splitKeepingSeparator(text: string, separator: string): string[] {\n  const raw = text.split(separator);\n  const segments: string[] = [];\n\n  raw.forEach((part, position) => {\n    const isLast = position === raw.length - 1;\n\n    segments.push(isLast ? part : part + separator);\n  });\n\n  return segments;\n}\n\n/** Hard char-window split for a unit larger than `size` with no usable separator. */\nfunction hardSplit(text: string, size: number): string[] {\n  const pieces: string[] = [];\n\n  for (let cursor = 0; cursor < text.length; cursor += size) {\n    pieces.push(text.slice(cursor, cursor + size));\n  }\n\n  return pieces;\n}\n\n/** A piece plus its absolute `[start, end)` span in the original text. */\ntype AnchoredPiece = {\n  text: string;\n  start: number;\n  end: number;\n};\n\n/**\n * Map each piece back to its absolute offset using a monotonic cursor —\n * pieces are emitted in document order, so the next occurrence at-or-after\n * the cursor is the correct one even for repeated substrings.\n */\nfunction anchorPieces(text: string, pieces: string[]): AnchoredPiece[] {\n  const anchored: AnchoredPiece[] = [];\n  let cursor = 0;\n\n  for (const piece of pieces) {\n    const start = text.indexOf(piece, cursor);\n    const resolvedStart = start === -1 ? cursor : start;\n    const end = resolvedStart + piece.length;\n\n    anchored.push({ text: piece, start: resolvedStart, end });\n    cursor = end;\n  }\n\n  return anchored;\n}\n\n/**\n * Greedily pack anchored pieces into chunks up to `size` characters, then\n * carry `overlap` trailing characters from each emitted chunk into the\n * next so context is not lost at a boundary. Spans are taken straight\n * from the anchored pieces, so the overlap text is part of the next\n * chunk's span exactly.\n */\nfunction packPieces(\n  text: string,\n  pieces: AnchoredPiece[],\n  size: number,\n  overlap: number,\n): Chunk[] {\n  const chunks: Chunk[] = [];\n\n  let bufferStart = -1;\n  let bufferEnd = -1;\n  let index = 0;\n\n  const flush = (): void => {\n    if (bufferStart === -1) {\n      return;\n    }\n\n    chunks.push({\n      text: text.slice(bufferStart, bufferEnd),\n      index,\n      span: [bufferStart, bufferEnd],\n    });\n    index += 1;\n  };\n\n  for (const piece of pieces) {\n    if (bufferStart === -1) {\n      bufferStart = piece.start;\n      bufferEnd = piece.end;\n\n      continue;\n    }\n\n    const projected = piece.end - bufferStart;\n\n    if (projected <= size) {\n      bufferEnd = piece.end;\n\n      continue;\n    }\n\n    flush();\n\n    // Start the next buffer `overlap` chars before this piece (clamped to\n    // the previous chunk's start) so adjacent chunks share context.\n    const overlapStart = overlap > 0 ? Math.max(bufferStart, piece.start - overlap) : piece.start;\n\n    bufferStart = overlapStart;\n    bufferEnd = piece.end;\n  }\n\n  flush();\n\n  return chunks;\n}\n"],"mappings":";;AAGA,MAAa,qBAA+B;CAAC;CAAQ;CAAM;CAAM;CAAK;AAAE;;;;;;;;;;;;;;;;;AAkBxE,SAAgB,eACd,MACA,MACA,SACA,aAAuB,oBACd;CAQT,OAAO,WAAW,MAFJ,aAAa,MALZ,cAAc,MAAM,MAAM,UAKH,CAEV,GAAG,MAAM,OAAO;AAC9C;;;;;;AAOA,SAAS,cAAc,MAAc,MAAc,YAAgC;CACjF,IAAI,KAAK,UAAU,MACjB,OAAO,KAAK,SAAS,IAAI,CAAC,IAAI,IAAI,CAAC;CAGrC,MAAM,CAAC,WAAW,GAAG,QAAQ;CAI7B,IAAI,cAAc,UAAa,cAAc,IAC3C,OAAO,UAAU,MAAM,IAAI;CAG7B,MAAM,WAAW,sBAAsB,MAAM,SAAS;CACtD,MAAM,SAAmB,CAAC;CAE1B,KAAK,MAAM,WAAW,UAAU;EAC9B,IAAI,QAAQ,WAAW,GACrB;EAGF,IAAI,QAAQ,UAAU,MAAM;GAC1B,OAAO,KAAK,OAAO;GAEnB;EACF;EAEA,OAAO,KAAK,GAAG,cAAc,SAAS,MAAM,IAAI,CAAC;CACnD;CAEA,OAAO;AACT;;;;;;AAOA,SAAS,sBAAsB,MAAc,WAA6B;CACxE,MAAM,MAAM,KAAK,MAAM,SAAS;CAChC,MAAM,WAAqB,CAAC;CAE5B,IAAI,SAAS,MAAM,aAAa;EAC9B,MAAM,SAAS,aAAa,IAAI,SAAS;EAEzC,SAAS,KAAK,SAAS,OAAO,OAAO,SAAS;CAChD,CAAC;CAED,OAAO;AACT;;AAGA,SAAS,UAAU,MAAc,MAAwB;CACvD,MAAM,SAAmB,CAAC;CAE1B,KAAK,IAAI,SAAS,GAAG,SAAS,KAAK,QAAQ,UAAU,MACnD,OAAO,KAAK,KAAK,MAAM,QAAQ,SAAS,IAAI,CAAC;CAG/C,OAAO;AACT;;;;;;AAcA,SAAS,aAAa,MAAc,QAAmC;CACrE,MAAM,WAA4B,CAAC;CACnC,IAAI,SAAS;CAEb,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,QAAQ,KAAK,QAAQ,OAAO,MAAM;EACxC,MAAM,gBAAgB,UAAU,KAAK,SAAS;EAC9C,MAAM,MAAM,gBAAgB,MAAM;EAElC,SAAS,KAAK;GAAE,MAAM;GAAO,OAAO;GAAe;EAAI,CAAC;EACxD,SAAS;CACX;CAEA,OAAO;AACT;;;;;;;;AASA,SAAS,WACP,MACA,QACA,MACA,SACS;CACT,MAAM,SAAkB,CAAC;CAEzB,IAAI,cAAc;CAClB,IAAI,YAAY;CAChB,IAAI,QAAQ;CAEZ,MAAM,cAAoB;EACxB,IAAI,gBAAgB,IAClB;EAGF,OAAO,KAAK;GACV,MAAM,KAAK,MAAM,aAAa,SAAS;GACvC;GACA,MAAM,CAAC,aAAa,SAAS;EAC/B,CAAC;EACD,SAAS;CACX;CAEA,KAAK,MAAM,SAAS,QAAQ;EAC1B,IAAI,gBAAgB,IAAI;GACtB,cAAc,MAAM;GACpB,YAAY,MAAM;GAElB;EACF;EAIA,IAFkB,MAAM,MAAM,eAEb,MAAM;GACrB,YAAY,MAAM;GAElB;EACF;EAEA,MAAM;EAMN,cAFqB,UAAU,IAAI,KAAK,IAAI,aAAa,MAAM,QAAQ,OAAO,IAAI,MAAM;EAGxF,YAAY,MAAM;CACpB;CAEA,MAAM;CAEN,OAAO;AACT"}
+{"version":3,"file":"recursive.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/chunk/recursive.ts"],"sourcesContent":["import type { Chunk } from \"../contracts/chunk-options.type\";\n\n/** Default separators for the recursive splitter, tried largest-unit first. */\nexport const DEFAULT_SEPARATORS: string[] = [\"\\n\\n\", \"\\n\", \". \", \" \", \"\"];\n\n/**\n * Recursive character splitter (the default strategy).\n *\n * Walks `separators` largest-unit-first: it splits the text on the first\n * separator, then packs the resulting pieces into chunks up to `size`\n * characters, carrying `overlap` characters forward between adjacent\n * chunks. Any single piece that is itself larger than `size` is split\n * again on the next-finer separator, recursing until a piece fits (the\n * `\"\"` separator is the final char-by-char fallback).\n *\n * Every emitted chunk records its exact `[start, end)` character span in\n * the ORIGINAL text so a citation can point back precisely — spans are\n * tracked by index-of search as packed pieces are joined.\n *\n * Character-based and deliberately tokenizer-free.\n */\nexport function recursiveChunk(\n  text: string,\n  size: number,\n  overlap: number,\n  separators: string[] = DEFAULT_SEPARATORS,\n): Chunk[] {\n  const pieces = splitToPieces(text, size, separators);\n\n  // Re-anchor each packed piece to its absolute offset in `text`. Pieces\n  // are non-overlapping and in document order, so a forward cursor finds\n  // each one's true start even when the same substring repeats.\n  const spans = anchorPieces(text, pieces);\n\n  return packPieces(text, spans, size, overlap);\n}\n\n/**\n * Recursively split `text` into pieces no larger than `size` using the\n * ordered separator list. Pieces preserve original characters (no\n * trimming) so downstream span anchoring stays exact.\n */\nfunction splitToPieces(text: string, size: number, separators: string[]): string[] {\n  if (text.length <= size) {\n    return text.length > 0 ? [text] : [];\n  }\n\n  const [separator, ...rest] = separators;\n\n  // Exhausted every separator (or hit the char fallback) — hard-split by\n  // size so an oversize unit never blows the budget.\n  if (separator === undefined || separator === \"\") {\n    return hardSplit(text, size);\n  }\n\n  const segments = splitKeepingSeparator(text, separator);\n  const pieces: string[] = [];\n\n  for (const segment of segments) {\n    if (segment.length === 0) {\n      continue;\n    }\n\n    if (segment.length <= size) {\n      pieces.push(segment);\n\n      continue;\n    }\n\n    pieces.push(...splitToPieces(segment, size, rest));\n  }\n\n  return pieces;\n}\n\n/**\n * Split on `separator` but re-attach the separator to the end of each\n * preceding segment, so concatenating the segments reconstructs the\n * original text verbatim (keeping spans exact).\n */\nfunction splitKeepingSeparator(text: string, separator: string): string[] {\n  const raw = text.split(separator);\n  const segments: string[] = [];\n\n  raw.forEach((part, position) => {\n    const isLast = position === raw.length - 1;\n\n    segments.push(isLast ? part : part + separator);\n  });\n\n  return segments;\n}\n\n/** Hard char-window split for a unit larger than `size` with no usable separator. */\nfunction hardSplit(text: string, size: number): string[] {\n  const pieces: string[] = [];\n\n  for (let cursor = 0; cursor < text.length; cursor += size) {\n    pieces.push(text.slice(cursor, cursor + size));\n  }\n\n  return pieces;\n}\n\n/** A piece plus its absolute `[start, end)` span in the original text. */\ntype AnchoredPiece = {\n  text: string;\n  start: number;\n  end: number;\n};\n\n/**\n * Map each piece back to its absolute offset using a monotonic cursor —\n * pieces are emitted in document order, so the next occurrence at-or-after\n * the cursor is the correct one even for repeated substrings.\n */\nfunction anchorPieces(text: string, pieces: string[]): AnchoredPiece[] {\n  const anchored: AnchoredPiece[] = [];\n  let cursor = 0;\n\n  for (const piece of pieces) {\n    const start = text.indexOf(piece, cursor);\n    const resolvedStart = start === -1 ? cursor : start;\n    const end = resolvedStart + piece.length;\n\n    anchored.push({ text: piece, start: resolvedStart, end });\n    cursor = end;\n  }\n\n  return anchored;\n}\n\n/**\n * Greedily pack anchored pieces into chunks up to `size` characters, then\n * carry `overlap` trailing characters from each emitted chunk into the\n * next so context is not lost at a boundary. Spans are taken straight\n * from the anchored pieces, so the overlap text is part of the next\n * chunk's span exactly.\n */\nfunction packPieces(\n  text: string,\n  pieces: AnchoredPiece[],\n  size: number,\n  overlap: number,\n): Chunk[] {\n  const chunks: Chunk[] = [];\n\n  let bufferStart = -1;\n  let bufferEnd = -1;\n  let index = 0;\n\n  const flush = (): void => {\n    if (bufferStart === -1) {\n      return;\n    }\n\n    chunks.push({\n      text: text.slice(bufferStart, bufferEnd),\n      index,\n      span: [bufferStart, bufferEnd],\n    });\n    index += 1;\n  };\n\n  for (const piece of pieces) {\n    if (bufferStart === -1) {\n      bufferStart = piece.start;\n      bufferEnd = piece.end;\n\n      continue;\n    }\n\n    const projected = piece.end - bufferStart;\n\n    if (projected <= size) {\n      bufferEnd = piece.end;\n\n      continue;\n    }\n\n    flush();\n\n    // Start the next buffer `overlap` chars before this piece (clamped to\n    // the previous chunk's start) so adjacent chunks share context.\n    const overlapStart = overlap > 0 ? Math.max(bufferStart, piece.start - overlap) : piece.start;\n\n    bufferStart = overlapStart;\n    bufferEnd = piece.end;\n  }\n\n  flush();\n\n  return chunks;\n}\n"],"mappings":";;AAGA,MAAa,qBAA+B;CAAC;CAAQ;CAAM;CAAM;CAAK;AAAE;;;;;;;;;;;;;;;;;AAkBxE,SAAgB,eACd,MACA,MACA,SACA,aAAuB,oBACd;CAQT,OAAO,WAAW,MAFJ,aAAa,MALZ,cAAc,MAAM,MAAM,UAKH,CAEV,GAAG,MAAM,OAAO;AAC9C;;;;;;AAOA,SAAS,cAAc,MAAc,MAAc,YAAgC;CACjF,IAAI,KAAK,UAAU,MACjB,OAAO,KAAK,SAAS,IAAI,CAAC,IAAI,IAAI,CAAC;CAGrC,MAAM,CAAC,WAAW,GAAG,QAAQ;CAI7B,IAAI,cAAc,UAAa,cAAc,IAC3C,OAAO,UAAU,MAAM,IAAI;CAG7B,MAAM,WAAW,sBAAsB,MAAM,SAAS;CACtD,MAAM,SAAmB,CAAC;CAE1B,KAAK,MAAM,WAAW,UAAU;EAC9B,IAAI,QAAQ,WAAW,GACrB;EAGF,IAAI,QAAQ,UAAU,MAAM;GAC1B,OAAO,KAAK,OAAO;GAEnB;EACF;EAEA,OAAO,KAAK,GAAG,cAAc,SAAS,MAAM,IAAI,CAAC;CACnD;CAEA,OAAO;AACT;;;;;;AAOA,SAAS,sBAAsB,MAAc,WAA6B;CACxE,MAAM,MAAM,KAAK,MAAM,SAAS;CAChC,MAAM,WAAqB,CAAC;CAE5B,IAAI,SAAS,MAAM,aAAa;EAC9B,MAAM,SAAS,aAAa,IAAI,SAAS;EAEzC,SAAS,KAAK,SAAS,OAAO,OAAO,SAAS;CAChD,CAAC;CAED,OAAO;AACT;;AAGA,SAAS,UAAU,MAAc,MAAwB;CACvD,MAAM,SAAmB,CAAC;CAE1B,KAAK,IAAI,SAAS,GAAG,SAAS,KAAK,QAAQ,UAAU,MACnD,OAAO,KAAK,KAAK,MAAM,QAAQ,SAAS,IAAI,CAAC;CAG/C,OAAO;AACT;;;;;;AAcA,SAAS,aAAa,MAAc,QAAmC;CACrE,MAAM,WAA4B,CAAC;CACnC,IAAI,SAAS;CAEb,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,QAAQ,KAAK,QAAQ,OAAO,MAAM;EACxC,MAAM,gBAAgB,UAAU,KAAK,SAAS;EAC9C,MAAM,MAAM,gBAAgB,MAAM;EAElC,SAAS,KAAK;GAAE,MAAM;GAAO,OAAO;GAAe;EAAI,CAAC;EACxD,SAAS;CACX;CAEA,OAAO;AACT;;;;;;;;AASA,SAAS,WACP,MACA,QACA,MACA,SACS;CACT,MAAM,SAAkB,CAAC;CAEzB,IAAI,cAAc;CAClB,IAAI,YAAY;CAChB,IAAI,QAAQ;CAEZ,MAAM,cAAoB;EACxB,IAAI,gBAAgB,IAClB;EAGF,OAAO,KAAK;GACV,MAAM,KAAK,MAAM,aAAa,SAAS;GACvC;GACA,MAAM,CAAC,aAAa,SAAS;EAC/B,CAAC;EACD,SAAS;CACX;CAEA,KAAK,MAAM,SAAS,QAAQ;EAC1B,IAAI,gBAAgB,IAAI;GACtB,cAAc,MAAM;GACpB,YAAY,MAAM;GAElB;EACF;EAIA,IAFkB,MAAM,MAAM,eAEb,MAAM;GACrB,YAAY,MAAM;GAElB;EACF;EAEA,MAAM;EAMN,cAFqB,UAAU,IAAI,KAAK,IAAI,aAAa,MAAM,QAAQ,OAAO,IAAI,MAAM;EAGxF,YAAY,MAAM;CACpB;CAEA,MAAM;CAEN,OAAO;AACT"}

package/esm/rag/chunk/sentence.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/chunk/sentence.ts
+//#region ../ai/src/rag/chunk/sentence.ts
 /** Matches a sentence terminator (`.`, `!`, `?`) followed by whitespace. */
 const SENTENCE_BOUNDARY = /([.!?])\s+/g;
 /**

package/esm/rag/chunk/sentence.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sentence.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/chunk/sentence.ts"],"sourcesContent":["import type { Chunk } from \"../contracts/chunk-options.type\";\n\n/** Matches a sentence terminator (`.`, `!`, `?`) followed by whitespace. */\nconst SENTENCE_BOUNDARY = /([.!?])\\s+/g;\n\n/**\n * Sentence-aware character splitter.\n *\n * Splits the text on sentence terminators (`. `, `! `, `? `), keeping the\n * terminator attached, then greedily packs whole sentences into chunks up\n * to `size` characters, carrying `overlap` characters forward between\n * adjacent chunks. A single sentence longer than `size` becomes its own\n * (oversize) chunk rather than being cut mid-sentence. Spans are exact.\n */\nexport function sentenceChunk(text: string, size: number, overlap: number): Chunk[] {\n  if (text.trim().length === 0) {\n    return [];\n  }\n\n  const sentences = splitSentences(text);\n  const chunks: Chunk[] = [];\n\n  let bufferStart = -1;\n  let bufferEnd = -1;\n  let index = 0;\n\n  const flush = (): void => {\n    if (bufferStart === -1) {\n      return;\n    }\n\n    chunks.push({\n      text: text.slice(bufferStart, bufferEnd),\n      index,\n      span: [bufferStart, bufferEnd],\n    });\n    index += 1;\n  };\n\n  for (const sentence of sentences) {\n    if (bufferStart === -1) {\n      bufferStart = sentence.start;\n      bufferEnd = sentence.end;\n\n      continue;\n    }\n\n    if (sentence.end - bufferStart <= size) {\n      bufferEnd = sentence.end;\n\n      continue;\n    }\n\n    flush();\n\n    const overlapStart =\n      overlap > 0 ? Math.max(bufferStart, sentence.start - overlap) : sentence.start;\n\n    bufferStart = overlapStart;\n    bufferEnd = sentence.end;\n  }\n\n  flush();\n\n  return chunks;\n}\n\n/** A sentence with its absolute `[start, end)` span in the original text. */\ntype SentenceSpan = {\n  start: number;\n  end: number;\n};\n\n/**\n * Split `text` into sentence spans on terminator + whitespace, keeping the\n * terminator with its sentence and absorbing the trailing whitespace into\n * the boundary so reconstructing the spans loses no characters.\n */\nfunction splitSentences(text: string): SentenceSpan[] {\n  const spans: SentenceSpan[] = [];\n  let start = 0;\n  let match: RegExpExecArray | null;\n\n  SENTENCE_BOUNDARY.lastIndex = 0;\n\n  while ((match = SENTENCE_BOUNDARY.exec(text)) !== null) {\n    const end = match.index + match[0].length;\n\n    spans.push({ start, end });\n    start = end;\n  }\n\n  if (start < text.length) {\n    spans.push({ start, end: text.length });\n  }\n\n  return spans;\n}\n"],"mappings":";;AAGA,MAAM,oBAAoB;;;;;;;;;;AAW1B,SAAgB,cAAc,MAAc,MAAc,SAA0B;CAClF,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GACzB,OAAO,CAAC;CAGV,MAAM,YAAY,eAAe,IAAI;CACrC,MAAM,SAAkB,CAAC;CAEzB,IAAI,cAAc;CAClB,IAAI,YAAY;CAChB,IAAI,QAAQ;CAEZ,MAAM,cAAoB;EACxB,IAAI,gBAAgB,IAClB;EAGF,OAAO,KAAK;GACV,MAAM,KAAK,MAAM,aAAa,SAAS;GACvC;GACA,MAAM,CAAC,aAAa,SAAS;EAC/B,CAAC;EACD,SAAS;CACX;CAEA,KAAK,MAAM,YAAY,WAAW;EAChC,IAAI,gBAAgB,IAAI;GACtB,cAAc,SAAS;GACvB,YAAY,SAAS;GAErB;EACF;EAEA,IAAI,SAAS,MAAM,eAAe,MAAM;GACtC,YAAY,SAAS;GAErB;EACF;EAEA,MAAM;EAKN,cAFE,UAAU,IAAI,KAAK,IAAI,aAAa,SAAS,QAAQ,OAAO,IAAI,SAAS;EAG3E,YAAY,SAAS;CACvB;CAEA,MAAM;CAEN,OAAO;AACT;;;;;;AAaA,SAAS,eAAe,MAA8B;CACpD,MAAM,QAAwB,CAAC;CAC/B,IAAI,QAAQ;CACZ,IAAI;CAEJ,kBAAkB,YAAY;CAE9B,QAAQ,QAAQ,kBAAkB,KAAK,IAAI,OAAO,MAAM;EACtD,MAAM,MAAM,MAAM,QAAQ,MAAM,EAAE,CAAC;EAEnC,MAAM,KAAK;GAAE;GAAO;EAAI,CAAC;EACzB,QAAQ;CACV;CAEA,IAAI,QAAQ,KAAK,QACf,MAAM,KAAK;EAAE;EAAO,KAAK,KAAK;CAAO,CAAC;CAGxC,OAAO;AACT"}
+{"version":3,"file":"sentence.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/chunk/sentence.ts"],"sourcesContent":["import type { Chunk } from \"../contracts/chunk-options.type\";\n\n/** Matches a sentence terminator (`.`, `!`, `?`) followed by whitespace. */\nconst SENTENCE_BOUNDARY = /([.!?])\\s+/g;\n\n/**\n * Sentence-aware character splitter.\n *\n * Splits the text on sentence terminators (`. `, `! `, `? `), keeping the\n * terminator attached, then greedily packs whole sentences into chunks up\n * to `size` characters, carrying `overlap` characters forward between\n * adjacent chunks. A single sentence longer than `size` becomes its own\n * (oversize) chunk rather than being cut mid-sentence. Spans are exact.\n */\nexport function sentenceChunk(text: string, size: number, overlap: number): Chunk[] {\n  if (text.trim().length === 0) {\n    return [];\n  }\n\n  const sentences = splitSentences(text);\n  const chunks: Chunk[] = [];\n\n  let bufferStart = -1;\n  let bufferEnd = -1;\n  let index = 0;\n\n  const flush = (): void => {\n    if (bufferStart === -1) {\n      return;\n    }\n\n    chunks.push({\n      text: text.slice(bufferStart, bufferEnd),\n      index,\n      span: [bufferStart, bufferEnd],\n    });\n    index += 1;\n  };\n\n  for (const sentence of sentences) {\n    if (bufferStart === -1) {\n      bufferStart = sentence.start;\n      bufferEnd = sentence.end;\n\n      continue;\n    }\n\n    if (sentence.end - bufferStart <= size) {\n      bufferEnd = sentence.end;\n\n      continue;\n    }\n\n    flush();\n\n    const overlapStart =\n      overlap > 0 ? Math.max(bufferStart, sentence.start - overlap) : sentence.start;\n\n    bufferStart = overlapStart;\n    bufferEnd = sentence.end;\n  }\n\n  flush();\n\n  return chunks;\n}\n\n/** A sentence with its absolute `[start, end)` span in the original text. */\ntype SentenceSpan = {\n  start: number;\n  end: number;\n};\n\n/**\n * Split `text` into sentence spans on terminator + whitespace, keeping the\n * terminator with its sentence and absorbing the trailing whitespace into\n * the boundary so reconstructing the spans loses no characters.\n */\nfunction splitSentences(text: string): SentenceSpan[] {\n  const spans: SentenceSpan[] = [];\n  let start = 0;\n  let match: RegExpExecArray | null;\n\n  SENTENCE_BOUNDARY.lastIndex = 0;\n\n  while ((match = SENTENCE_BOUNDARY.exec(text)) !== null) {\n    const end = match.index + match[0].length;\n\n    spans.push({ start, end });\n    start = end;\n  }\n\n  if (start < text.length) {\n    spans.push({ start, end: text.length });\n  }\n\n  return spans;\n}\n"],"mappings":";;AAGA,MAAM,oBAAoB;;;;;;;;;;AAW1B,SAAgB,cAAc,MAAc,MAAc,SAA0B;CAClF,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GACzB,OAAO,CAAC;CAGV,MAAM,YAAY,eAAe,IAAI;CACrC,MAAM,SAAkB,CAAC;CAEzB,IAAI,cAAc;CAClB,IAAI,YAAY;CAChB,IAAI,QAAQ;CAEZ,MAAM,cAAoB;EACxB,IAAI,gBAAgB,IAClB;EAGF,OAAO,KAAK;GACV,MAAM,KAAK,MAAM,aAAa,SAAS;GACvC;GACA,MAAM,CAAC,aAAa,SAAS;EAC/B,CAAC;EACD,SAAS;CACX;CAEA,KAAK,MAAM,YAAY,WAAW;EAChC,IAAI,gBAAgB,IAAI;GACtB,cAAc,SAAS;GACvB,YAAY,SAAS;GAErB;EACF;EAEA,IAAI,SAAS,MAAM,eAAe,MAAM;GACtC,YAAY,SAAS;GAErB;EACF;EAEA,MAAM;EAKN,cAFE,UAAU,IAAI,KAAK,IAAI,aAAa,SAAS,QAAQ,OAAO,IAAI,SAAS;EAG3E,YAAY,SAAS;CACvB;CAEA,MAAM;CAEN,OAAO;AACT;;;;;;AAaA,SAAS,eAAe,MAA8B;CACpD,MAAM,QAAwB,CAAC;CAC/B,IAAI,QAAQ;CACZ,IAAI;CAEJ,kBAAkB,YAAY;CAE9B,QAAQ,QAAQ,kBAAkB,KAAK,IAAI,OAAO,MAAM;EACtD,MAAM,MAAM,MAAM,QAAQ,MAAM,EAAE,CAAC;EAEnC,MAAM,KAAK;GAAE;GAAO;EAAI,CAAC;EACzB,QAAQ;CACV;CAEA,IAAI,QAAQ,KAAK,QACf,MAAM,KAAK;EAAE;EAAO,KAAK,KAAK;CAAO,CAAC;CAGxC,OAAO;AACT"}

package/esm/rag/contracts/chunk-options.type.d.mts

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/contracts/chunk-options.type.d.ts
+//#region ../ai/src/rag/contracts/chunk-options.type.d.ts
 /** Splitter strategy used to break a document's text before embedding. */
 type ChunkType = "recursive" | "sentence" | "fixed" | "markdown";
 /**

package/esm/rag/contracts/chunk-options.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/contracts/chunk-options.type.ts"],"mappings":";;KACY,SAAA;;;;AAAS;AAWrB;;;;;KAAY,YAAA;EAIV,gDAFA,IAAA,GAAO,SAAS,EAShB;EAPA,IAAA,WAOU;EALV,OAAA;EAae;;;;EARf,UAAA;AAAA;;;;AAcyB;;KANf,KAAA;wBAEV,IAAA;EAEA,KAAA;EAEA,IAAA,GAAO,KAAA,UAAe,GAAA;AAAA"}
+{"version":3,"file":"chunk-options.type.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/contracts/chunk-options.type.ts"],"mappings":";;KACY,SAAA;;;;AAAS;AAWrB;;;;;KAAY,YAAA;EAIV,gDAFA,IAAA,GAAO,SAAS,EAShB;EAPA,IAAA,WAOU;EALV,OAAA;EAae;;;;EARf,UAAA;AAAA;;;;AAcyB;;KANf,KAAA;wBAEV,IAAA;EAEA,KAAA;EAEA,IAAA,GAAO,KAAA,UAAe,GAAA;AAAA"}

package/esm/rag/contracts/citation.type.d.mts

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/contracts/citation.type.d.ts
+//#region ../ai/src/rag/contracts/citation.type.d.ts
 /** Where a retrieved chunk came from — the unit an answer cites. */
 type Citation = {
   /** `id` of the source `RagDocument` this chunk was split from. */sourceId: string; /** 0-based index of the chunk within its source document. */

package/esm/rag/contracts/citation.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"citation.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/contracts/citation.type.ts"],"mappings":";;KACY,QAAA;EAAQ,kEAElB,QAAA,UAQiB;EANjB,UAAA;EAEA,IAAA,GAAO,KAAA,UAAe,GAAA,WAAf;EAEP,KAAA;EAEA,QAAA,GAAW,MAAM;AAAA;;KAIP,cAAA;EAAA,iDAEV,IAAA;EAEA,KAAA,UAFA;EAIA,QAAA,EAAU,QAAQ;AAAA;;KAIR,eAAA;EAJQ,6DAMlB,IAAA,WAFyB;EAIzB,SAAA;EAJyB;;;;;EAUzB,UAAA,WAEI;EAAJ,IAAA;AAAA;;KAIU,cAAA;EAEV,mCAAA,KAAA,UAEQ;EAAR,MAAA,EAAQ,cAAc;AAAA"}
+{"version":3,"file":"citation.type.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/contracts/citation.type.ts"],"mappings":";;KACY,QAAA;EAAQ,kEAElB,QAAA,UAQiB;EANjB,UAAA;EAEA,IAAA,GAAO,KAAA,UAAe,GAAA,WAAf;EAEP,KAAA;EAEA,QAAA,GAAW,MAAM;AAAA;;KAIP,cAAA;EAAA,iDAEV,IAAA;EAEA,KAAA,UAFA;EAIA,QAAA,EAAU,QAAQ;AAAA;;KAIR,eAAA;EAJQ,6DAMlB,IAAA,WAFyB;EAIzB,SAAA;EAJyB;;;;;EAUzB,UAAA,WAEI;EAAJ,IAAA;AAAA;;KAIU,cAAA;EAEV,mCAAA,KAAA,UAEQ;EAAR,MAAA,EAAQ,cAAc;AAAA"}

package/esm/rag/contracts/rag-config.type.d.mts

@@ -6,7 +6,7 @@ import { ChunkOptions } from "./chunk-options.type.mjs";
 import { RagDocument } from "./rag-document.type.mjs";
 import { CacheDriver } from "@warlock.js/cache";
 
-//#region ../@warlock.js/ai/src/rag/contracts/rag-config.type.d.ts
+//#region ../ai/src/rag/contracts/rag-config.type.d.ts
 /** Options for `rag.asTool()` — how retrieval is exposed to an agent. */
 type RagAsToolOptions = {
   /** LLM tool name. Default `"retrieve_<rag.name>"`. */name?: string; /** Tool description the model reads. Sensible default derived from the rag name. */

package/esm/rag/contracts/rag-config.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"rag-config.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/contracts/rag-config.type.ts"],"mappings":";;;;;;;;;;KASY,gBAAA;EAAA,sDAEV,IAAA;EAEA,WAAA,WAFA;EAIA,QAAA,GAAW,eAAe;AAAA;;KAIhB,SAAA;EAJgB,gFAM1B,IAAA,WAFmB;EAInB,QAAA,EAAU,gBAAA;EAAA;;;;;EAMV,KAAA,GAAQ,WAAA,YAQkB;EAN1B,SAAA,WARA;EAUA,KAAA,GAAQ,YAAA,EAJR;EAMA,QAAA,GAAW,WAAA,EAJX;EAMA,QAAA,GAAW,eAAA;EAJH;;;;;;EAWR,MAAA;IAIE,yDAFA,YAAA,WAIQ;IAFR,SAAA,WAUa;IARb,QAAA;EAAA;AAAA;;;;;UAQa,GAAA;EAQN;EAAA,SANA,IAAA;EAY2D;EAVpE,KAAA,CAAM,IAAA,EAAM,WAAA,IAAe,KAAA,GAAQ,YAAA,GAAe,OAAA;IAAU,MAAA;EAAA;EAFnD;EAIT,QAAA,CAAS,KAAA,UAAe,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,cAAA;EAFhD;EAIZ,KAAA,IAAS,OAAA;EAJ0B;;;;;EAUnC,MAAA,CAAO,OAAA,GAAU,gBAAA,GAAmB,YAAA;IAAe,KAAA;EAAA,GAAiB,cAAA;AAAA"}
+{"version":3,"file":"rag-config.type.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/contracts/rag-config.type.ts"],"mappings":";;;;;;;;;;KASY,gBAAA;EAAA,sDAEV,IAAA;EAEA,WAAA,WAFA;EAIA,QAAA,GAAW,eAAe;AAAA;;KAIhB,SAAA;EAJgB,gFAM1B,IAAA,WAFmB;EAInB,QAAA,EAAU,gBAAA;EAAA;;;;;EAMV,KAAA,GAAQ,WAAA,YAQkB;EAN1B,SAAA,WARA;EAUA,KAAA,GAAQ,YAAA,EAJR;EAMA,QAAA,GAAW,WAAA,EAJX;EAMA,QAAA,GAAW,eAAA;EAJH;;;;;;EAWR,MAAA;IAIE,yDAFA,YAAA,WAIQ;IAFR,SAAA,WAUa;IARb,QAAA;EAAA;AAAA;;;;;UAQa,GAAA;EAQN;EAAA,SANA,IAAA;EAY2D;EAVpE,KAAA,CAAM,IAAA,EAAM,WAAA,IAAe,KAAA,GAAQ,YAAA,GAAe,OAAA;IAAU,MAAA;EAAA;EAFnD;EAIT,QAAA,CAAS,KAAA,UAAe,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,cAAA;EAFhD;EAIZ,KAAA,IAAS,OAAA;EAJ0B;;;;;EAUnC,MAAA,CAAO,OAAA,GAAU,gBAAA,GAAmB,YAAA;IAAe,KAAA;EAAA,GAAiB,cAAA;AAAA"}

package/esm/rag/contracts/rag-document.type.d.mts

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/contracts/rag-document.type.d.ts
+//#region ../ai/src/rag/contracts/rag-document.type.d.ts
 /**
  * A raw document handed to the pipeline before chunking.
  *

package/esm/rag/contracts/rag-document.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"rag-document.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/contracts/rag-document.type.ts"],"mappings":";;AAOA;;;;;;KAAY,WAAA;EAMC,6EAJX,EAAA,UASI;EAPJ,IAAA;EAEA,QAAA,GAAW,MAAM;;;;;EAKjB,IAAA;AAAA"}
+{"version":3,"file":"rag-document.type.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/contracts/rag-document.type.ts"],"mappings":";;AAOA;;;;;;KAAY,WAAA;EAMC,6EAJX,EAAA,UASI;EAPJ,IAAA;EAEA,QAAA,GAAW,MAAM;;;;;EAKjB,IAAA;AAAA"}

package/esm/rag/hybrid/bm25.d.mts

@@ -1,6 +1,6 @@
 import { RankedItem } from "./rrf.mjs";
 
-//#region ../@warlock.js/ai/src/rag/hybrid/bm25.d.ts
+//#region ../ai/src/rag/hybrid/bm25.d.ts
 /** A document to score lexically. */
 type LexicalDoc = {
   id: string;

package/esm/rag/hybrid/bm25.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"bm25.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/hybrid/bm25.ts"],"mappings":";;;;KAGY,UAAA;EAAe,EAAA;EAAY,IAAI;AAAA;;AAAA;AAwB3C;;;;;;;;;iBAAgB,QAAA,CAAS,KAAA,UAAe,IAAA,EAAM,aAAA,CAAc,UAAA,IAAc,UAAA"}
+{"version":3,"file":"bm25.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/hybrid/bm25.ts"],"mappings":";;;;KAGY,UAAA;EAAe,EAAA;EAAY,IAAI;AAAA;;AAAA;AAwB3C;;;;;;;;;iBAAgB,QAAA,CAAS,KAAA,UAAe,IAAA,EAAM,aAAA,CAAc,UAAA,IAAc,UAAA"}

package/esm/rag/hybrid/bm25.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/hybrid/bm25.ts
+//#region ../ai/src/rag/hybrid/bm25.ts
 const BM25_K1 = 1.5;
 const BM25_B = .75;
 /** Lowercase + split on non-word characters; drop empties. */

package/esm/rag/hybrid/bm25.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"bm25.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/hybrid/bm25.ts"],"sourcesContent":["import type { RankedItem } from \"./rrf\";\n\n/** A document to score lexically. */\nexport type LexicalDoc = { id: string; text: string };\n\nconst BM25_K1 = 1.5;\nconst BM25_B = 0.75;\n\n/** Lowercase + split on non-word characters; drop empties. */\nfunction tokenize(text: string): string[] {\n  return text\n    .toLowerCase()\n    .split(/[^a-z0-9]+/i)\n    .filter(Boolean);\n}\n\n/**\n * Rank `docs` against `query` with BM25 (A4) — the lexical half of hybrid\n * retrieval. Scores keyword overlap with TF saturation (`k1`) and length\n * normalization (`b`) over the candidate set, so an exact-term match\n * surfaces even when dense embeddings miss it. Returns docs sorted by\n * score (highest first); zero-score docs are dropped.\n *\n * Operates over the supplied candidate set (typically the dense retriever's\n * over-fetch), so it needs no global corpus index — ideal for fusing with\n * a vector ranking via {@link reciprocalRankFusion}.\n */\nexport function bm25Rank(query: string, docs: ReadonlyArray<LexicalDoc>): RankedItem[] {\n  const queryTerms = [...new Set(tokenize(query))];\n  if (queryTerms.length === 0 || docs.length === 0) return [];\n\n  const tokenized = docs.map(doc => ({ id: doc.id, terms: tokenize(doc.text) }));\n  const avgLen =\n    tokenized.reduce((sum, d) => sum + d.terms.length, 0) / tokenized.length || 1;\n\n  // Document frequency per query term, across the candidate set.\n  const df = new Map<string, number>();\n  for (const term of queryTerms) {\n    df.set(\n      term,\n      tokenized.filter(d => d.terms.includes(term)).length,\n    );\n  }\n\n  const n = tokenized.length;\n\n  const scored = tokenized.map(doc => {\n    const len = doc.terms.length || 1;\n    let score = 0;\n\n    for (const term of queryTerms) {\n      const tf = doc.terms.filter(t => t === term).length;\n      if (tf === 0) continue;\n\n      const docFreq = df.get(term) ?? 0;\n      // BM25 idf (with the +1 to keep it non-negative).\n      const idf = Math.log(1 + (n - docFreq + 0.5) / (docFreq + 0.5));\n      const numerator = tf * (BM25_K1 + 1);\n      const denominator = tf + BM25_K1 * (1 - BM25_B + BM25_B * (len / avgLen));\n      score += idf * (numerator / denominator);\n    }\n\n    return { id: doc.id, score };\n  });\n\n  return scored.filter(item => item.score > 0).sort((a, b) => b.score - a.score);\n}\n"],"mappings":";AAKA,MAAM,UAAU;AAChB,MAAM,SAAS;;AAGf,SAAS,SAAS,MAAwB;CACxC,OAAO,KACJ,YAAY,CAAC,CACb,MAAM,aAAa,CAAC,CACpB,OAAO,OAAO;AACnB;;;;;;;;;;;;AAaA,SAAgB,SAAS,OAAe,MAA+C;CACrF,MAAM,aAAa,CAAC,GAAG,IAAI,IAAI,SAAS,KAAK,CAAC,CAAC;CAC/C,IAAI,WAAW,WAAW,KAAK,KAAK,WAAW,GAAG,OAAO,CAAC;CAE1D,MAAM,YAAY,KAAK,KAAI,SAAQ;EAAE,IAAI,IAAI;EAAI,OAAO,SAAS,IAAI,IAAI;CAAE,EAAE;CAC7E,MAAM,SACJ,UAAU,QAAQ,KAAK,MAAM,MAAM,EAAE,MAAM,QAAQ,CAAC,IAAI,UAAU,UAAU;CAG9E,MAAM,qBAAK,IAAI,IAAoB;CACnC,KAAK,MAAM,QAAQ,YACjB,GAAG,IACD,MACA,UAAU,QAAO,MAAK,EAAE,MAAM,SAAS,IAAI,CAAC,CAAC,CAAC,MAChD;CAGF,MAAM,IAAI,UAAU;CAqBpB,OAnBe,UAAU,KAAI,QAAO;EAClC,MAAM,MAAM,IAAI,MAAM,UAAU;EAChC,IAAI,QAAQ;EAEZ,KAAK,MAAM,QAAQ,YAAY;GAC7B,MAAM,KAAK,IAAI,MAAM,QAAO,MAAK,MAAM,IAAI,CAAC,CAAC;GAC7C,IAAI,OAAO,GAAG;GAEd,MAAM,UAAU,GAAG,IAAI,IAAI,KAAK;GAEhC,MAAM,MAAM,KAAK,IAAI,KAAK,IAAI,UAAU,OAAQ,UAAU,GAAI;GAC9D,MAAM,YAAY,KAAM;GACxB,MAAM,cAAc,KAAK,WAAW,IAAI,SAAS,UAAU,MAAM;GACjE,SAAS,OAAO,YAAY;EAC9B;EAEA,OAAO;GAAE,IAAI,IAAI;GAAI;EAAM;CAC7B,CAEY,CAAC,CAAC,QAAO,SAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK;AAC/E"}
+{"version":3,"file":"bm25.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/hybrid/bm25.ts"],"sourcesContent":["import type { RankedItem } from \"./rrf\";\n\n/** A document to score lexically. */\nexport type LexicalDoc = { id: string; text: string };\n\nconst BM25_K1 = 1.5;\nconst BM25_B = 0.75;\n\n/** Lowercase + split on non-word characters; drop empties. */\nfunction tokenize(text: string): string[] {\n  return text\n    .toLowerCase()\n    .split(/[^a-z0-9]+/i)\n    .filter(Boolean);\n}\n\n/**\n * Rank `docs` against `query` with BM25 (A4) — the lexical half of hybrid\n * retrieval. Scores keyword overlap with TF saturation (`k1`) and length\n * normalization (`b`) over the candidate set, so an exact-term match\n * surfaces even when dense embeddings miss it. Returns docs sorted by\n * score (highest first); zero-score docs are dropped.\n *\n * Operates over the supplied candidate set (typically the dense retriever's\n * over-fetch), so it needs no global corpus index — ideal for fusing with\n * a vector ranking via {@link reciprocalRankFusion}.\n */\nexport function bm25Rank(query: string, docs: ReadonlyArray<LexicalDoc>): RankedItem[] {\n  const queryTerms = [...new Set(tokenize(query))];\n  if (queryTerms.length === 0 || docs.length === 0) return [];\n\n  const tokenized = docs.map(doc => ({ id: doc.id, terms: tokenize(doc.text) }));\n  const avgLen =\n    tokenized.reduce((sum, d) => sum + d.terms.length, 0) / tokenized.length || 1;\n\n  // Document frequency per query term, across the candidate set.\n  const df = new Map<string, number>();\n  for (const term of queryTerms) {\n    df.set(\n      term,\n      tokenized.filter(d => d.terms.includes(term)).length,\n    );\n  }\n\n  const n = tokenized.length;\n\n  const scored = tokenized.map(doc => {\n    const len = doc.terms.length || 1;\n    let score = 0;\n\n    for (const term of queryTerms) {\n      const tf = doc.terms.filter(t => t === term).length;\n      if (tf === 0) continue;\n\n      const docFreq = df.get(term) ?? 0;\n      // BM25 idf (with the +1 to keep it non-negative).\n      const idf = Math.log(1 + (n - docFreq + 0.5) / (docFreq + 0.5));\n      const numerator = tf * (BM25_K1 + 1);\n      const denominator = tf + BM25_K1 * (1 - BM25_B + BM25_B * (len / avgLen));\n      score += idf * (numerator / denominator);\n    }\n\n    return { id: doc.id, score };\n  });\n\n  return scored.filter(item => item.score > 0).sort((a, b) => b.score - a.score);\n}\n"],"mappings":";AAKA,MAAM,UAAU;AAChB,MAAM,SAAS;;AAGf,SAAS,SAAS,MAAwB;CACxC,OAAO,KACJ,YAAY,CAAC,CACb,MAAM,aAAa,CAAC,CACpB,OAAO,OAAO;AACnB;;;;;;;;;;;;AAaA,SAAgB,SAAS,OAAe,MAA+C;CACrF,MAAM,aAAa,CAAC,GAAG,IAAI,IAAI,SAAS,KAAK,CAAC,CAAC;CAC/C,IAAI,WAAW,WAAW,KAAK,KAAK,WAAW,GAAG,OAAO,CAAC;CAE1D,MAAM,YAAY,KAAK,KAAI,SAAQ;EAAE,IAAI,IAAI;EAAI,OAAO,SAAS,IAAI,IAAI;CAAE,EAAE;CAC7E,MAAM,SACJ,UAAU,QAAQ,KAAK,MAAM,MAAM,EAAE,MAAM,QAAQ,CAAC,IAAI,UAAU,UAAU;CAG9E,MAAM,qBAAK,IAAI,IAAoB;CACnC,KAAK,MAAM,QAAQ,YACjB,GAAG,IACD,MACA,UAAU,QAAO,MAAK,EAAE,MAAM,SAAS,IAAI,CAAC,CAAC,CAAC,MAChD;CAGF,MAAM,IAAI,UAAU;CAqBpB,OAnBe,UAAU,KAAI,QAAO;EAClC,MAAM,MAAM,IAAI,MAAM,UAAU;EAChC,IAAI,QAAQ;EAEZ,KAAK,MAAM,QAAQ,YAAY;GAC7B,MAAM,KAAK,IAAI,MAAM,QAAO,MAAK,MAAM,IAAI,CAAC,CAAC;GAC7C,IAAI,OAAO,GAAG;GAEd,MAAM,UAAU,GAAG,IAAI,IAAI,KAAK;GAEhC,MAAM,MAAM,KAAK,IAAI,KAAK,IAAI,UAAU,OAAQ,UAAU,GAAI;GAC9D,MAAM,YAAY,KAAM;GACxB,MAAM,cAAc,KAAK,WAAW,IAAI,SAAS,UAAU,MAAM;GACjE,SAAS,OAAO,YAAY;EAC9B;EAEA,OAAO;GAAE,IAAI,IAAI;GAAI;EAAM;CAC7B,CAEY,CAAC,CAAC,QAAO,SAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK;AAC/E"}

package/esm/rag/hybrid/hybrid-rank.d.mts

@@ -1,7 +1,7 @@
 import { RankedItem } from "./rrf.mjs";
 import { LexicalDoc } from "./bm25.mjs";
 
-//#region ../@warlock.js/ai/src/rag/hybrid/hybrid-rank.d.ts
+//#region ../ai/src/rag/hybrid/hybrid-rank.d.ts
 /**
  * Hybrid rank (A4) — fuse a dense (vector) ranking with a BM25 lexical
  * ranking over the same candidate set via Reciprocal Rank Fusion. Dense

package/esm/rag/hybrid/hybrid-rank.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"hybrid-rank.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/hybrid/hybrid-rank.ts"],"mappings":";;;;;;AAqBA;;;;;;;;;;;;;;;;iBAAgB,UAAA,CAAW,MAAA;EACzB,KAAA;EACA,KAAA,EAAO,aAAA;IAAgB,EAAA;EAAA;EACvB,UAAA,EAAY,aAAA,CAAc,UAAA;EAC1B,CAAA;AAAA,IACE,UAAA"}
+{"version":3,"file":"hybrid-rank.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/hybrid/hybrid-rank.ts"],"mappings":";;;;;;AAqBA;;;;;;;;;;;;;;;;iBAAgB,UAAA,CAAW,MAAA;EACzB,KAAA;EACA,KAAA,EAAO,aAAA;IAAgB,EAAA;EAAA;EACvB,UAAA,EAAY,aAAA,CAAc,UAAA;EAC1B,CAAA;AAAA,IACE,UAAA"}

package/esm/rag/hybrid/hybrid-rank.mjs

@@ -1,7 +1,7 @@
 import { reciprocalRankFusion } from "./rrf.mjs";
 import { bm25Rank } from "./bm25.mjs";
 
-//#region ../@warlock.js/ai/src/rag/hybrid/hybrid-rank.ts
+//#region ../ai/src/rag/hybrid/hybrid-rank.ts
 /**
 * Hybrid rank (A4) — fuse a dense (vector) ranking with a BM25 lexical
 * ranking over the same candidate set via Reciprocal Rank Fusion. Dense

package/esm/rag/hybrid/hybrid-rank.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"hybrid-rank.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/hybrid/hybrid-rank.ts"],"sourcesContent":["import { bm25Rank, type LexicalDoc } from \"./bm25\";\nimport { reciprocalRankFusion, type RankedItem } from \"./rrf\";\n\n/**\n * Hybrid rank (A4) — fuse a dense (vector) ranking with a BM25 lexical\n * ranking over the same candidate set via Reciprocal Rank Fusion. Dense\n * retrieval captures semantic similarity; BM25 captures exact-term\n * matches dense embeddings miss (names, ids, rare tokens). Fusing both\n * beats either alone for keyword-heavy queries.\n *\n * `dense` is the vector retriever's result in rank order; `candidates`\n * supplies the text for the lexical pass (typically the same over-fetched\n * set). Returns the fused ranking, highest score first.\n *\n * @example\n * const fused = hybridRank({\n *   query: \"invoice 8842 refund\",\n *   dense: vectorHits,                 // [{ id }, ...] in similarity order\n *   candidates: vectorHits.map(h => ({ id: h.id, text: h.text })),\n * });\n */\nexport function hybridRank(params: {\n  query: string;\n  dense: ReadonlyArray<{ id: string }>;\n  candidates: ReadonlyArray<LexicalDoc>;\n  k?: number;\n}): RankedItem[] {\n  const denseIds = params.dense.map(d => d.id);\n  const lexicalIds = bm25Rank(params.query, params.candidates).map(r => r.id);\n\n  return reciprocalRankFusion([denseIds, lexicalIds], params.k);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,WAAW,QAKV;CAIf,OAAO,qBAAqB,CAHX,OAAO,MAAM,KAAI,MAAK,EAAE,EAGL,GAFjB,SAAS,OAAO,OAAO,OAAO,UAAU,CAAC,CAAC,KAAI,MAAK,EAAE,EAExB,CAAC,GAAG,OAAO,CAAC;AAC9D"}
+{"version":3,"file":"hybrid-rank.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/hybrid/hybrid-rank.ts"],"sourcesContent":["import { bm25Rank, type LexicalDoc } from \"./bm25\";\nimport { reciprocalRankFusion, type RankedItem } from \"./rrf\";\n\n/**\n * Hybrid rank (A4) — fuse a dense (vector) ranking with a BM25 lexical\n * ranking over the same candidate set via Reciprocal Rank Fusion. Dense\n * retrieval captures semantic similarity; BM25 captures exact-term\n * matches dense embeddings miss (names, ids, rare tokens). Fusing both\n * beats either alone for keyword-heavy queries.\n *\n * `dense` is the vector retriever's result in rank order; `candidates`\n * supplies the text for the lexical pass (typically the same over-fetched\n * set). Returns the fused ranking, highest score first.\n *\n * @example\n * const fused = hybridRank({\n *   query: \"invoice 8842 refund\",\n *   dense: vectorHits,                 // [{ id }, ...] in similarity order\n *   candidates: vectorHits.map(h => ({ id: h.id, text: h.text })),\n * });\n */\nexport function hybridRank(params: {\n  query: string;\n  dense: ReadonlyArray<{ id: string }>;\n  candidates: ReadonlyArray<LexicalDoc>;\n  k?: number;\n}): RankedItem[] {\n  const denseIds = params.dense.map(d => d.id);\n  const lexicalIds = bm25Rank(params.query, params.candidates).map(r => r.id);\n\n  return reciprocalRankFusion([denseIds, lexicalIds], params.k);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,WAAW,QAKV;CAIf,OAAO,qBAAqB,CAHX,OAAO,MAAM,KAAI,MAAK,EAAE,EAGL,GAFjB,SAAS,OAAO,OAAO,OAAO,UAAU,CAAC,CAAC,KAAI,MAAK,EAAE,EAExB,CAAC,GAAG,OAAO,CAAC;AAC9D"}

package/esm/rag/hybrid/rrf.d.mts

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/hybrid/rrf.d.ts
+//#region ../ai/src/rag/hybrid/rrf.d.ts
 /** One item's id paired with a fused relevance score. */
 type RankedItem = {
   id: string;

package/esm/rag/hybrid/rrf.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"rrf.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/hybrid/rrf.ts"],"mappings":";;KACY,UAAA;EAAe,EAAA;EAAY,KAAK;AAAA;AAAA;AAiB5C;;;;;;;;;;;;;;AAjB4C,iBAiB5B,oBAAA,CACd,WAAA,EAAa,aAAA,CAAc,aAAA,WAC3B,CAAA,YACC,UAAA"}
+{"version":3,"file":"rrf.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/hybrid/rrf.ts"],"mappings":";;KACY,UAAA;EAAe,EAAA;EAAY,KAAK;AAAA;AAAA;AAiB5C;;;;;;;;;;;;;;AAjB4C,iBAiB5B,oBAAA,CACd,WAAA,EAAa,aAAA,CAAc,aAAA,WAC3B,CAAA,YACC,UAAA"}

package/esm/rag/hybrid/rrf.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/hybrid/rrf.ts
+//#region ../ai/src/rag/hybrid/rrf.ts
 /**
 * Reciprocal Rank Fusion (A4) — combine several independently-ranked
 * lists of ids into one consensus ranking. Each list contributes

package/esm/rag/hybrid/rrf.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"rrf.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/hybrid/rrf.ts"],"sourcesContent":["/** One item's id paired with a fused relevance score. */\nexport type RankedItem = { id: string; score: number };\n\n/**\n * Reciprocal Rank Fusion (A4) — combine several independently-ranked\n * lists of ids into one consensus ranking. Each list contributes\n * `1 / (k + rank)` to an id's score (rank is 0-based within that list), so\n * an id near the top of multiple lists rises even if no single list ranks\n * it first. The classic fusion for hybrid (dense + lexical) retrieval\n * because it needs no score calibration between the lists.\n *\n * `k` (default 60, the standard) dampens the contribution of lower ranks.\n * Returns ids sorted by fused score, highest first.\n *\n * @example\n * reciprocalRankFusion([[\"a\", \"b\", \"c\"], [\"b\", \"a\"]]);\n * // → [{ id: \"b\", ... }, { id: \"a\", ... }, { id: \"c\", ... }]\n */\nexport function reciprocalRankFusion(\n  rankedLists: ReadonlyArray<ReadonlyArray<string>>,\n  k = 60,\n): RankedItem[] {\n  const scores = new Map<string, number>();\n\n  for (const list of rankedLists) {\n    list.forEach((id, rank) => {\n      scores.set(id, (scores.get(id) ?? 0) + 1 / (k + rank));\n    });\n  }\n\n  return [...scores.entries()]\n    .map(([id, score]) => ({ id, score }))\n    .sort((a, b) => b.score - a.score);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,SAAgB,qBACd,aACA,IAAI,IACU;CACd,MAAM,yBAAS,IAAI,IAAoB;CAEvC,KAAK,MAAM,QAAQ,aACjB,KAAK,SAAS,IAAI,SAAS;EACzB,OAAO,IAAI,KAAK,OAAO,IAAI,EAAE,KAAK,KAAK,KAAK,IAAI,KAAK;CACvD,CAAC;CAGH,OAAO,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC,CACzB,KAAK,CAAC,IAAI,YAAY;EAAE;EAAI;CAAM,EAAE,CAAC,CACrC,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK;AACrC"}
+{"version":3,"file":"rrf.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/hybrid/rrf.ts"],"sourcesContent":["/** One item's id paired with a fused relevance score. */\nexport type RankedItem = { id: string; score: number };\n\n/**\n * Reciprocal Rank Fusion (A4) — combine several independently-ranked\n * lists of ids into one consensus ranking. Each list contributes\n * `1 / (k + rank)` to an id's score (rank is 0-based within that list), so\n * an id near the top of multiple lists rises even if no single list ranks\n * it first. The classic fusion for hybrid (dense + lexical) retrieval\n * because it needs no score calibration between the lists.\n *\n * `k` (default 60, the standard) dampens the contribution of lower ranks.\n * Returns ids sorted by fused score, highest first.\n *\n * @example\n * reciprocalRankFusion([[\"a\", \"b\", \"c\"], [\"b\", \"a\"]]);\n * // → [{ id: \"b\", ... }, { id: \"a\", ... }, { id: \"c\", ... }]\n */\nexport function reciprocalRankFusion(\n  rankedLists: ReadonlyArray<ReadonlyArray<string>>,\n  k = 60,\n): RankedItem[] {\n  const scores = new Map<string, number>();\n\n  for (const list of rankedLists) {\n    list.forEach((id, rank) => {\n      scores.set(id, (scores.get(id) ?? 0) + 1 / (k + rank));\n    });\n  }\n\n  return [...scores.entries()]\n    .map(([id, score]) => ({ id, score }))\n    .sort((a, b) => b.score - a.score);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,SAAgB,qBACd,aACA,IAAI,IACU;CACd,MAAM,yBAAS,IAAI,IAAoB;CAEvC,KAAK,MAAM,QAAQ,aACjB,KAAK,SAAS,IAAI,SAAS;EACzB,OAAO,IAAI,KAAK,OAAO,IAAI,EAAE,KAAK,KAAK,KAAK,IAAI,KAAK;CACvD,CAAC;CAGH,OAAO,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC,CACzB,KAAK,CAAC,IAAI,YAAY;EAAE;EAAI;CAAM,EAAE,CAAC,CACrC,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK;AACrC"}

package/esm/rag/loaders/errors.d.mts

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/loaders/errors.d.ts
+//#region ../ai/src/rag/loaders/errors.d.ts
 /**
  * Loader error surface. The only loader-specific failure is a missing
  * OPTIONAL peer (`pdf-parse`), which — like the moderation detector's

package/esm/rag/loaders/errors.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/errors.ts"],"mappings":";;AAeA;;;;AAKQ;;;;;;;;;cALK,8BAAA"}
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/errors.ts"],"mappings":";;AAeA;;;;AAKQ;;;;;;;;;cALK,8BAAA"}

package/esm/rag/loaders/errors.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/loaders/errors.ts
+//#region ../ai/src/rag/loaders/errors.ts
 /**
 * Loader error surface. The only loader-specific failure is a missing
 * OPTIONAL peer (`pdf-parse`), which — like the moderation detector's

package/esm/rag/loaders/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/errors.ts"],"sourcesContent":["/**\n * Loader error surface. The only loader-specific failure is a missing\n * OPTIONAL peer (`pdf-parse`), which — like the moderation detector's\n * missing `openai` peer — is an *infrastructure* fault, not a content\n * problem, so {@link loadPdf} throws a plain `Error` carrying the curated\n * {@link PDF_PARSE_INSTALL_INSTRUCTIONS} rather than an `AIError`. Mirrors\n * the guard's `OPENAI_INSTALL_INSTRUCTIONS` / ai-panoptic's\n * `LANGFUSE_INSTALL_INSTRUCTIONS`.\n */\n\n/**\n * Curated install string thrown by {@link loadPdf} on first call when the\n * `pdf-parse` peer is absent. Surfaced instead of a raw\n * module-resolution stack trace.\n */\nexport const PDF_PARSE_INSTALL_INSTRUCTIONS = `\nThe @warlock.js/ai PDF loader requires the optional \"pdf-parse\" peer.\nInstall it with:\n\n  npm install pdf-parse\n`.trim();\n"],"mappings":";;;;;;;;;;;;;;;AAeA,MAAa,iCAAiC;;;;;EAK5C,KAAK"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/errors.ts"],"sourcesContent":["/**\n * Loader error surface. The only loader-specific failure is a missing\n * OPTIONAL peer (`pdf-parse`), which — like the moderation detector's\n * missing `openai` peer — is an *infrastructure* fault, not a content\n * problem, so {@link loadPdf} throws a plain `Error` carrying the curated\n * {@link PDF_PARSE_INSTALL_INSTRUCTIONS} rather than an `AIError`. Mirrors\n * the guard's `OPENAI_INSTALL_INSTRUCTIONS` / ai-panoptic's\n * `LANGFUSE_INSTALL_INSTRUCTIONS`.\n */\n\n/**\n * Curated install string thrown by {@link loadPdf} on first call when the\n * `pdf-parse` peer is absent. Surfaced instead of a raw\n * module-resolution stack trace.\n */\nexport const PDF_PARSE_INSTALL_INSTRUCTIONS = `\nThe @warlock.js/ai PDF loader requires the optional \"pdf-parse\" peer.\nInstall it with:\n\n  npm install pdf-parse\n`.trim();\n"],"mappings":";;;;;;;;;;;;;;;AAeA,MAAa,iCAAiC;;;;;EAK5C,KAAK"}

package/esm/rag/loaders/load-html.d.mts

@@ -1,6 +1,6 @@
 import { LoadHtmlOptions, RagLoaderResult } from "./loader.type.mjs";
 
-//#region ../@warlock.js/ai/src/rag/loaders/load-html.d.ts
+//#region ../ai/src/rag/loaders/load-html.d.ts
 /**
  * Load an HTML string into a single {@link RagDocument} of readable text.
  * Scripts, styles, and other non-prose elements are dropped content-and-all,

package/esm/rag/loaders/load-html.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"load-html.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/load-html.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;iBAiKgB,QAAA,CACd,IAAA,UACA,OAAA,GAAS,eAAA,GACR,eAAe"}
+{"version":3,"file":"load-html.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-html.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;iBAiKgB,QAAA,CACd,IAAA,UACA,OAAA,GAAS,eAAA,GACR,eAAe"}

package/esm/rag/loaders/load-html.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/loaders/load-html.ts
+//#region ../ai/src/rag/loaders/load-html.ts
 /** Default `id` when the caller supplies none. */
 const DEFAULT_ID = "document";
 /**

package/esm/rag/loaders/load-html.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"load-html.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/load-html.ts"],"sourcesContent":["import type { RagDocument } from \"../contracts/rag-document.type\";\nimport type { LoadHtmlOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Default `id` when the caller supplies none. */\nconst DEFAULT_ID = \"document\";\n\n/**\n * Elements whose *content* is not human-readable text and must be removed\n * wholesale (open tag → close tag → everything in between) before tags are\n * stripped. `script` / `style` would otherwise leak code into the chunked\n * text; `noscript` / `template` / `head` / `svg` are non-prose noise.\n */\nconst STRIPPED_ELEMENTS = [\n  \"script\",\n  \"style\",\n  \"noscript\",\n  \"template\",\n  \"head\",\n  \"svg\",\n];\n\n/**\n * Block-level tags that imply a line break in the readable text. Replacing\n * them with `\\n` BEFORE the generic tag strip keeps paragraph / list / table\n * structure (so the recursive splitter still sees `\\n\\n` boundaries) instead\n * of collapsing the whole page onto one line.\n */\nconst BLOCK_TAGS =\n  /<\\/?(?:p|div|section|article|header|footer|main|aside|nav|h[1-6]|ul|ol|li|table|tr|td|th|thead|tbody|blockquote|pre|hr|br)\\b[^>]*>/gi;\n\n/** Named HTML entities common in prose. Numeric entities are decoded generically. */\nconst NAMED_ENTITIES: Record<string, string> = {\n  amp: \"&\",\n  lt: \"<\",\n  gt: \">\",\n  quot: '\"',\n  apos: \"'\",\n  nbsp: \" \",\n  copy: \"©\",\n  reg: \"®\",\n  trade: \"™\",\n  hellip: \"…\",\n  mdash: \"—\",\n  ndash: \"–\",\n  lsquo: \"‘\",\n  rsquo: \"’\",\n  ldquo: \"“\",\n  rdquo: \"”\",\n  laquo: \"«\",\n  raquo: \"»\",\n  middot: \"·\",\n  bull: \"•\",\n};\n\n/**\n * Decode the HTML entities that survive tag stripping: named (`&amp;`),\n * decimal (`&#169;`), and hex (`&#xA9;`). Unknown named entities are left\n * verbatim rather than dropped, so unusual markup never silently loses text.\n */\nfunction decodeEntities(text: string): string {\n  return text.replace(/&(#x?[0-9a-f]+|[a-z][a-z0-9]*);/gi, (match, body: string) => {\n    if (body[0] === \"#\") {\n      const codePoint =\n        body[1] === \"x\" || body[1] === \"X\"\n          ? Number.parseInt(body.slice(2), 16)\n          : Number.parseInt(body.slice(1), 10);\n\n      if (Number.isNaN(codePoint) || codePoint < 0 || codePoint > 0x10ffff) {\n        return match;\n      }\n\n      try {\n        return String.fromCodePoint(codePoint);\n      } catch {\n        return match;\n      }\n    }\n\n    const named = NAMED_ENTITIES[body.toLowerCase()];\n\n    return named ?? match;\n  });\n}\n\n/**\n * Pull the `<title>` text out of the document, decoded and trimmed, or\n * `undefined` when there is none. Read BEFORE `<head>` is stripped.\n */\nfunction extractTitle(html: string): string | undefined {\n  const match = /<title[^>]*>([\\s\\S]*?)<\\/title>/i.exec(html);\n\n  if (!match) {\n    return undefined;\n  }\n\n  const title = decodeEntities(match[1]).replace(/\\s+/g, \" \").trim();\n\n  return title.length > 0 ? title : undefined;\n}\n\n/**\n * Strip HTML markup down to readable plain text — a lightweight,\n * dependency-free pass (no DOM parser): drop comments and non-prose elements\n * (`script` / `style` / `head` / `svg` / …) content-and-all, convert block\n * tags to line breaks to preserve paragraph structure, remove every\n * remaining tag, decode entities, then collapse runs of whitespace while\n * keeping blank-line paragraph separators.\n */\nfunction htmlToText(html: string): string {\n  let text = html;\n\n  // 1. Comments first — a commented-out `<script>` must not survive.\n  text = text.replace(/<!--[\\s\\S]*?-->/g, \" \");\n\n  // 2. Non-prose elements, content and all.\n  for (const tag of STRIPPED_ELEMENTS) {\n    const element = new RegExp(`<${tag}\\\\b[^>]*>[\\\\s\\\\S]*?<\\\\/${tag}>`, \"gi\");\n    text = text.replace(element, \" \");\n    // Defensively drop a self-closing / unterminated open tag too.\n    text = text.replace(new RegExp(`<\\\\/?${tag}\\\\b[^>]*>`, \"gi\"), \" \");\n  }\n\n  // 3. Block tags → newlines, so paragraph / list structure survives.\n  text = text.replace(BLOCK_TAGS, \"\\n\");\n\n  // 4. Every remaining tag → gone.\n  text = text.replace(/<[^>]+>/g, \"\");\n\n  // 5. Entities → characters.\n  text = decodeEntities(text);\n\n  // 6. Normalize whitespace: trim each line, drop blank runs to a single\n  //    blank line (a paragraph separator the recursive splitter honors).\n  text = text\n    .replace(/[^\\S\\n]+/g, \" \")\n    .replace(/[ \\t]*\\n[ \\t]*/g, \"\\n\")\n    .replace(/\\n{3,}/g, \"\\n\\n\")\n    .trim();\n\n  return text;\n}\n\n/**\n * Load an HTML string into a single {@link RagDocument} of readable text.\n * Scripts, styles, and other non-prose elements are dropped content-and-all,\n * block tags become line breaks (so paragraph structure survives for the\n * splitter), remaining tags are stripped, and HTML entities are decoded — a\n * lightweight regex pass, no heavy DOM dependency.\n *\n * The document's `metadata.title` is set from the page's `<title>` (unless\n * the caller overrode it), and `metadata.loader` is `\"html\"`. The output is\n * the exact shape `index()` consumes.\n *\n * @example\n * const kb = ai.rag({ embedder, store });\n * await kb.index(loadHtml(rawHtmlString, { id: \"landing-page\" }));\n *\n * @param html - The raw HTML markup.\n * @param options - Shared `id` / `metadata` / `tags` ({@link LoadHtmlOptions}).\n * @returns A {@link RagLoaderResult} (one document) ready for `rag.index()`.\n */\nexport function loadHtml(\n  html: string,\n  options: LoadHtmlOptions = {},\n): RagLoaderResult {\n  const id = options.id ?? DEFAULT_ID;\n  const title = extractTitle(html);\n  const text = htmlToText(html);\n\n  // An all-markup / empty page strips to nothing; emit no document so\n  // index() never receives a no-op record (matches loadText's behavior).\n  if (text.length === 0) {\n    return [];\n  }\n\n  // Derived keys (source, loader, title) sit UNDER the caller's metadata so\n  // an explicit override always wins.\n  const doc: RagDocument = {\n    id,\n    text,\n    metadata: {\n      source: id,\n      loader: \"html\",\n      ...(title !== undefined ? { title } : {}),\n      ...options.metadata,\n    },\n    tags: options.tags,\n  };\n\n  return [doc];\n}\n\n/** Internal — exported for the web loader so it shares the exact strip pass. */\nexport { htmlToText, extractTitle };\n"],"mappings":";;AAIA,MAAM,aAAa;;;;;;;AAQnB,MAAM,oBAAoB;CACxB;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;AAQA,MAAM,aACJ;;AAGF,MAAM,iBAAyC;CAC7C,KAAK;CACL,IAAI;CACJ,IAAI;CACJ,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,KAAK;CACL,OAAO;CACP,QAAQ;CACR,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,QAAQ;CACR,MAAM;AACR;;;;;;AAOA,SAAS,eAAe,MAAsB;CAC5C,OAAO,KAAK,QAAQ,sCAAsC,OAAO,SAAiB;EAChF,IAAI,KAAK,OAAO,KAAK;GACnB,MAAM,YACJ,KAAK,OAAO,OAAO,KAAK,OAAO,MAC3B,OAAO,SAAS,KAAK,MAAM,CAAC,GAAG,EAAE,IACjC,OAAO,SAAS,KAAK,MAAM,CAAC,GAAG,EAAE;GAEvC,IAAI,OAAO,MAAM,SAAS,KAAK,YAAY,KAAK,YAAY,SAC1D,OAAO;GAGT,IAAI;IACF,OAAO,OAAO,cAAc,SAAS;GACvC,QAAQ;IACN,OAAO;GACT;EACF;EAIA,OAFc,eAAe,KAAK,YAAY,MAE9B;CAClB,CAAC;AACH;;;;;AAMA,SAAS,aAAa,MAAkC;CACtD,MAAM,QAAQ,mCAAmC,KAAK,IAAI;CAE1D,IAAI,CAAC,OACH;CAGF,MAAM,QAAQ,eAAe,MAAM,EAAE,CAAC,CAAC,QAAQ,QAAQ,GAAG,CAAC,CAAC,KAAK;CAEjE,OAAO,MAAM,SAAS,IAAI,QAAQ;AACpC;;;;;;;;;AAUA,SAAS,WAAW,MAAsB;CACxC,IAAI,OAAO;CAGX,OAAO,KAAK,QAAQ,oBAAoB,GAAG;CAG3C,KAAK,MAAM,OAAO,mBAAmB;EACnC,MAAM,UAAU,IAAI,OAAO,IAAI,IAAI,yBAAyB,IAAI,IAAI,IAAI;EACxE,OAAO,KAAK,QAAQ,SAAS,GAAG;EAEhC,OAAO,KAAK,QAAQ,IAAI,OAAO,QAAQ,IAAI,YAAY,IAAI,GAAG,GAAG;CACnE;CAGA,OAAO,KAAK,QAAQ,YAAY,IAAI;CAGpC,OAAO,KAAK,QAAQ,YAAY,EAAE;CAGlC,OAAO,eAAe,IAAI;CAI1B,OAAO,KACJ,QAAQ,aAAa,GAAG,CAAC,CACzB,QAAQ,mBAAmB,IAAI,CAAC,CAChC,QAAQ,WAAW,MAAM,CAAC,CAC1B,KAAK;CAER,OAAO;AACT;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,SACd,MACA,UAA2B,CAAC,GACX;CACjB,MAAM,KAAK,QAAQ,MAAM;CACzB,MAAM,QAAQ,aAAa,IAAI;CAC/B,MAAM,OAAO,WAAW,IAAI;CAI5B,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAiBV,OAAO,CAAC;EAXN;EACA;EACA,UAAU;GACR,QAAQ;GACR,QAAQ;GACR,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC;GACvC,GAAG,QAAQ;EACb;EACA,MAAM,QAAQ;CAGN,CAAC;AACb"}
+{"version":3,"file":"load-html.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-html.ts"],"sourcesContent":["import type { RagDocument } from \"../contracts/rag-document.type\";\nimport type { LoadHtmlOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Default `id` when the caller supplies none. */\nconst DEFAULT_ID = \"document\";\n\n/**\n * Elements whose *content* is not human-readable text and must be removed\n * wholesale (open tag → close tag → everything in between) before tags are\n * stripped. `script` / `style` would otherwise leak code into the chunked\n * text; `noscript` / `template` / `head` / `svg` are non-prose noise.\n */\nconst STRIPPED_ELEMENTS = [\n  \"script\",\n  \"style\",\n  \"noscript\",\n  \"template\",\n  \"head\",\n  \"svg\",\n];\n\n/**\n * Block-level tags that imply a line break in the readable text. Replacing\n * them with `\\n` BEFORE the generic tag strip keeps paragraph / list / table\n * structure (so the recursive splitter still sees `\\n\\n` boundaries) instead\n * of collapsing the whole page onto one line.\n */\nconst BLOCK_TAGS =\n  /<\\/?(?:p|div|section|article|header|footer|main|aside|nav|h[1-6]|ul|ol|li|table|tr|td|th|thead|tbody|blockquote|pre|hr|br)\\b[^>]*>/gi;\n\n/** Named HTML entities common in prose. Numeric entities are decoded generically. */\nconst NAMED_ENTITIES: Record<string, string> = {\n  amp: \"&\",\n  lt: \"<\",\n  gt: \">\",\n  quot: '\"',\n  apos: \"'\",\n  nbsp: \" \",\n  copy: \"©\",\n  reg: \"®\",\n  trade: \"™\",\n  hellip: \"…\",\n  mdash: \"—\",\n  ndash: \"–\",\n  lsquo: \"‘\",\n  rsquo: \"’\",\n  ldquo: \"“\",\n  rdquo: \"”\",\n  laquo: \"«\",\n  raquo: \"»\",\n  middot: \"·\",\n  bull: \"•\",\n};\n\n/**\n * Decode the HTML entities that survive tag stripping: named (`&amp;`),\n * decimal (`&#169;`), and hex (`&#xA9;`). Unknown named entities are left\n * verbatim rather than dropped, so unusual markup never silently loses text.\n */\nfunction decodeEntities(text: string): string {\n  return text.replace(/&(#x?[0-9a-f]+|[a-z][a-z0-9]*);/gi, (match, body: string) => {\n    if (body[0] === \"#\") {\n      const codePoint =\n        body[1] === \"x\" || body[1] === \"X\"\n          ? Number.parseInt(body.slice(2), 16)\n          : Number.parseInt(body.slice(1), 10);\n\n      if (Number.isNaN(codePoint) || codePoint < 0 || codePoint > 0x10ffff) {\n        return match;\n      }\n\n      try {\n        return String.fromCodePoint(codePoint);\n      } catch {\n        return match;\n      }\n    }\n\n    const named = NAMED_ENTITIES[body.toLowerCase()];\n\n    return named ?? match;\n  });\n}\n\n/**\n * Pull the `<title>` text out of the document, decoded and trimmed, or\n * `undefined` when there is none. Read BEFORE `<head>` is stripped.\n */\nfunction extractTitle(html: string): string | undefined {\n  const match = /<title[^>]*>([\\s\\S]*?)<\\/title>/i.exec(html);\n\n  if (!match) {\n    return undefined;\n  }\n\n  const title = decodeEntities(match[1]).replace(/\\s+/g, \" \").trim();\n\n  return title.length > 0 ? title : undefined;\n}\n\n/**\n * Strip HTML markup down to readable plain text — a lightweight,\n * dependency-free pass (no DOM parser): drop comments and non-prose elements\n * (`script` / `style` / `head` / `svg` / …) content-and-all, convert block\n * tags to line breaks to preserve paragraph structure, remove every\n * remaining tag, decode entities, then collapse runs of whitespace while\n * keeping blank-line paragraph separators.\n */\nfunction htmlToText(html: string): string {\n  let text = html;\n\n  // 1. Comments first — a commented-out `<script>` must not survive.\n  text = text.replace(/<!--[\\s\\S]*?-->/g, \" \");\n\n  // 2. Non-prose elements, content and all.\n  for (const tag of STRIPPED_ELEMENTS) {\n    const element = new RegExp(`<${tag}\\\\b[^>]*>[\\\\s\\\\S]*?<\\\\/${tag}>`, \"gi\");\n    text = text.replace(element, \" \");\n    // Defensively drop a self-closing / unterminated open tag too.\n    text = text.replace(new RegExp(`<\\\\/?${tag}\\\\b[^>]*>`, \"gi\"), \" \");\n  }\n\n  // 3. Block tags → newlines, so paragraph / list structure survives.\n  text = text.replace(BLOCK_TAGS, \"\\n\");\n\n  // 4. Every remaining tag → gone.\n  text = text.replace(/<[^>]+>/g, \"\");\n\n  // 5. Entities → characters.\n  text = decodeEntities(text);\n\n  // 6. Normalize whitespace: trim each line, drop blank runs to a single\n  //    blank line (a paragraph separator the recursive splitter honors).\n  text = text\n    .replace(/[^\\S\\n]+/g, \" \")\n    .replace(/[ \\t]*\\n[ \\t]*/g, \"\\n\")\n    .replace(/\\n{3,}/g, \"\\n\\n\")\n    .trim();\n\n  return text;\n}\n\n/**\n * Load an HTML string into a single {@link RagDocument} of readable text.\n * Scripts, styles, and other non-prose elements are dropped content-and-all,\n * block tags become line breaks (so paragraph structure survives for the\n * splitter), remaining tags are stripped, and HTML entities are decoded — a\n * lightweight regex pass, no heavy DOM dependency.\n *\n * The document's `metadata.title` is set from the page's `<title>` (unless\n * the caller overrode it), and `metadata.loader` is `\"html\"`. The output is\n * the exact shape `index()` consumes.\n *\n * @example\n * const kb = ai.rag({ embedder, store });\n * await kb.index(loadHtml(rawHtmlString, { id: \"landing-page\" }));\n *\n * @param html - The raw HTML markup.\n * @param options - Shared `id` / `metadata` / `tags` ({@link LoadHtmlOptions}).\n * @returns A {@link RagLoaderResult} (one document) ready for `rag.index()`.\n */\nexport function loadHtml(\n  html: string,\n  options: LoadHtmlOptions = {},\n): RagLoaderResult {\n  const id = options.id ?? DEFAULT_ID;\n  const title = extractTitle(html);\n  const text = htmlToText(html);\n\n  // An all-markup / empty page strips to nothing; emit no document so\n  // index() never receives a no-op record (matches loadText's behavior).\n  if (text.length === 0) {\n    return [];\n  }\n\n  // Derived keys (source, loader, title) sit UNDER the caller's metadata so\n  // an explicit override always wins.\n  const doc: RagDocument = {\n    id,\n    text,\n    metadata: {\n      source: id,\n      loader: \"html\",\n      ...(title !== undefined ? { title } : {}),\n      ...options.metadata,\n    },\n    tags: options.tags,\n  };\n\n  return [doc];\n}\n\n/** Internal — exported for the web loader so it shares the exact strip pass. */\nexport { htmlToText, extractTitle };\n"],"mappings":";;AAIA,MAAM,aAAa;;;;;;;AAQnB,MAAM,oBAAoB;CACxB;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;AAQA,MAAM,aACJ;;AAGF,MAAM,iBAAyC;CAC7C,KAAK;CACL,IAAI;CACJ,IAAI;CACJ,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,KAAK;CACL,OAAO;CACP,QAAQ;CACR,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,QAAQ;CACR,MAAM;AACR;;;;;;AAOA,SAAS,eAAe,MAAsB;CAC5C,OAAO,KAAK,QAAQ,sCAAsC,OAAO,SAAiB;EAChF,IAAI,KAAK,OAAO,KAAK;GACnB,MAAM,YACJ,KAAK,OAAO,OAAO,KAAK,OAAO,MAC3B,OAAO,SAAS,KAAK,MAAM,CAAC,GAAG,EAAE,IACjC,OAAO,SAAS,KAAK,MAAM,CAAC,GAAG,EAAE;GAEvC,IAAI,OAAO,MAAM,SAAS,KAAK,YAAY,KAAK,YAAY,SAC1D,OAAO;GAGT,IAAI;IACF,OAAO,OAAO,cAAc,SAAS;GACvC,QAAQ;IACN,OAAO;GACT;EACF;EAIA,OAFc,eAAe,KAAK,YAAY,MAE9B;CAClB,CAAC;AACH;;;;;AAMA,SAAS,aAAa,MAAkC;CACtD,MAAM,QAAQ,mCAAmC,KAAK,IAAI;CAE1D,IAAI,CAAC,OACH;CAGF,MAAM,QAAQ,eAAe,MAAM,EAAE,CAAC,CAAC,QAAQ,QAAQ,GAAG,CAAC,CAAC,KAAK;CAEjE,OAAO,MAAM,SAAS,IAAI,QAAQ;AACpC;;;;;;;;;AAUA,SAAS,WAAW,MAAsB;CACxC,IAAI,OAAO;CAGX,OAAO,KAAK,QAAQ,oBAAoB,GAAG;CAG3C,KAAK,MAAM,OAAO,mBAAmB;EACnC,MAAM,UAAU,IAAI,OAAO,IAAI,IAAI,yBAAyB,IAAI,IAAI,IAAI;EACxE,OAAO,KAAK,QAAQ,SAAS,GAAG;EAEhC,OAAO,KAAK,QAAQ,IAAI,OAAO,QAAQ,IAAI,YAAY,IAAI,GAAG,GAAG;CACnE;CAGA,OAAO,KAAK,QAAQ,YAAY,IAAI;CAGpC,OAAO,KAAK,QAAQ,YAAY,EAAE;CAGlC,OAAO,eAAe,IAAI;CAI1B,OAAO,KACJ,QAAQ,aAAa,GAAG,CAAC,CACzB,QAAQ,mBAAmB,IAAI,CAAC,CAChC,QAAQ,WAAW,MAAM,CAAC,CAC1B,KAAK;CAER,OAAO;AACT;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,SACd,MACA,UAA2B,CAAC,GACX;CACjB,MAAM,KAAK,QAAQ,MAAM;CACzB,MAAM,QAAQ,aAAa,IAAI;CAC/B,MAAM,OAAO,WAAW,IAAI;CAI5B,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAiBV,OAAO,CAAC;EAXN;EACA;EACA,UAAU;GACR,QAAQ;GACR,QAAQ;GACR,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC;GACvC,GAAG,QAAQ;EACb;EACA,MAAM,QAAQ;CAGN,CAAC;AACb"}

package/esm/rag/loaders/load-pdf.d.mts

@@ -1,6 +1,6 @@
 import { LoadPdfOptions, RagLoaderResult } from "./loader.type.mjs";
 
-//#region ../@warlock.js/ai/src/rag/loaders/load-pdf.d.ts
+//#region ../ai/src/rag/loaders/load-pdf.d.ts
 /**
  * Load a PDF's bytes into {@link RagDocument}(s) via the OPTIONAL `pdf-parse`
  * peer. The peer is resolved lazily on the FIRST call (not at import) so

package/esm/rag/loaders/load-pdf.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"load-pdf.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/load-pdf.ts"],"mappings":";;;;;AA8HA;;;;;;;;;;;;;;;;;;;;AAG0B;;;;;;;;;iBAHJ,OAAA,CACpB,KAAA,EAAO,MAAA,GAAS,WAAA,GAAc,UAAA,EAC9B,OAAA,GAAS,cAAA,GACR,OAAA,CAAQ,eAAA"}
+{"version":3,"file":"load-pdf.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-pdf.ts"],"mappings":";;;;;AA8HA;;;;;;;;;;;;;;;;;;;;AAG0B;;;;;;;;;iBAHJ,OAAA,CACpB,KAAA,EAAO,MAAA,GAAS,WAAA,GAAc,UAAA,EAC9B,OAAA,GAAS,cAAA,GACR,OAAA,CAAQ,eAAA"}

package/esm/rag/loaders/load-pdf.mjs

@@ -1,6 +1,6 @@
 import { PDF_PARSE_INSTALL_INSTRUCTIONS } from "./errors.mjs";
 
-//#region ../@warlock.js/ai/src/rag/loaders/load-pdf.ts
+//#region ../ai/src/rag/loaders/load-pdf.ts
 /** Default `id` when the caller supplies none. */
 const DEFAULT_ID = "document";
 let pdfParse;

package/esm/rag/loaders/load-pdf.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"load-pdf.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/load-pdf.ts"],"sourcesContent":["import type { RagDocument } from \"../contracts/rag-document.type\";\nimport { PDF_PARSE_INSTALL_INSTRUCTIONS } from \"./errors\";\nimport type { LoadPdfOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Default `id` when the caller supplies none. */\nconst DEFAULT_ID = \"document\";\n\n/**\n * The slice of `pdf-parse`'s result we consume. The peer returns more\n * (`info`, `metadata`, `version`); we only need the extracted `text` and\n * page count, so we type just those to keep the dependency at arm's length.\n */\ntype PdfParseResult = {\n  /** Concatenated text of every page. */\n  text: string;\n  /** Number of pages in the document. */\n  numpages: number;\n  /** Document info dictionary — `Title` lifted into metadata when present. */\n  info?: { Title?: string } & Record<string, unknown>;\n};\n\n/** The `pdf-parse` module's callable default export. */\ntype PdfParseFn = (\n  data: Buffer | Uint8Array,\n  options?: {\n    /**\n     * Per-page renderer `pdf-parse` calls once per page in document order and\n     * `await`s — may return the page text synchronously or as a promise.\n     */\n    pagerender?: (page: unknown) => string | Promise<string>;\n  },\n) => Promise<PdfParseResult>;\n\n// ============================================================\n// Lazily-loaded pdf-parse (OPTIONAL peer)\n// ============================================================\n\nlet pdfParse: PdfParseFn | undefined;\nlet isModuleExists: boolean | undefined;\nlet loadingPromise: Promise<void> | undefined;\n\n/**\n * Settle the lazy import of `pdf-parse` once, concurrency-safe. A bare\n * `catch` flips the flag to `false`; the curated\n * {@link PDF_PARSE_INSTALL_INSTRUCTIONS} surfaces at first\n * {@link loadPdf} call, never a raw module-resolution stack trace. Mirrors\n * the guard moderation detector's `loadOpenAi`.\n */\nfunction loadPdfParse(): Promise<void> {\n  if (isModuleExists !== undefined) {\n    return Promise.resolve();\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      // Literal specifier so `vi.mock(\"pdf-parse\")` can intercept it in tests.\n      // Typed via the ambient `pdf-parse` shim in this directory, so the bare\n      // import resolves even though the OPTIONAL peer is not a dependency.\n      const mod = (await import(\"pdf-parse\")) as {\n        default?: PdfParseFn;\n      } & Partial<PdfParseFn>;\n      // pdf-parse ships CommonJS — the callable is `module.exports`, surfaced\n      // as `default` under ESM interop. Fall back to the namespace itself for\n      // bundlers that hoist the callable to the top level.\n      pdfParse = mod.default ?? (mod as unknown as PdfParseFn);\n      isModuleExists = typeof pdfParse === \"function\";\n    } catch {\n      isModuleExists = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * Coerce a {@link RagDocument}-compatible binary input into a `Buffer` for\n * `pdf-parse`. Accepts a Node `Buffer`, an `ArrayBuffer`, or a typed array\n * (`Uint8Array`) — the shapes a file read / fetch body hands back.\n */\nfunction toBuffer(input: Buffer | ArrayBuffer | Uint8Array): Buffer {\n  if (Buffer.isBuffer(input)) {\n    return input;\n  }\n\n  if (input instanceof ArrayBuffer) {\n    return Buffer.from(input);\n  }\n\n  return Buffer.from(input.buffer, input.byteOffset, input.byteLength);\n}\n\n/**\n * Load a PDF's bytes into {@link RagDocument}(s) via the OPTIONAL `pdf-parse`\n * peer. The peer is resolved lazily on the FIRST call (not at import) so\n * importing `@warlock.js/ai` never forces it to be installed; when it is\n * absent the curated {@link PDF_PARSE_INSTALL_INSTRUCTIONS} is thrown as a\n * plain `Error` (a missing optional peer is an infrastructure fault, not a\n * content problem).\n *\n * By default the whole PDF becomes a single document carrying\n * `metadata.pageCount`. With `perPage: true`, each page becomes its own\n * document (`id` suffixed `#p<n>`, `metadata.page` set) so citations stay\n * page-precise. Document `metadata.title` comes from the PDF info\n * dictionary's `Title` (unless overridden), and `metadata.loader` is\n * `\"pdf\"`. The output is the exact shape `index()` consumes.\n *\n * @example\n * import { readFile } from \"node:fs/promises\";\n * const kb = ai.rag({ embedder, store });\n * await kb.index(await loadPdf(await readFile(\"guide.pdf\"), { id: \"guide\" }));\n *\n * @example\n * // One document per page for page-precise citations:\n * await kb.index(await loadPdf(bytes, { id: \"manual\", perPage: true }));\n *\n * @param input - The PDF bytes (`Buffer`, `ArrayBuffer`, or `Uint8Array`).\n * @param options - `perPage` plus shared `id` / `metadata` / `tags`\n *   ({@link LoadPdfOptions}).\n * @returns A {@link RagLoaderResult} ready for `rag.index()`.\n * @throws {Error} carrying {@link PDF_PARSE_INSTALL_INSTRUCTIONS} when the\n *   `pdf-parse` peer is not installed.\n */\nexport async function loadPdf(\n  input: Buffer | ArrayBuffer | Uint8Array,\n  options: LoadPdfOptions = {},\n): Promise<RagLoaderResult> {\n  await loadPdfParse();\n\n  if (!isModuleExists || !pdfParse) {\n    throw new Error(PDF_PARSE_INSTALL_INSTRUCTIONS);\n  }\n\n  const id = options.id ?? DEFAULT_ID;\n  const perPage = options.perPage ?? false;\n\n  if (perPage) {\n    return loadPerPage(input, id, options);\n  }\n\n  const parsed = await pdfParse(toBuffer(input));\n  const text = parsed.text.trim();\n  const title = parsed.info?.Title?.trim();\n\n  // An image-only / empty PDF extracts no text — emit nothing so index()\n  // never receives a no-op record.\n  if (text.length === 0) {\n    return [];\n  }\n\n  const doc: RagDocument = {\n    id,\n    text,\n    metadata: {\n      source: id,\n      loader: \"pdf\",\n      pageCount: parsed.numpages,\n      ...(title ? { title } : {}),\n      ...options.metadata,\n    },\n    tags: options.tags,\n  };\n\n  return [doc];\n}\n\n/** One page of a parsed PDF — the text-layer item list `pagerender` sees. */\ntype PdfPage = {\n  getTextContent: (\n    options?: unknown,\n  ) => Promise<{ items: { str: string }[] }>;\n};\n\n/**\n * Per-page variant: render each page separately via `pdf-parse`'s\n * `pagerender` hook, accumulating one document per non-empty page. Each\n * carries `metadata.page` (1-based) and `metadata.pageCount`, and its id is\n * the base id suffixed `#p<n>` so every page-document is distinctly\n * identified for citation.\n *\n * `pdf-parse` calls `pagerender` once per page in document order and\n * `await`s the returned string, so capturing each page's joined text content\n * here gives reliable page boundaries the concatenated `text` lacks.\n */\nasync function loadPerPage(\n  input: Buffer | ArrayBuffer | Uint8Array,\n  id: string,\n  options: LoadPdfOptions,\n): Promise<RagDocument[]> {\n  const pages: string[] = [];\n\n  const parsed = await pdfParse!(toBuffer(input), {\n    pagerender: async (page: unknown): Promise<string> => {\n      const rendered = await renderPage(page as PdfPage);\n      pages.push(rendered);\n      return rendered;\n    },\n  });\n\n  const title = parsed.info?.Title?.trim();\n  const docs: RagDocument[] = [];\n\n  pages.forEach((pageText, index) => {\n    const text = pageText.trim();\n\n    if (text.length === 0) {\n      return;\n    }\n\n    const pageNumber = index + 1;\n\n    docs.push({\n      id: `${id}#p${pageNumber}`,\n      text,\n      metadata: {\n        source: id,\n        loader: \"pdf\",\n        page: pageNumber,\n        pageCount: parsed.numpages,\n        ...(title ? { title } : {}),\n        ...options.metadata,\n      },\n      tags: options.tags,\n    });\n  });\n\n  return docs;\n}\n\n/**\n * Join a single page's text-layer items in reading order, inserting a space\n * between items so adjacent words do not run together. Mirrors the essence\n * of `pdf-parse`'s default renderer without depending on its internals, so\n * the per-page hook stays stable across `pdf-parse` versions. A page with no\n * text layer (scanned image) renders to an empty string and is dropped.\n */\nasync function renderPage(page: PdfPage): Promise<string> {\n  if (typeof page?.getTextContent !== \"function\") {\n    return \"\";\n  }\n\n  const content = await page.getTextContent({\n    normalizeWhitespace: true,\n    disableCombineTextItems: false,\n  });\n\n  return content.items\n    .map((item) => item.str)\n    .join(\" \")\n    .replace(/\\s+/g, \" \")\n    .trim();\n}\n"],"mappings":";;;;AAKA,MAAM,aAAa;AAgCnB,IAAI;AACJ,IAAI;AACJ,IAAI;;;;;;;;AASJ,SAAS,eAA8B;CACrC,IAAI,mBAAmB,QACrB,OAAO,QAAQ,QAAQ;CAGzB,IAAI,gBACF,OAAO;CAGT,kBAAkB,YAAY;EAC5B,IAAI;GAIF,MAAM,MAAO,MAAM,OAAO;GAM1B,WAAW,IAAI,WAAY;GAC3B,iBAAiB,OAAO,aAAa;EACvC,QAAQ;GACN,iBAAiB;EACnB;CACF,EAAC,CAAE;CAEH,OAAO;AACT;;;;;;AAOA,SAAS,SAAS,OAAkD;CAClE,IAAI,OAAO,SAAS,KAAK,GACvB,OAAO;CAGT,IAAI,iBAAiB,aACnB,OAAO,OAAO,KAAK,KAAK;CAG1B,OAAO,OAAO,KAAK,MAAM,QAAQ,MAAM,YAAY,MAAM,UAAU;AACrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,eAAsB,QACpB,OACA,UAA0B,CAAC,GACD;CAC1B,MAAM,aAAa;CAEnB,IAAI,CAAC,kBAAkB,CAAC,UACtB,MAAM,IAAI,MAAM,8BAA8B;CAGhD,MAAM,KAAK,QAAQ,MAAM;CAGzB,IAFgB,QAAQ,WAAW,OAGjC,OAAO,YAAY,OAAO,IAAI,OAAO;CAGvC,MAAM,SAAS,MAAM,SAAS,SAAS,KAAK,CAAC;CAC7C,MAAM,OAAO,OAAO,KAAK,KAAK;CAC9B,MAAM,QAAQ,OAAO,MAAM,OAAO,KAAK;CAIvC,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAgBV,OAAO,CAAC;EAZN;EACA;EACA,UAAU;GACR,QAAQ;GACR,QAAQ;GACR,WAAW,OAAO;GAClB,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;GACzB,GAAG,QAAQ;EACb;EACA,MAAM,QAAQ;CAGN,CAAC;AACb;;;;;;;;;;;;AAoBA,eAAe,YACb,OACA,IACA,SACwB;CACxB,MAAM,QAAkB,CAAC;CAEzB,MAAM,SAAS,MAAM,SAAU,SAAS,KAAK,GAAG,EAC9C,YAAY,OAAO,SAAmC;EACpD,MAAM,WAAW,MAAM,WAAW,IAAe;EACjD,MAAM,KAAK,QAAQ;EACnB,OAAO;CACT,EACF,CAAC;CAED,MAAM,QAAQ,OAAO,MAAM,OAAO,KAAK;CACvC,MAAM,OAAsB,CAAC;CAE7B,MAAM,SAAS,UAAU,UAAU;EACjC,MAAM,OAAO,SAAS,KAAK;EAE3B,IAAI,KAAK,WAAW,GAClB;EAGF,MAAM,aAAa,QAAQ;EAE3B,KAAK,KAAK;GACR,IAAI,GAAG,GAAG,IAAI;GACd;GACA,UAAU;IACR,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,WAAW,OAAO;IAClB,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;IACzB,GAAG,QAAQ;GACb;GACA,MAAM,QAAQ;EAChB,CAAC;CACH,CAAC;CAED,OAAO;AACT;;;;;;;;AASA,eAAe,WAAW,MAAgC;CACxD,IAAI,OAAO,MAAM,mBAAmB,YAClC,OAAO;CAQT,QAAO,MALe,KAAK,eAAe;EACxC,qBAAqB;EACrB,yBAAyB;CAC3B,CAAC,EAEa,CAAC,MACZ,KAAK,SAAS,KAAK,GAAG,CAAC,CACvB,KAAK,GAAG,CAAC,CACT,QAAQ,QAAQ,GAAG,CAAC,CACpB,KAAK;AACV"}
+{"version":3,"file":"load-pdf.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-pdf.ts"],"sourcesContent":["import type { RagDocument } from \"../contracts/rag-document.type\";\nimport { PDF_PARSE_INSTALL_INSTRUCTIONS } from \"./errors\";\nimport type { LoadPdfOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Default `id` when the caller supplies none. */\nconst DEFAULT_ID = \"document\";\n\n/**\n * The slice of `pdf-parse`'s result we consume. The peer returns more\n * (`info`, `metadata`, `version`); we only need the extracted `text` and\n * page count, so we type just those to keep the dependency at arm's length.\n */\ntype PdfParseResult = {\n  /** Concatenated text of every page. */\n  text: string;\n  /** Number of pages in the document. */\n  numpages: number;\n  /** Document info dictionary — `Title` lifted into metadata when present. */\n  info?: { Title?: string } & Record<string, unknown>;\n};\n\n/** The `pdf-parse` module's callable default export. */\ntype PdfParseFn = (\n  data: Buffer | Uint8Array,\n  options?: {\n    /**\n     * Per-page renderer `pdf-parse` calls once per page in document order and\n     * `await`s — may return the page text synchronously or as a promise.\n     */\n    pagerender?: (page: unknown) => string | Promise<string>;\n  },\n) => Promise<PdfParseResult>;\n\n// ============================================================\n// Lazily-loaded pdf-parse (OPTIONAL peer)\n// ============================================================\n\nlet pdfParse: PdfParseFn | undefined;\nlet isModuleExists: boolean | undefined;\nlet loadingPromise: Promise<void> | undefined;\n\n/**\n * Settle the lazy import of `pdf-parse` once, concurrency-safe. A bare\n * `catch` flips the flag to `false`; the curated\n * {@link PDF_PARSE_INSTALL_INSTRUCTIONS} surfaces at first\n * {@link loadPdf} call, never a raw module-resolution stack trace. Mirrors\n * the guard moderation detector's `loadOpenAi`.\n */\nfunction loadPdfParse(): Promise<void> {\n  if (isModuleExists !== undefined) {\n    return Promise.resolve();\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      // Literal specifier so `vi.mock(\"pdf-parse\")` can intercept it in tests.\n      // Typed via the ambient `pdf-parse` shim in this directory, so the bare\n      // import resolves even though the OPTIONAL peer is not a dependency.\n      const mod = (await import(\"pdf-parse\")) as {\n        default?: PdfParseFn;\n      } & Partial<PdfParseFn>;\n      // pdf-parse ships CommonJS — the callable is `module.exports`, surfaced\n      // as `default` under ESM interop. Fall back to the namespace itself for\n      // bundlers that hoist the callable to the top level.\n      pdfParse = mod.default ?? (mod as unknown as PdfParseFn);\n      isModuleExists = typeof pdfParse === \"function\";\n    } catch {\n      isModuleExists = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * Coerce a {@link RagDocument}-compatible binary input into a `Buffer` for\n * `pdf-parse`. Accepts a Node `Buffer`, an `ArrayBuffer`, or a typed array\n * (`Uint8Array`) — the shapes a file read / fetch body hands back.\n */\nfunction toBuffer(input: Buffer | ArrayBuffer | Uint8Array): Buffer {\n  if (Buffer.isBuffer(input)) {\n    return input;\n  }\n\n  if (input instanceof ArrayBuffer) {\n    return Buffer.from(input);\n  }\n\n  return Buffer.from(input.buffer, input.byteOffset, input.byteLength);\n}\n\n/**\n * Load a PDF's bytes into {@link RagDocument}(s) via the OPTIONAL `pdf-parse`\n * peer. The peer is resolved lazily on the FIRST call (not at import) so\n * importing `@warlock.js/ai` never forces it to be installed; when it is\n * absent the curated {@link PDF_PARSE_INSTALL_INSTRUCTIONS} is thrown as a\n * plain `Error` (a missing optional peer is an infrastructure fault, not a\n * content problem).\n *\n * By default the whole PDF becomes a single document carrying\n * `metadata.pageCount`. With `perPage: true`, each page becomes its own\n * document (`id` suffixed `#p<n>`, `metadata.page` set) so citations stay\n * page-precise. Document `metadata.title` comes from the PDF info\n * dictionary's `Title` (unless overridden), and `metadata.loader` is\n * `\"pdf\"`. The output is the exact shape `index()` consumes.\n *\n * @example\n * import { readFile } from \"node:fs/promises\";\n * const kb = ai.rag({ embedder, store });\n * await kb.index(await loadPdf(await readFile(\"guide.pdf\"), { id: \"guide\" }));\n *\n * @example\n * // One document per page for page-precise citations:\n * await kb.index(await loadPdf(bytes, { id: \"manual\", perPage: true }));\n *\n * @param input - The PDF bytes (`Buffer`, `ArrayBuffer`, or `Uint8Array`).\n * @param options - `perPage` plus shared `id` / `metadata` / `tags`\n *   ({@link LoadPdfOptions}).\n * @returns A {@link RagLoaderResult} ready for `rag.index()`.\n * @throws {Error} carrying {@link PDF_PARSE_INSTALL_INSTRUCTIONS} when the\n *   `pdf-parse` peer is not installed.\n */\nexport async function loadPdf(\n  input: Buffer | ArrayBuffer | Uint8Array,\n  options: LoadPdfOptions = {},\n): Promise<RagLoaderResult> {\n  await loadPdfParse();\n\n  if (!isModuleExists || !pdfParse) {\n    throw new Error(PDF_PARSE_INSTALL_INSTRUCTIONS);\n  }\n\n  const id = options.id ?? DEFAULT_ID;\n  const perPage = options.perPage ?? false;\n\n  if (perPage) {\n    return loadPerPage(input, id, options);\n  }\n\n  const parsed = await pdfParse(toBuffer(input));\n  const text = parsed.text.trim();\n  const title = parsed.info?.Title?.trim();\n\n  // An image-only / empty PDF extracts no text — emit nothing so index()\n  // never receives a no-op record.\n  if (text.length === 0) {\n    return [];\n  }\n\n  const doc: RagDocument = {\n    id,\n    text,\n    metadata: {\n      source: id,\n      loader: \"pdf\",\n      pageCount: parsed.numpages,\n      ...(title ? { title } : {}),\n      ...options.metadata,\n    },\n    tags: options.tags,\n  };\n\n  return [doc];\n}\n\n/** One page of a parsed PDF — the text-layer item list `pagerender` sees. */\ntype PdfPage = {\n  getTextContent: (\n    options?: unknown,\n  ) => Promise<{ items: { str: string }[] }>;\n};\n\n/**\n * Per-page variant: render each page separately via `pdf-parse`'s\n * `pagerender` hook, accumulating one document per non-empty page. Each\n * carries `metadata.page` (1-based) and `metadata.pageCount`, and its id is\n * the base id suffixed `#p<n>` so every page-document is distinctly\n * identified for citation.\n *\n * `pdf-parse` calls `pagerender` once per page in document order and\n * `await`s the returned string, so capturing each page's joined text content\n * here gives reliable page boundaries the concatenated `text` lacks.\n */\nasync function loadPerPage(\n  input: Buffer | ArrayBuffer | Uint8Array,\n  id: string,\n  options: LoadPdfOptions,\n): Promise<RagDocument[]> {\n  const pages: string[] = [];\n\n  const parsed = await pdfParse!(toBuffer(input), {\n    pagerender: async (page: unknown): Promise<string> => {\n      const rendered = await renderPage(page as PdfPage);\n      pages.push(rendered);\n      return rendered;\n    },\n  });\n\n  const title = parsed.info?.Title?.trim();\n  const docs: RagDocument[] = [];\n\n  pages.forEach((pageText, index) => {\n    const text = pageText.trim();\n\n    if (text.length === 0) {\n      return;\n    }\n\n    const pageNumber = index + 1;\n\n    docs.push({\n      id: `${id}#p${pageNumber}`,\n      text,\n      metadata: {\n        source: id,\n        loader: \"pdf\",\n        page: pageNumber,\n        pageCount: parsed.numpages,\n        ...(title ? { title } : {}),\n        ...options.metadata,\n      },\n      tags: options.tags,\n    });\n  });\n\n  return docs;\n}\n\n/**\n * Join a single page's text-layer items in reading order, inserting a space\n * between items so adjacent words do not run together. Mirrors the essence\n * of `pdf-parse`'s default renderer without depending on its internals, so\n * the per-page hook stays stable across `pdf-parse` versions. A page with no\n * text layer (scanned image) renders to an empty string and is dropped.\n */\nasync function renderPage(page: PdfPage): Promise<string> {\n  if (typeof page?.getTextContent !== \"function\") {\n    return \"\";\n  }\n\n  const content = await page.getTextContent({\n    normalizeWhitespace: true,\n    disableCombineTextItems: false,\n  });\n\n  return content.items\n    .map((item) => item.str)\n    .join(\" \")\n    .replace(/\\s+/g, \" \")\n    .trim();\n}\n"],"mappings":";;;;AAKA,MAAM,aAAa;AAgCnB,IAAI;AACJ,IAAI;AACJ,IAAI;;;;;;;;AASJ,SAAS,eAA8B;CACrC,IAAI,mBAAmB,QACrB,OAAO,QAAQ,QAAQ;CAGzB,IAAI,gBACF,OAAO;CAGT,kBAAkB,YAAY;EAC5B,IAAI;GAIF,MAAM,MAAO,MAAM,OAAO;GAM1B,WAAW,IAAI,WAAY;GAC3B,iBAAiB,OAAO,aAAa;EACvC,QAAQ;GACN,iBAAiB;EACnB;CACF,EAAC,CAAE;CAEH,OAAO;AACT;;;;;;AAOA,SAAS,SAAS,OAAkD;CAClE,IAAI,OAAO,SAAS,KAAK,GACvB,OAAO;CAGT,IAAI,iBAAiB,aACnB,OAAO,OAAO,KAAK,KAAK;CAG1B,OAAO,OAAO,KAAK,MAAM,QAAQ,MAAM,YAAY,MAAM,UAAU;AACrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,eAAsB,QACpB,OACA,UAA0B,CAAC,GACD;CAC1B,MAAM,aAAa;CAEnB,IAAI,CAAC,kBAAkB,CAAC,UACtB,MAAM,IAAI,MAAM,8BAA8B;CAGhD,MAAM,KAAK,QAAQ,MAAM;CAGzB,IAFgB,QAAQ,WAAW,OAGjC,OAAO,YAAY,OAAO,IAAI,OAAO;CAGvC,MAAM,SAAS,MAAM,SAAS,SAAS,KAAK,CAAC;CAC7C,MAAM,OAAO,OAAO,KAAK,KAAK;CAC9B,MAAM,QAAQ,OAAO,MAAM,OAAO,KAAK;CAIvC,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAgBV,OAAO,CAAC;EAZN;EACA;EACA,UAAU;GACR,QAAQ;GACR,QAAQ;GACR,WAAW,OAAO;GAClB,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;GACzB,GAAG,QAAQ;EACb;EACA,MAAM,QAAQ;CAGN,CAAC;AACb;;;;;;;;;;;;AAoBA,eAAe,YACb,OACA,IACA,SACwB;CACxB,MAAM,QAAkB,CAAC;CAEzB,MAAM,SAAS,MAAM,SAAU,SAAS,KAAK,GAAG,EAC9C,YAAY,OAAO,SAAmC;EACpD,MAAM,WAAW,MAAM,WAAW,IAAe;EACjD,MAAM,KAAK,QAAQ;EACnB,OAAO;CACT,EACF,CAAC;CAED,MAAM,QAAQ,OAAO,MAAM,OAAO,KAAK;CACvC,MAAM,OAAsB,CAAC;CAE7B,MAAM,SAAS,UAAU,UAAU;EACjC,MAAM,OAAO,SAAS,KAAK;EAE3B,IAAI,KAAK,WAAW,GAClB;EAGF,MAAM,aAAa,QAAQ;EAE3B,KAAK,KAAK;GACR,IAAI,GAAG,GAAG,IAAI;GACd;GACA,UAAU;IACR,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,WAAW,OAAO;IAClB,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;IACzB,GAAG,QAAQ;GACb;GACA,MAAM,QAAQ;EAChB,CAAC;CACH,CAAC;CAED,OAAO;AACT;;;;;;;;AASA,eAAe,WAAW,MAAgC;CACxD,IAAI,OAAO,MAAM,mBAAmB,YAClC,OAAO;CAQT,QAAO,MALe,KAAK,eAAe;EACxC,qBAAqB;EACrB,yBAAyB;CAC3B,CAAC,EAEa,CAAC,MACZ,KAAK,SAAS,KAAK,GAAG,CAAC,CACvB,KAAK,GAAG,CAAC,CACT,QAAQ,QAAQ,GAAG,CAAC,CACpB,KAAK;AACV"}

package/esm/rag/loaders/load-text.d.mts

@@ -1,6 +1,6 @@
 import { LoadTextOptions, RagLoaderResult } from "./loader.type.mjs";
 
-//#region ../@warlock.js/ai/src/rag/loaders/load-text.d.ts
+//#region ../ai/src/rag/loaders/load-text.d.ts
 /**
  * One raw text item — a bare string, or a `{ id, text, … }` record giving the
  * item its own id / metadata / tags. Passing records lets a single

package/esm/rag/loaders/load-text.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"load-text.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/load-text.ts"],"mappings":";;;;;AAYA;;;;KAAY,SAAA;EAMN,sEAFA,EAAA,WAIW;EAFX,IAAA,UAII;EAFJ,QAAA,GAAW,MAAM,mBAiCP;EA/BV,IAAA;AAAA;;;;;;;;;;;;;;AAkCY;;;;;;;;;;;;;;;iBAHF,QAAA,CACd,KAAA,EAAO,SAAA,GAAY,SAAA,IACnB,OAAA,GAAS,eAAA,GACR,eAAA"}
+{"version":3,"file":"load-text.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-text.ts"],"mappings":";;;;;AAYA;;;;KAAY,SAAA;EAMN,sEAFA,EAAA,WAIW;EAFX,IAAA,UAII;EAFJ,QAAA,GAAW,MAAM,mBAiCP;EA/BV,IAAA;AAAA;;;;;;;;;;;;;;AAkCY;;;;;;;;;;;;;;;iBAHF,QAAA,CACd,KAAA,EAAO,SAAA,GAAY,SAAA,IACnB,OAAA,GAAS,eAAA,GACR,eAAA"}

package/esm/rag/loaders/load-text.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/rag/loaders/load-text.ts
+//#region ../ai/src/rag/loaders/load-text.ts
 /** Default `id` when the caller supplies neither `id` nor an item id. */
 const DEFAULT_ID = "document";
 /**

package/esm/rag/loaders/load-text.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"load-text.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/load-text.ts"],"sourcesContent":["import type { RagDocument } from \"../contracts/rag-document.type\";\nimport type { LoadTextOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Default `id` when the caller supplies neither `id` nor an item id. */\nconst DEFAULT_ID = \"document\";\n\n/**\n * One raw text item — a bare string, or a `{ id, text, … }` record giving the\n * item its own id / metadata / tags. Passing records lets a single\n * {@link loadText} call turn many strings into many distinctly-identified\n * {@link RagDocument}s.\n */\nexport type TextInput =\n  | string\n  | {\n      /** Stable id for this item. Falls back to the option `id` + index. */\n      id?: string;\n      /** The text body. */\n      text: string;\n      /** Per-item metadata, merged under the shared option `metadata`. */\n      metadata?: Record<string, unknown>;\n      /** Per-item tags (override the shared option `tags` when present). */\n      tags?: string[];\n    };\n\n/**\n * Load plain text into {@link RagDocument}(s) — the zero-dependency base\n * loader every other loader ultimately funnels into. Accepts a single\n * string, a single `{ id, text }` record, or an array mixing both; each\n * input becomes one document carrying `metadata.loader = \"text\"` plus a\n * `metadata.source` (the resolved id).\n *\n * Caller `metadata` always wins over the loader-derived keys, and per-item\n * `metadata` / `tags` (when an item is a record) layer on top of the shared\n * option values. Empty / whitespace-only items are dropped — they would\n * chunk to nothing anyway, so the result never carries a no-op document.\n *\n * The output is the exact shape `index()` consumes:\n *\n * @example\n * const kb = ai.rag({ embedder, store });\n * await kb.index(loadText(\"a long string of notes…\"));\n *\n * @example\n * await kb.index(loadText([\n *   { id: \"faq-1\", text: \"…\", metadata: { section: \"billing\" } },\n *   { id: \"faq-2\", text: \"…\" },\n * ]));\n *\n * @param input - A string, a `{ id, text }` record, or an array of either.\n * @param options - Shared `id` / `metadata` / `tags` ({@link LoadTextOptions}).\n * @returns A {@link RagLoaderResult} ready to hand to `rag.index()`.\n */\nexport function loadText(\n  input: TextInput | TextInput[],\n  options: LoadTextOptions = {},\n): RagLoaderResult {\n  const items = Array.isArray(input) ? input : [input];\n  const baseId = options.id ?? DEFAULT_ID;\n  const multiple = items.length > 1;\n\n  const docs: RagDocument[] = [];\n\n  items.forEach((item, index) => {\n    const text = typeof item === \"string\" ? item : item.text;\n\n    // Drop empties up front — they chunk to nothing, so emitting them would\n    // only add a no-op document for index() to skip.\n    if (text.trim().length === 0) {\n      return;\n    }\n\n    const itemId =\n      typeof item === \"string\" ? undefined : item.id;\n    // A single input keeps the bare base id; multiple inputs are suffixed so\n    // every emitted document has a distinct, stable id.\n    const id = itemId ?? (multiple ? `${baseId}#${index}` : baseId);\n\n    const itemMetadata =\n      typeof item === \"string\" ? undefined : item.metadata;\n    const itemTags = typeof item === \"string\" ? undefined : item.tags;\n\n    docs.push({\n      id,\n      text,\n      // Loader-derived keys first, then the shared option metadata, then the\n      // per-item metadata — caller intent always overrides the derived keys.\n      metadata: {\n        source: id,\n        loader: \"text\",\n        ...options.metadata,\n        ...itemMetadata,\n      },\n      tags: itemTags ?? options.tags,\n    });\n  });\n\n  return docs;\n}\n"],"mappings":";;AAIA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDnB,SAAgB,SACd,OACA,UAA2B,CAAC,GACX;CACjB,MAAM,QAAQ,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;CACnD,MAAM,SAAS,QAAQ,MAAM;CAC7B,MAAM,WAAW,MAAM,SAAS;CAEhC,MAAM,OAAsB,CAAC;CAE7B,MAAM,SAAS,MAAM,UAAU;EAC7B,MAAM,OAAO,OAAO,SAAS,WAAW,OAAO,KAAK;EAIpD,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GACzB;EAOF,MAAM,MAHJ,OAAO,SAAS,WAAW,SAAY,KAAK,QAGxB,WAAW,GAAG,OAAO,GAAG,UAAU;EAExD,MAAM,eACJ,OAAO,SAAS,WAAW,SAAY,KAAK;EAC9C,MAAM,WAAW,OAAO,SAAS,WAAW,SAAY,KAAK;EAE7D,KAAK,KAAK;GACR;GACA;GAGA,UAAU;IACR,QAAQ;IACR,QAAQ;IACR,GAAG,QAAQ;IACX,GAAG;GACL;GACA,MAAM,YAAY,QAAQ;EAC5B,CAAC;CACH,CAAC;CAED,OAAO;AACT"}
+{"version":3,"file":"load-text.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-text.ts"],"sourcesContent":["import type { RagDocument } from \"../contracts/rag-document.type\";\nimport type { LoadTextOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Default `id` when the caller supplies neither `id` nor an item id. */\nconst DEFAULT_ID = \"document\";\n\n/**\n * One raw text item — a bare string, or a `{ id, text, … }` record giving the\n * item its own id / metadata / tags. Passing records lets a single\n * {@link loadText} call turn many strings into many distinctly-identified\n * {@link RagDocument}s.\n */\nexport type TextInput =\n  | string\n  | {\n      /** Stable id for this item. Falls back to the option `id` + index. */\n      id?: string;\n      /** The text body. */\n      text: string;\n      /** Per-item metadata, merged under the shared option `metadata`. */\n      metadata?: Record<string, unknown>;\n      /** Per-item tags (override the shared option `tags` when present). */\n      tags?: string[];\n    };\n\n/**\n * Load plain text into {@link RagDocument}(s) — the zero-dependency base\n * loader every other loader ultimately funnels into. Accepts a single\n * string, a single `{ id, text }` record, or an array mixing both; each\n * input becomes one document carrying `metadata.loader = \"text\"` plus a\n * `metadata.source` (the resolved id).\n *\n * Caller `metadata` always wins over the loader-derived keys, and per-item\n * `metadata` / `tags` (when an item is a record) layer on top of the shared\n * option values. Empty / whitespace-only items are dropped — they would\n * chunk to nothing anyway, so the result never carries a no-op document.\n *\n * The output is the exact shape `index()` consumes:\n *\n * @example\n * const kb = ai.rag({ embedder, store });\n * await kb.index(loadText(\"a long string of notes…\"));\n *\n * @example\n * await kb.index(loadText([\n *   { id: \"faq-1\", text: \"…\", metadata: { section: \"billing\" } },\n *   { id: \"faq-2\", text: \"…\" },\n * ]));\n *\n * @param input - A string, a `{ id, text }` record, or an array of either.\n * @param options - Shared `id` / `metadata` / `tags` ({@link LoadTextOptions}).\n * @returns A {@link RagLoaderResult} ready to hand to `rag.index()`.\n */\nexport function loadText(\n  input: TextInput | TextInput[],\n  options: LoadTextOptions = {},\n): RagLoaderResult {\n  const items = Array.isArray(input) ? input : [input];\n  const baseId = options.id ?? DEFAULT_ID;\n  const multiple = items.length > 1;\n\n  const docs: RagDocument[] = [];\n\n  items.forEach((item, index) => {\n    const text = typeof item === \"string\" ? item : item.text;\n\n    // Drop empties up front — they chunk to nothing, so emitting them would\n    // only add a no-op document for index() to skip.\n    if (text.trim().length === 0) {\n      return;\n    }\n\n    const itemId =\n      typeof item === \"string\" ? undefined : item.id;\n    // A single input keeps the bare base id; multiple inputs are suffixed so\n    // every emitted document has a distinct, stable id.\n    const id = itemId ?? (multiple ? `${baseId}#${index}` : baseId);\n\n    const itemMetadata =\n      typeof item === \"string\" ? undefined : item.metadata;\n    const itemTags = typeof item === \"string\" ? undefined : item.tags;\n\n    docs.push({\n      id,\n      text,\n      // Loader-derived keys first, then the shared option metadata, then the\n      // per-item metadata — caller intent always overrides the derived keys.\n      metadata: {\n        source: id,\n        loader: \"text\",\n        ...options.metadata,\n        ...itemMetadata,\n      },\n      tags: itemTags ?? options.tags,\n    });\n  });\n\n  return docs;\n}\n"],"mappings":";;AAIA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDnB,SAAgB,SACd,OACA,UAA2B,CAAC,GACX;CACjB,MAAM,QAAQ,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;CACnD,MAAM,SAAS,QAAQ,MAAM;CAC7B,MAAM,WAAW,MAAM,SAAS;CAEhC,MAAM,OAAsB,CAAC;CAE7B,MAAM,SAAS,MAAM,UAAU;EAC7B,MAAM,OAAO,OAAO,SAAS,WAAW,OAAO,KAAK;EAIpD,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GACzB;EAOF,MAAM,MAHJ,OAAO,SAAS,WAAW,SAAY,KAAK,QAGxB,WAAW,GAAG,OAAO,GAAG,UAAU;EAExD,MAAM,eACJ,OAAO,SAAS,WAAW,SAAY,KAAK;EAC9C,MAAM,WAAW,OAAO,SAAS,WAAW,SAAY,KAAK;EAE7D,KAAK,KAAK;GACR;GACA;GAGA,UAAU;IACR,QAAQ;IACR,QAAQ;IACR,GAAG,QAAQ;IACX,GAAG;GACL;GACA,MAAM,YAAY,QAAQ;EAC5B,CAAC;CACH,CAAC;CAED,OAAO;AACT"}

package/esm/rag/loaders/load-web.d.mts

@@ -1,6 +1,6 @@
 import { LoadWebOptions, RagLoaderResult } from "./loader.type.mjs";
 
-//#region ../@warlock.js/ai/src/rag/loaders/load-web.d.ts
+//#region ../ai/src/rag/loaders/load-web.d.ts
 /**
  * Fetch a URL through the SSRF-safe outbound policy and load it into a single
  * {@link RagDocument} of readable text. The fetch ALWAYS goes through

package/esm/rag/loaders/load-web.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"load-web.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/load-web.ts"],"mappings":";;;;;AAgEA;;;;;;;;;;;;;;AAG0B;;;;;;;;;;;;;;;;;;;iBAHJ,OAAA,CACpB,GAAA,UACA,OAAA,GAAS,cAAA,GACR,OAAA,CAAQ,eAAA"}
+{"version":3,"file":"load-web.d.mts","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-web.ts"],"mappings":";;;;;AAgEA;;;;;;;;;;;;;;AAG0B;;;;;;;;;;;;;;;;;;;iBAHJ,OAAA,CACpB,GAAA,UACA,OAAA,GAAS,cAAA,GACR,OAAA,CAAQ,eAAA"}

package/esm/rag/loaders/load-web.mjs

@@ -3,7 +3,7 @@ import "../../errors/index.mjs";
 import { guardedFetch, readTextCapped, resolveOutboundPolicy } from "../../security/outbound-policy.mjs";
 import { extractTitle, htmlToText } from "./load-html.mjs";
 
-//#region ../@warlock.js/ai/src/rag/loaders/load-web.ts
+//#region ../ai/src/rag/loaders/load-web.ts
 /** Browser-ish UA so servers that gate on it still return prose. */
 const DEFAULT_USER_AGENT = "warlock-ai-rag-loader/1.0 (+https://github.com/warlock-js)";
 /**

package/esm/rag/loaders/load-web.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"load-web.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/load-web.ts"],"sourcesContent":["import {\n  guardedFetch,\n  readTextCapped,\n  resolveOutboundPolicy,\n} from \"../../security/outbound-policy\";\nimport { OutboundPolicyError } from \"../../errors\";\nimport type { RagDocument } from \"../contracts/rag-document.type\";\nimport { htmlToText, extractTitle } from \"./load-html\";\nimport type { LoadWebOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Browser-ish UA so servers that gate on it still return prose. */\nconst DEFAULT_USER_AGENT =\n  \"warlock-ai-rag-loader/1.0 (+https://github.com/warlock-js)\";\n\n/**\n * Whether a `content-type` header names an HTML document (so it is run\n * through the tag-strip pass) versus already-plain text (used verbatim).\n */\nfunction isHtmlContentType(contentType: string | undefined): boolean {\n  if (!contentType) {\n    // No header — assume HTML, the common case for a fetched URL.\n    return true;\n  }\n\n  const lower = contentType.toLowerCase();\n\n  return lower.includes(\"text/html\") || lower.includes(\"application/xhtml\");\n}\n\n/**\n * Fetch a URL through the SSRF-safe outbound policy and load it into a single\n * {@link RagDocument} of readable text. The fetch ALWAYS goes through\n * `guardedFetch` — never a raw `fetch` — so the scheme allowlist, host\n * allowlist, post-DNS private-IP guard, timeout, and response-size cap from\n * {@link LoadWebOptions.policy} (or the strict defaults) always apply.\n *\n * HTML responses are run through the same tag-strip pass as {@link loadHtml}\n * (scripts/styles dropped, entities decoded, paragraph structure kept);\n * non-HTML text responses (`text/plain`, markdown, …) are used verbatim.\n * The document's `metadata.source` is the resolved URL, `metadata.title` is\n * the page `<title>` (HTML only, unless overridden), `metadata.contentType`\n * is the server-reported type, and `metadata.loader` is `\"web\"`.\n *\n * The output is the exact shape `index()` consumes, so a load feeds straight\n * in:\n *\n * @example\n * const kb = ai.rag({ embedder, store });\n * await kb.index(await loadWeb(\"https://example.com/guide\"));\n *\n * @example\n * // Tighten the SSRF policy to a single host:\n * await kb.index(await loadWeb(url, {\n *   policy: { hostAllowlist: [\"docs.example.com\"], maxBytes: 2_000_000 },\n *   tags: [\"docs\"],\n * }));\n *\n * @param url - The absolute URL to fetch. Validated by the outbound policy.\n * @param options - `policy` (the {@link OutboundPolicy}) plus shared\n *   `id` / `metadata` / `tags` ({@link LoadWebOptions}).\n * @returns A {@link RagLoaderResult} (one document) ready for `rag.index()`.\n * @throws {OutboundPolicyError} when the policy blocks the URL, the request\n *   times out, the body exceeds the cap, or the response is not OK.\n */\nexport async function loadWeb(\n  url: string,\n  options: LoadWebOptions = {},\n): Promise<RagLoaderResult> {\n  const policy = resolveOutboundPolicy(options.policy);\n\n  const response = await guardedFetch(url, policy, {\n    headers: { \"user-agent\": DEFAULT_USER_AGENT, accept: \"text/html,text/*\" },\n    redirect: \"follow\",\n  });\n\n  if (!response.ok) {\n    throw new OutboundPolicyError(\n      `loadWeb: fetching \"${url}\" returned ${response.status} ${response.statusText}`,\n      { context: { url, status: response.status } },\n    );\n  }\n\n  const contentType = response.headers.get(\"content-type\") ?? undefined;\n  const raw = await readTextCapped(response, policy.maxBytes);\n\n  const isHtml = isHtmlContentType(contentType);\n  const text = isHtml ? htmlToText(raw) : raw.trim();\n  const title = isHtml ? extractTitle(raw) : undefined;\n\n  const id = options.id ?? url;\n\n  // An empty body / all-markup page yields no document, so index() never\n  // receives a no-op record.\n  if (text.length === 0) {\n    return [];\n  }\n\n  // Derived keys sit UNDER the caller's metadata so an explicit override wins.\n  const doc: RagDocument = {\n    id,\n    text,\n    metadata: {\n      source: url,\n      loader: \"web\",\n      ...(title !== undefined ? { title } : {}),\n      ...(contentType !== undefined ? { contentType } : {}),\n      ...options.metadata,\n    },\n    tags: options.tags,\n  };\n\n  return [doc];\n}\n"],"mappings":";;;;;;;AAWA,MAAM,qBACJ;;;;;AAMF,SAAS,kBAAkB,aAA0C;CACnE,IAAI,CAAC,aAEH,OAAO;CAGT,MAAM,QAAQ,YAAY,YAAY;CAEtC,OAAO,MAAM,SAAS,WAAW,KAAK,MAAM,SAAS,mBAAmB;AAC1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,eAAsB,QACpB,KACA,UAA0B,CAAC,GACD;CAC1B,MAAM,SAAS,sBAAsB,QAAQ,MAAM;CAEnD,MAAM,WAAW,MAAM,aAAa,KAAK,QAAQ;EAC/C,SAAS;GAAE,cAAc;GAAoB,QAAQ;EAAmB;EACxE,UAAU;CACZ,CAAC;CAED,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,oBACR,sBAAsB,IAAI,aAAa,SAAS,OAAO,GAAG,SAAS,cACnE,EAAE,SAAS;EAAE;EAAK,QAAQ,SAAS;CAAO,EAAE,CAC9C;CAGF,MAAM,cAAc,SAAS,QAAQ,IAAI,cAAc,KAAK;CAC5D,MAAM,MAAM,MAAM,eAAe,UAAU,OAAO,QAAQ;CAE1D,MAAM,SAAS,kBAAkB,WAAW;CAC5C,MAAM,OAAO,SAAS,WAAW,GAAG,IAAI,IAAI,KAAK;CACjD,MAAM,QAAQ,SAAS,aAAa,GAAG,IAAI;CAE3C,MAAM,KAAK,QAAQ,MAAM;CAIzB,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAiBV,OAAO,CAAC;EAZN;EACA;EACA,UAAU;GACR,QAAQ;GACR,QAAQ;GACR,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC;GACvC,GAAI,gBAAgB,SAAY,EAAE,YAAY,IAAI,CAAC;GACnD,GAAG,QAAQ;EACb;EACA,MAAM,QAAQ;CAGN,CAAC;AACb"}
+{"version":3,"file":"load-web.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-web.ts"],"sourcesContent":["import {\n  guardedFetch,\n  readTextCapped,\n  resolveOutboundPolicy,\n} from \"../../security/outbound-policy\";\nimport { OutboundPolicyError } from \"../../errors\";\nimport type { RagDocument } from \"../contracts/rag-document.type\";\nimport { htmlToText, extractTitle } from \"./load-html\";\nimport type { LoadWebOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Browser-ish UA so servers that gate on it still return prose. */\nconst DEFAULT_USER_AGENT =\n  \"warlock-ai-rag-loader/1.0 (+https://github.com/warlock-js)\";\n\n/**\n * Whether a `content-type` header names an HTML document (so it is run\n * through the tag-strip pass) versus already-plain text (used verbatim).\n */\nfunction isHtmlContentType(contentType: string | undefined): boolean {\n  if (!contentType) {\n    // No header — assume HTML, the common case for a fetched URL.\n    return true;\n  }\n\n  const lower = contentType.toLowerCase();\n\n  return lower.includes(\"text/html\") || lower.includes(\"application/xhtml\");\n}\n\n/**\n * Fetch a URL through the SSRF-safe outbound policy and load it into a single\n * {@link RagDocument} of readable text. The fetch ALWAYS goes through\n * `guardedFetch` — never a raw `fetch` — so the scheme allowlist, host\n * allowlist, post-DNS private-IP guard, timeout, and response-size cap from\n * {@link LoadWebOptions.policy} (or the strict defaults) always apply.\n *\n * HTML responses are run through the same tag-strip pass as {@link loadHtml}\n * (scripts/styles dropped, entities decoded, paragraph structure kept);\n * non-HTML text responses (`text/plain`, markdown, …) are used verbatim.\n * The document's `metadata.source` is the resolved URL, `metadata.title` is\n * the page `<title>` (HTML only, unless overridden), `metadata.contentType`\n * is the server-reported type, and `metadata.loader` is `\"web\"`.\n *\n * The output is the exact shape `index()` consumes, so a load feeds straight\n * in:\n *\n * @example\n * const kb = ai.rag({ embedder, store });\n * await kb.index(await loadWeb(\"https://example.com/guide\"));\n *\n * @example\n * // Tighten the SSRF policy to a single host:\n * await kb.index(await loadWeb(url, {\n *   policy: { hostAllowlist: [\"docs.example.com\"], maxBytes: 2_000_000 },\n *   tags: [\"docs\"],\n * }));\n *\n * @param url - The absolute URL to fetch. Validated by the outbound policy.\n * @param options - `policy` (the {@link OutboundPolicy}) plus shared\n *   `id` / `metadata` / `tags` ({@link LoadWebOptions}).\n * @returns A {@link RagLoaderResult} (one document) ready for `rag.index()`.\n * @throws {OutboundPolicyError} when the policy blocks the URL, the request\n *   times out, the body exceeds the cap, or the response is not OK.\n */\nexport async function loadWeb(\n  url: string,\n  options: LoadWebOptions = {},\n): Promise<RagLoaderResult> {\n  const policy = resolveOutboundPolicy(options.policy);\n\n  const response = await guardedFetch(url, policy, {\n    headers: { \"user-agent\": DEFAULT_USER_AGENT, accept: \"text/html,text/*\" },\n    redirect: \"follow\",\n  });\n\n  if (!response.ok) {\n    throw new OutboundPolicyError(\n      `loadWeb: fetching \"${url}\" returned ${response.status} ${response.statusText}`,\n      { context: { url, status: response.status } },\n    );\n  }\n\n  const contentType = response.headers.get(\"content-type\") ?? undefined;\n  const raw = await readTextCapped(response, policy.maxBytes);\n\n  const isHtml = isHtmlContentType(contentType);\n  const text = isHtml ? htmlToText(raw) : raw.trim();\n  const title = isHtml ? extractTitle(raw) : undefined;\n\n  const id = options.id ?? url;\n\n  // An empty body / all-markup page yields no document, so index() never\n  // receives a no-op record.\n  if (text.length === 0) {\n    return [];\n  }\n\n  // Derived keys sit UNDER the caller's metadata so an explicit override wins.\n  const doc: RagDocument = {\n    id,\n    text,\n    metadata: {\n      source: url,\n      loader: \"web\",\n      ...(title !== undefined ? { title } : {}),\n      ...(contentType !== undefined ? { contentType } : {}),\n      ...options.metadata,\n    },\n    tags: options.tags,\n  };\n\n  return [doc];\n}\n"],"mappings":";;;;;;;AAWA,MAAM,qBACJ;;;;;AAMF,SAAS,kBAAkB,aAA0C;CACnE,IAAI,CAAC,aAEH,OAAO;CAGT,MAAM,QAAQ,YAAY,YAAY;CAEtC,OAAO,MAAM,SAAS,WAAW,KAAK,MAAM,SAAS,mBAAmB;AAC1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,eAAsB,QACpB,KACA,UAA0B,CAAC,GACD;CAC1B,MAAM,SAAS,sBAAsB,QAAQ,MAAM;CAEnD,MAAM,WAAW,MAAM,aAAa,KAAK,QAAQ;EAC/C,SAAS;GAAE,cAAc;GAAoB,QAAQ;EAAmB;EACxE,UAAU;CACZ,CAAC;CAED,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,oBACR,sBAAsB,IAAI,aAAa,SAAS,OAAO,GAAG,SAAS,cACnE,EAAE,SAAS;EAAE;EAAK,QAAQ,SAAS;CAAO,EAAE,CAC9C;CAGF,MAAM,cAAc,SAAS,QAAQ,IAAI,cAAc,KAAK;CAC5D,MAAM,MAAM,MAAM,eAAe,UAAU,OAAO,QAAQ;CAE1D,MAAM,SAAS,kBAAkB,WAAW;CAC5C,MAAM,OAAO,SAAS,WAAW,GAAG,IAAI,IAAI,KAAK;CACjD,MAAM,QAAQ,SAAS,aAAa,GAAG,IAAI;CAE3C,MAAM,KAAK,QAAQ,MAAM;CAIzB,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAiBV,OAAO,CAAC;EAZN;EACA;EACA,UAAU;GACR,QAAQ;GACR,QAAQ;GACR,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC;GACvC,GAAI,gBAAgB,SAAY,EAAE,YAAY,IAAI,CAAC;GACnD,GAAG,QAAQ;EACb;EACA,MAAM,QAAQ;CAGN,CAAC;AACb"}

package/esm/rag/loaders/loader.type.d.mts

@@ -1,7 +1,7 @@
 import { OutboundPolicy } from "../../security/outbound-policy.type.mjs";
 import { RagDocument } from "../contracts/rag-document.type.mjs";
 
-//#region ../@warlock.js/ai/src/rag/loaders/loader.type.d.ts
+//#region ../ai/src/rag/loaders/loader.type.d.ts
 /**
  * The shape every loader emits — the **exact** {@link RagDocument} (or array
  * of them) that `ai.rag(config).index()` consumes, so a load result is fed