@warlock.js/core 4.4.0 → 4.6.0

package/esm/ai/src/prompts/prompts-validate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts-validate.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/prompts/prompts-validate.ts"],"sourcesContent":["import { agent } from \"../agent/agent\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { ModelContract } from \"../contracts/model.contract\";\nimport type { SystemPromptContract } from \"../contracts/system-prompt.contract\";\nimport { judge } from \"../eval/judge-scorer\";\nimport { PROMPT_JUDGE_RUBRIC } from \"../prompt/prompt-validate\";\nimport type { PromptJudgeCacheLike } from \"./prompts-manager.type\";\n\n/**\n * Placeholder matcher — kept in lock-step with the matcher\n * `renderPlaceholders` (`src/system-prompt/render-placeholders.ts`) and the\n * legacy `prompt-validate` lint both use, so the deterministic validator sees\n * the exact same `{{key}}` / `{{a.b}}` / `{{key|default}}` set the renderer\n * substitutes. Global so every occurrence is collected.\n */\nconst PLACEHOLDER_PATTERN = /\\{\\{\\s*([^{}]+?)\\s*\\}\\}/g;\n\n/**\n * One parsed placeholder occurrence — the key path (the part before any\n * `|default`) and whether the occurrence carried an inline default.\n */\ntype ParsedPlaceholder = {\n  /** The dot-path key, e.g. `language` or `user.name`. */\n  readonly path: string;\n  /** Whether THIS occurrence declared an inline `{{key|default}}` fallback. */\n  readonly hasDefault: boolean;\n};\n\n/**\n * Collect every distinct placeholder occurrence from a template, in first-seen\n * order. A key is considered to \"have a default\" only when EVERY occurrence of\n * it carries one — a single bare `{{key}}` means the renderer can leave it\n * unresolved, so the key is still required.\n */\nfunction collectPlaceholders(template: string): ParsedPlaceholder[] {\n  const byPath = new Map<string, boolean>();\n  const order: string[] = [];\n\n  for (const match of template.matchAll(PLACEHOLDER_PATTERN)) {\n    const [rawPath, rawDefault] = match[1].split(\"|\");\n    const path = rawPath.trim();\n\n    if (path.length === 0) {\n      continue;\n    }\n\n    const hasDefault = rawDefault !== undefined;\n\n    if (!byPath.has(path)) {\n      byPath.set(path, hasDefault);\n      order.push(path);\n    } else {\n      // A key only counts as defaulted when ALL of its occurrences default.\n      byPath.set(path, (byPath.get(path) ?? false) && hasDefault);\n    }\n  }\n\n  return order.map(path => ({ path, hasDefault: byPath.get(path) ?? false }));\n}\n\n/**\n * Run the deterministic (model-free) half of validation over a resolved prompt\n * body. Reports every `{{key}}` placeholder that has NO inline default and is\n * neither supplied in `provided` nor declared in `declared` (the prompt's\n * `meta.required` plus any caller-declared keys).\n *\n * Pure and synchronous — the only required half of `validate`; the LLM-judge\n * half is optional and layered on top.\n *\n * @param text - The resolved prompt body (placeholders may still be present).\n * @param provided - Placeholder keys the caller has supplied a value for.\n * @param declared - Placeholder keys declared as known/required (e.g. `meta.required`).\n */\nexport function findMissingPlaceholders(\n  text: string,\n  provided: ReadonlySet<string>,\n  declared: ReadonlySet<string>,\n): string[] {\n  const missing: string[] = [];\n\n  for (const { path, hasDefault } of collectPlaceholders(text)) {\n    if (hasDefault) {\n      continue;\n    }\n\n    if (provided.has(path) || declared.has(path)) {\n      continue;\n    }\n\n    missing.push(path);\n  }\n\n  return missing;\n}\n\n/**\n * A `meta.required` key absent from the template entirely — declared as\n * required but never referenced — is itself a defect worth surfacing. Returns\n * the declared keys that appear nowhere in the body.\n */\nexport function findUnreferencedRequired(\n  text: string,\n  required: readonly string[],\n): string[] {\n  const present = new Set(collectPlaceholders(text).map(p => p.path));\n\n  return required.filter(key => !present.has(key));\n}\n\n/**\n * Build the one-shot judge agent the optional LLM-as-judge pass runs. Mirrors\n * the legacy `prompt.ts` judge agent (strict-JSON instruction so the verdict\n * parses even without an output schema), so the two validate paths share one\n * judging contract.\n */\nfunction buildJudgeAgent(model: ModelContract): AgentContract<unknown> {\n  return agent({\n    name: \"prompt-quality-judge\",\n    model,\n    systemPrompt:\n      \"You are a strict prompt-quality grader. Respond with JSON only: \" +\n      '{ \"score\": <0..1>, \"passed\": <true|false>, \"reason\": \"<short explanation>\" }.',\n  });\n}\n\n/** Outcome of the optional LLM-as-judge pass over a resolved prompt body. */\nexport type JudgeOutcome = {\n  /**\n   * The judge score in `[0, 1]`, or `undefined` when the judge degraded\n   * (errored, returned no parseable verdict, or threw) — never a misleading\n   * `0` masquerading as a real verdict.\n   */\n  readonly score?: number;\n  /** Human-readable issues raised by the judge (its reason, or a degrade note). */\n  readonly issues: string[];\n};\n\n/**\n * Run the optional LLM-as-judge pass over a resolved prompt body, REUSING the\n * eval `judge` scorer (the same path `prompt().validate` uses) so there is no\n * second judging implementation.\n *\n * **Nova-safe by contract.** The judge NEVER throws here: the eval scorer\n * already degrades a broken judge to `score: 0` with a failure reason, and any\n * exception that still escapes (model wiring, agent construction) is caught.\n * Both degrade paths surface `score: undefined` plus an issue note — so a flaky\n * judge can never fail an otherwise-valid prompt.\n *\n * @param text - The resolved prompt body under evaluation.\n * @param model - The model that powers the judge agent.\n */\nexport async function judgePromptBody(\n  text: string,\n  model: ModelContract,\n): Promise<JudgeOutcome> {\n  try {\n    const judgeAgent = buildJudgeAgent(model);\n    const scorer = judge({ agent: judgeAgent, rubric: PROMPT_JUDGE_RUBRIC });\n\n    const verdict = await scorer({\n      case: { name: \"prompt-quality\", input: \"Grade the system prompt below.\" },\n      text,\n      // `result` is unused by the judge scorer's prompt builder; a minimal\n      // stand-in keeps the structural contract satisfied without a real run.\n      result: { text } as never,\n      output: undefined,\n    });\n\n    // The eval scorer signals a degraded judge with score 0 + a diagnostic\n    // reason (\"judge failed: …\" / \"judge returned no parseable verdict\"). Treat\n    // that as \"no usable score\" rather than a real 0 verdict.\n    const degraded =\n      verdict.score === 0 &&\n      typeof verdict.reason === \"string\" &&\n      /^judge (failed|returned no parseable)/.test(verdict.reason);\n\n    if (degraded) {\n      return {\n        issues: [`LLM-judge unavailable: ${verdict.reason}`],\n      };\n    }\n\n    return {\n      score: verdict.score,\n      issues: verdict.reason ? [verdict.reason] : [],\n    };\n  } catch (error) {\n    // Last-resort guard: never let a judge failure throw out of validate().\n    const message = error instanceof Error ? error.message : String(error);\n\n    return {\n      issues: [`LLM-judge unavailable: ${message}`],\n    };\n  }\n}\n\n/**\n * Non-cryptographic 53-bit string hash (cyrb53) — deterministic across runs\n * and platforms, with no `node:crypto` dependency (keeps the validate path\n * usable in any runtime). Mirrors the VCR request hash; collision-resistant\n * enough for a per-prompt judge-verdict keyspace. Returned as base-36.\n */\nfunction hashString(input: string): string {\n  let h1 = 0xdeadbeef;\n  let h2 = 0x41c6ce57;\n\n  for (let i = 0; i < input.length; i++) {\n    const ch = input.charCodeAt(i);\n\n    h1 = Math.imul(h1 ^ ch, 2654435761);\n    h2 = Math.imul(h2 ^ ch, 1597334677);\n  }\n\n  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);\n  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);\n  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);\n  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);\n\n  const combined = 4294967296 * (2097151 & h2) + (h1 >>> 0);\n\n  return combined.toString(36);\n}\n\n/**\n * Build the judge-verdict cache key for a resolved prompt body + judge model.\n * Combines the model's `provider:name` identity with a content hash of the\n * body, so the same prompt graded by the same judge hits the cache, while any\n * change to either misses it.\n */\nexport function judgeCacheKey(text: string, model: ModelContract): string {\n  return `prompts.judge.${model.provider}:${model.name}.${hashString(text)}`;\n}\n\n/**\n * Run the judge pass with an OPTIONAL memo cache in front. On a hit, the stored\n * {@link JudgeOutcome} is returned without a model call; on a miss, the live\n * judge runs and a USABLE verdict (one carrying a `score`) is written back.\n * Degraded outcomes (no score) are NOT cached — a transient judge failure must\n * never poison the memo. A `null`/absent cache degrades to a direct judge call.\n *\n * Cache I/O is itself fault-tolerant: a `get`/`set` that rejects is swallowed\n * so a flaky cache can never break (or fail) validation.\n *\n * @param text - The resolved prompt body under evaluation.\n * @param model - The judge model.\n * @param cache - Optional verdict memo (any `CacheDriver`-like get/set surface).\n */\nexport async function judgePromptBodyCached(\n  text: string,\n  model: ModelContract,\n  cache?: PromptJudgeCacheLike,\n): Promise<JudgeOutcome> {\n  if (!cache) {\n    return judgePromptBody(text, model);\n  }\n\n  const key = judgeCacheKey(text, model);\n\n  const cached = await readJudgeCache(cache, key);\n\n  if (cached) {\n    return cached;\n  }\n\n  const outcome = await judgePromptBody(text, model);\n\n  // Only memoize a usable verdict — never a degraded (scoreless) one.\n  if (outcome.score !== undefined) {\n    await writeJudgeCache(cache, key, outcome);\n  }\n\n  return outcome;\n}\n\n/** Read a cached verdict, swallowing any cache fault (treated as a miss). */\nasync function readJudgeCache(\n  cache: PromptJudgeCacheLike,\n  key: string,\n): Promise<JudgeOutcome | undefined> {\n  try {\n    const value = await cache.get<JudgeOutcome>(key);\n\n    return value ?? undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/** Write a verdict, swallowing any cache fault (best-effort memo). */\nasync function writeJudgeCache(\n  cache: PromptJudgeCacheLike,\n  key: string,\n  outcome: JudgeOutcome,\n): Promise<void> {\n  try {\n    await cache.set(key, outcome);\n  } catch {\n    // Best-effort — a failed memo write never affects the validation result.\n  }\n}\n\n/**\n * Resolve the body + declared-required keys for a validation target that is a\n * `SystemPromptContract` (named or anonymous). The declared set is the\n * prompt's `meta.required` (when present).\n */\nexport function describeContractTarget(contract: SystemPromptContract): {\n  text: string;\n  required: readonly string[];\n} {\n  const meta = contract.meta();\n\n  return {\n    text: contract.resolve(),\n    required: meta?.required ?? [],\n  };\n}\n"],"mappings":"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"}

package/esm/ai/src/rag/as-tool.mjs

@@ -0,0 +1,48 @@
+import { tool } from "../tool/tool.mjs";
+
+//#region ../@warlock.js/ai/src/rag/as-tool.ts
+/**
+* A minimal, schema-library-agnostic Standard Schema for `{ query: string }`.
+*
+* Built by hand (no `seal` / `zod` import) so `asTool()` stays dependency-
+* free and matches the framework's own `passthroughSchema` style — the
+* `~standard.validate` returns `{ issues }` on a bad shape so the tool
+* runtime surfaces a `SchemaValidationError` exactly like any other tool.
+*/
+function ragToolSchema() {
+	return { "~standard": {
+		version: 1,
+		vendor: "warlock-ai-rag",
+		validate: (value) => {
+			if (!value || typeof value !== "object" || typeof value.query !== "string") return { issues: [{ message: "rag tool input must be { query: string }" }] };
+			return { value: { query: value.query } };
+		}
+	} };
+}
+/**
+* Build a `ToolContract<{ query: string }, RetrieveResult>` that exposes a
+* rag's `retrieve()` to an agent's `tools: []` loop.
+*
+* `retrieve()` is a leaf operation (no inner executable report to nest),
+* so the plain `tool()` factory is the right shape — not `compositeAsTool`.
+* The resulting contract has `invoke`, so `isExecutableTool` returns false
+* and `normalizeAgentTools` passes it through untouched. On a thrown
+* retrieval error the runtime serializes `{ error }` back to the agent for
+* self-correction; the run does not abort.
+*
+* The tool name defaults to `retrieve_<name>` — namespaced by the rag's
+* name because the agent tool surface has no duplicate-name collision
+* guard (first match wins silently).
+*/
+function ragAsTool(name, retrieveFn, options = {}) {
+	return tool({
+		name: options.name ?? `retrieve_${name}`,
+		description: options.description ?? `Search the "${name}" knowledge base and return the most relevant cited passages for a query.`,
+		input: ragToolSchema(),
+		execute: async ({ query }) => retrieveFn(query, options.retrieve)
+	});
+}
+
+//#endregion
+export { ragAsTool };
+//# sourceMappingURL=as-tool.mjs.map

package/esm/ai/src/rag/as-tool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"as-tool.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/rag/as-tool.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { ToolContract } from \"../tool/tool\";\nimport { tool } from \"../tool/tool\";\nimport type { RetrieveOptions, RetrieveResult } from \"./contracts/citation.type\";\nimport type { RagAsToolOptions } from \"./contracts/rag-config.type\";\n\n/** The validated input shape of a rag tool. */\ntype RagToolInput = { query: string };\n\n/**\n * A minimal, schema-library-agnostic Standard Schema for `{ query: string }`.\n *\n * Built by hand (no `seal` / `zod` import) so `asTool()` stays dependency-\n * free and matches the framework's own `passthroughSchema` style — the\n * `~standard.validate` returns `{ issues }` on a bad shape so the tool\n * runtime surfaces a `SchemaValidationError` exactly like any other tool.\n */\nfunction ragToolSchema(): StandardSchemaV1<RagToolInput> {\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-ai-rag\",\n      validate: (value: unknown) => {\n        if (\n          !value ||\n          typeof value !== \"object\" ||\n          typeof (value as { query?: unknown }).query !== \"string\"\n        ) {\n          return {\n            issues: [{ message: \"rag tool input must be { query: string }\" }],\n          };\n        }\n\n        return { value: { query: (value as RagToolInput).query } };\n      },\n    },\n  };\n}\n\n/**\n * Build a `ToolContract<{ query: string }, RetrieveResult>` that exposes a\n * rag's `retrieve()` to an agent's `tools: []` loop.\n *\n * `retrieve()` is a leaf operation (no inner executable report to nest),\n * so the plain `tool()` factory is the right shape — not `compositeAsTool`.\n * The resulting contract has `invoke`, so `isExecutableTool` returns false\n * and `normalizeAgentTools` passes it through untouched. On a thrown\n * retrieval error the runtime serializes `{ error }` back to the agent for\n * self-correction; the run does not abort.\n *\n * The tool name defaults to `retrieve_<name>` — namespaced by the rag's\n * name because the agent tool surface has no duplicate-name collision\n * guard (first match wins silently).\n */\nexport function ragAsTool(\n  name: string,\n  retrieveFn: (query: string, options?: RetrieveOptions) => Promise<RetrieveResult>,\n  options: RagAsToolOptions = {},\n): ToolContract<RagToolInput, RetrieveResult> {\n  const toolName = options.name ?? `retrieve_${name}`;\n\n  return tool<RagToolInput, RetrieveResult>({\n    name: toolName,\n    description:\n      options.description ??\n      `Search the \"${name}\" knowledge base and return the most relevant cited passages for a query.`,\n    input: ragToolSchema(),\n    execute: async ({ query }) => retrieveFn(query, options.retrieve),\n  });\n}\n"],"mappings":";;;;;;;;;;;AAiBA,SAAS,gBAAgD;CACvD,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,UAAmB;GAC5B,IACE,CAAC,SACD,OAAO,UAAU,YACjB,OAAQ,MAA8B,UAAU,UAEhD,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,2CAA2C,CAAC,EAClE;GAGF,OAAO,EAAE,OAAO,EAAE,OAAQ,MAAuB,MAAM,EAAE;EAC3D;CACF,EACF;AACF;;;;;;;;;;;;;;;;AAiBA,SAAgB,UACd,MACA,YACA,UAA4B,CAAC,GACe;CAG5C,OAAO,KAAmC;EACxC,MAHe,QAAQ,QAAQ,YAAY;EAI3C,aACE,QAAQ,eACR,eAAe,KAAK;EACtB,OAAO,cAAc;EACrB,SAAS,OAAO,EAAE,YAAY,WAAW,OAAO,QAAQ,QAAQ;CAClE,CAAC;AACH"}

package/esm/ai/src/rag/chunk/chunk.mjs

@@ -0,0 +1,44 @@
+import { fixedChunk } from "./fixed.mjs";
+import { DEFAULT_SEPARATORS, recursiveChunk } from "./recursive.mjs";
+import { markdownChunk } from "./markdown.mjs";
+import { sentenceChunk } from "./sentence.mjs";
+
+//#region ../@warlock.js/ai/src/rag/chunk/chunk.ts
+/** Default target chunk size in characters. */
+const DEFAULT_CHUNK_SIZE = 1e3;
+/** Default character overlap carried between adjacent chunks. */
+const DEFAULT_CHUNK_OVERLAP = 200;
+/**
+* Split `text` into citation-bearing {@link Chunk}s according to
+* {@link ChunkOptions}, dispatching on `options.type`:
+*
+* - `"recursive"` (default) — separator-aware greedy packing.
+* - `"markdown"` — heading/section-aware, then recursive within sections.
+* - `"sentence"` — packs whole sentences.
+* - `"fixed"` — back-to-back character windows.
+*
+* All strategies are character-based (tokenizer-free) and record the exact
+* `[start, end)` span of every chunk in the original text. Empty or
+* whitespace-only input yields `[]`.
+*
+* @example
+* const chunks = chunk(markdownDoc, { type: "markdown", size: 800, overlap: 120 });
+* for (const c of chunks) console.log(c.index, c.span, c.text);
+*/
+function chunk(text, options = {}) {
+	const type = options.type ?? "recursive";
+	const size = options.size ?? 1e3;
+	const overlap = options.overlap ?? 200;
+	const separators = options.separators ?? DEFAULT_SEPARATORS;
+	if (text.trim().length === 0) return [];
+	switch (type) {
+		case "markdown": return markdownChunk(text, size, overlap, separators);
+		case "sentence": return sentenceChunk(text, size, overlap);
+		case "fixed": return fixedChunk(text, size, overlap);
+		default: return recursiveChunk(text, size, overlap, separators);
+	}
+}
+
+//#endregion
+export { chunk };
+//# sourceMappingURL=chunk.mjs.map

package/esm/ai/src/rag/chunk/chunk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/rag/chunk/chunk.ts"],"sourcesContent":["import type { Chunk, ChunkOptions } from \"../contracts/chunk-options.type\";\nimport { fixedChunk } from \"./fixed\";\nimport { markdownChunk } from \"./markdown\";\nimport { DEFAULT_SEPARATORS, recursiveChunk } from \"./recursive\";\nimport { sentenceChunk } from \"./sentence\";\n\n/** Default target chunk size in characters. */\nexport const DEFAULT_CHUNK_SIZE = 1000;\n\n/** Default character overlap carried between adjacent chunks. */\nexport const DEFAULT_CHUNK_OVERLAP = 200;\n\n/**\n * Split `text` into citation-bearing {@link Chunk}s according to\n * {@link ChunkOptions}, dispatching on `options.type`:\n *\n * - `\"recursive\"` (default) — separator-aware greedy packing.\n * - `\"markdown\"` — heading/section-aware, then recursive within sections.\n * - `\"sentence\"` — packs whole sentences.\n * - `\"fixed\"` — back-to-back character windows.\n *\n * All strategies are character-based (tokenizer-free) and record the exact\n * `[start, end)` span of every chunk in the original text. Empty or\n * whitespace-only input yields `[]`.\n *\n * @example\n * const chunks = chunk(markdownDoc, { type: \"markdown\", size: 800, overlap: 120 });\n * for (const c of chunks) console.log(c.index, c.span, c.text);\n */\nexport function chunk(text: string, options: ChunkOptions = {}): Chunk[] {\n  const type = options.type ?? \"recursive\";\n  const size = options.size ?? DEFAULT_CHUNK_SIZE;\n  const overlap = options.overlap ?? DEFAULT_CHUNK_OVERLAP;\n  const separators = options.separators ?? DEFAULT_SEPARATORS;\n\n  // Empty or whitespace-only input yields no chunks — index() then writes\n  // nothing and never embeds an empty batch.\n  if (text.trim().length === 0) {\n    return [];\n  }\n\n  switch (type) {\n    case \"markdown\":\n      return markdownChunk(text, size, overlap, separators);\n\n    case \"sentence\":\n      return sentenceChunk(text, size, overlap);\n\n    case \"fixed\":\n      return fixedChunk(text, size, overlap);\n\n    case \"recursive\":\n    default:\n      return recursiveChunk(text, size, overlap, separators);\n  }\n}\n"],"mappings":";;;;;;;AAOA,MAAa,qBAAqB;;AAGlC,MAAa,wBAAwB;;;;;;;;;;;;;;;;;;AAmBrC,SAAgB,MAAM,MAAc,UAAwB,CAAC,GAAY;CACvE,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,OAAO,QAAQ;CACrB,MAAM,UAAU,QAAQ;CACxB,MAAM,aAAa,QAAQ,cAAc;CAIzC,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GACzB,OAAO,CAAC;CAGV,QAAQ,MAAR;EACE,KAAK,YACH,OAAO,cAAc,MAAM,MAAM,SAAS,UAAU;EAEtD,KAAK,YACH,OAAO,cAAc,MAAM,MAAM,OAAO;EAE1C,KAAK,SACH,OAAO,WAAW,MAAM,MAAM,OAAO;EAGvC,SACE,OAAO,eAAe,MAAM,MAAM,SAAS,UAAU;CACzD;AACF"}

package/esm/ai/src/rag/chunk/fixed.mjs

@@ -0,0 +1,32 @@
+//#region ../@warlock.js/ai/src/rag/chunk/fixed.ts
+/**
+* Fixed-window character splitter.
+*
+* The simplest strategy: slices the text into back-to-back windows of
+* `size` characters, stepping forward by `size - overlap` so adjacent
+* windows share `overlap` characters. Boundary-unaware — it will cut
+* mid-word — but deterministic and dep-free. Spans are exact by
+* construction.
+*/
+function fixedChunk(text, size, overlap) {
+	if (text.length === 0) return [];
+	const step = Math.max(1, size - overlap);
+	const chunks = [];
+	let index = 0;
+	for (let cursor = 0; cursor < text.length; cursor += step) {
+		const start = cursor;
+		const end = Math.min(cursor + size, text.length);
+		chunks.push({
+			text: text.slice(start, end),
+			index,
+			span: [start, end]
+		});
+		index += 1;
+		if (end >= text.length) break;
+	}
+	return chunks;
+}
+
+//#endregion
+export { fixedChunk };
+//# sourceMappingURL=fixed.mjs.map

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

@@ -0,0 +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"}

package/esm/ai/src/rag/chunk/markdown.mjs

@@ -0,0 +1,75 @@
+import { DEFAULT_SEPARATORS, recursiveChunk } from "./recursive.mjs";
+
+//#region ../@warlock.js/ai/src/rag/chunk/markdown.ts
+/** Matches an ATX Markdown heading line (`#` … `######`) at line start. */
+const HEADING_LINE = /^#{1,6}[ \t].*$/gm;
+/**
+* Markdown heading/section-aware splitter.
+*
+* Splits the document on ATX heading boundaries (`#`…`######`) first so a
+* section's heading stays glued to its body, then applies the recursive
+* character splitter WITHIN each section so any section larger than `size`
+* is broken down further. Sections at or under `size` are emitted whole.
+* Spans are exact relative to the original document.
+*/
+function markdownChunk(text, size, overlap, separators = DEFAULT_SEPARATORS) {
+	if (text.length === 0) return [];
+	const sections = splitSections(text);
+	const chunks = [];
+	let index = 0;
+	for (const section of sections) {
+		const body = text.slice(section.start, section.end);
+		if (body.trim().length === 0) continue;
+		if (body.length <= size) {
+			chunks.push({
+				text: body,
+				index,
+				span: [section.start, section.end]
+			});
+			index += 1;
+			continue;
+		}
+		const inner = recursiveChunk(body, size, overlap, separators);
+		for (const piece of inner) {
+			chunks.push({
+				text: piece.text,
+				index,
+				span: [section.start + piece.span[0], section.start + piece.span[1]]
+			});
+			index += 1;
+		}
+	}
+	return chunks;
+}
+/**
+* Carve the document into sections, each beginning at a heading line and
+* running until the next heading (the preamble before the first heading is
+* its own section). Spans cover the whole document with no gaps.
+*/
+function splitSections(text) {
+	const starts = [];
+	let match;
+	HEADING_LINE.lastIndex = 0;
+	while ((match = HEADING_LINE.exec(text)) !== null) starts.push(match.index);
+	if (starts.length === 0) return [{
+		start: 0,
+		end: text.length
+	}];
+	const sections = [];
+	if (starts[0] > 0) sections.push({
+		start: 0,
+		end: starts[0]
+	});
+	starts.forEach((start, position) => {
+		const end = position + 1 < starts.length ? starts[position + 1] : text.length;
+		sections.push({
+			start,
+			end
+		});
+	});
+	return sections;
+}
+
+//#endregion
+export { markdownChunk };
+//# sourceMappingURL=markdown.mjs.map

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

@@ -0,0 +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"}

package/esm/ai/src/rag/chunk/recursive.mjs

@@ -0,0 +1,132 @@
+//#region ../@warlock.js/ai/src/rag/chunk/recursive.ts
+/** Default separators for the recursive splitter, tried largest-unit first. */
+const DEFAULT_SEPARATORS = [
+	"\n\n",
+	"\n",
+	". ",
+	" ",
+	""
+];
+/**
+* Recursive character splitter (the default strategy).
+*
+* Walks `separators` largest-unit-first: it splits the text on the first
+* separator, then packs the resulting pieces into chunks up to `size`
+* characters, carrying `overlap` characters forward between adjacent
+* chunks. Any single piece that is itself larger than `size` is split
+* again on the next-finer separator, recursing until a piece fits (the
+* `""` separator is the final char-by-char fallback).
+*
+* Every emitted chunk records its exact `[start, end)` character span in
+* the ORIGINAL text so a citation can point back precisely — spans are
+* tracked by index-of search as packed pieces are joined.
+*
+* Character-based and deliberately tokenizer-free.
+*/
+function recursiveChunk(text, size, overlap, separators = DEFAULT_SEPARATORS) {
+	return packPieces(text, anchorPieces(text, splitToPieces(text, size, separators)), size, overlap);
+}
+/**
+* Recursively split `text` into pieces no larger than `size` using the
+* ordered separator list. Pieces preserve original characters (no
+* trimming) so downstream span anchoring stays exact.
+*/
+function splitToPieces(text, size, separators) {
+	if (text.length <= size) return text.length > 0 ? [text] : [];
+	const [separator, ...rest] = separators;
+	if (separator === void 0 || separator === "") return hardSplit(text, size);
+	const segments = splitKeepingSeparator(text, separator);
+	const pieces = [];
+	for (const segment of segments) {
+		if (segment.length === 0) continue;
+		if (segment.length <= size) {
+			pieces.push(segment);
+			continue;
+		}
+		pieces.push(...splitToPieces(segment, size, rest));
+	}
+	return pieces;
+}
+/**
+* Split on `separator` but re-attach the separator to the end of each
+* preceding segment, so concatenating the segments reconstructs the
+* original text verbatim (keeping spans exact).
+*/
+function splitKeepingSeparator(text, separator) {
+	const raw = text.split(separator);
+	const segments = [];
+	raw.forEach((part, position) => {
+		const isLast = position === raw.length - 1;
+		segments.push(isLast ? part : part + separator);
+	});
+	return segments;
+}
+/** Hard char-window split for a unit larger than `size` with no usable separator. */
+function hardSplit(text, size) {
+	const pieces = [];
+	for (let cursor = 0; cursor < text.length; cursor += size) pieces.push(text.slice(cursor, cursor + size));
+	return pieces;
+}
+/**
+* Map each piece back to its absolute offset using a monotonic cursor —
+* pieces are emitted in document order, so the next occurrence at-or-after
+* the cursor is the correct one even for repeated substrings.
+*/
+function anchorPieces(text, pieces) {
+	const anchored = [];
+	let cursor = 0;
+	for (const piece of pieces) {
+		const start = text.indexOf(piece, cursor);
+		const resolvedStart = start === -1 ? cursor : start;
+		const end = resolvedStart + piece.length;
+		anchored.push({
+			text: piece,
+			start: resolvedStart,
+			end
+		});
+		cursor = end;
+	}
+	return anchored;
+}
+/**
+* Greedily pack anchored pieces into chunks up to `size` characters, then
+* carry `overlap` trailing characters from each emitted chunk into the
+* next so context is not lost at a boundary. Spans are taken straight
+* from the anchored pieces, so the overlap text is part of the next
+* chunk's span exactly.
+*/
+function packPieces(text, pieces, size, overlap) {
+	const chunks = [];
+	let bufferStart = -1;
+	let bufferEnd = -1;
+	let index = 0;
+	const flush = () => {
+		if (bufferStart === -1) return;
+		chunks.push({
+			text: text.slice(bufferStart, bufferEnd),
+			index,
+			span: [bufferStart, bufferEnd]
+		});
+		index += 1;
+	};
+	for (const piece of pieces) {
+		if (bufferStart === -1) {
+			bufferStart = piece.start;
+			bufferEnd = piece.end;
+			continue;
+		}
+		if (piece.end - bufferStart <= size) {
+			bufferEnd = piece.end;
+			continue;
+		}
+		flush();
+		bufferStart = overlap > 0 ? Math.max(bufferStart, piece.start - overlap) : piece.start;
+		bufferEnd = piece.end;
+	}
+	flush();
+	return chunks;
+}
+
+//#endregion
+export { DEFAULT_SEPARATORS, recursiveChunk };
+//# sourceMappingURL=recursive.mjs.map

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

@@ -0,0 +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"}

package/esm/ai/src/rag/chunk/sentence.mjs

@@ -0,0 +1,73 @@
+//#region ../@warlock.js/ai/src/rag/chunk/sentence.ts
+/** Matches a sentence terminator (`.`, `!`, `?`) followed by whitespace. */
+const SENTENCE_BOUNDARY = /([.!?])\s+/g;
+/**
+* Sentence-aware character splitter.
+*
+* Splits the text on sentence terminators (`. `, `! `, `? `), keeping the
+* terminator attached, then greedily packs whole sentences into chunks up
+* to `size` characters, carrying `overlap` characters forward between
+* adjacent chunks. A single sentence longer than `size` becomes its own
+* (oversize) chunk rather than being cut mid-sentence. Spans are exact.
+*/
+function sentenceChunk(text, size, overlap) {
+	if (text.trim().length === 0) return [];
+	const sentences = splitSentences(text);
+	const chunks = [];
+	let bufferStart = -1;
+	let bufferEnd = -1;
+	let index = 0;
+	const flush = () => {
+		if (bufferStart === -1) return;
+		chunks.push({
+			text: text.slice(bufferStart, bufferEnd),
+			index,
+			span: [bufferStart, bufferEnd]
+		});
+		index += 1;
+	};
+	for (const sentence of sentences) {
+		if (bufferStart === -1) {
+			bufferStart = sentence.start;
+			bufferEnd = sentence.end;
+			continue;
+		}
+		if (sentence.end - bufferStart <= size) {
+			bufferEnd = sentence.end;
+			continue;
+		}
+		flush();
+		bufferStart = overlap > 0 ? Math.max(bufferStart, sentence.start - overlap) : sentence.start;
+		bufferEnd = sentence.end;
+	}
+	flush();
+	return chunks;
+}
+/**
+* Split `text` into sentence spans on terminator + whitespace, keeping the
+* terminator with its sentence and absorbing the trailing whitespace into
+* the boundary so reconstructing the spans loses no characters.
+*/
+function splitSentences(text) {
+	const spans = [];
+	let start = 0;
+	let match;
+	SENTENCE_BOUNDARY.lastIndex = 0;
+	while ((match = SENTENCE_BOUNDARY.exec(text)) !== null) {
+		const end = match.index + match[0].length;
+		spans.push({
+			start,
+			end
+		});
+		start = end;
+	}
+	if (start < text.length) spans.push({
+		start,
+		end: text.length
+	});
+	return spans;
+}
+
+//#endregion
+export { sentenceChunk };
+//# sourceMappingURL=sentence.mjs.map

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

@@ -0,0 +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"}

package/esm/ai/src/rag/hybrid/bm25.mjs

@@ -0,0 +1,51 @@
+//#region ../@warlock.js/ai/src/rag/hybrid/bm25.ts
+const BM25_K1 = 1.5;
+const BM25_B = .75;
+/** Lowercase + split on non-word characters; drop empties. */
+function tokenize(text) {
+	return text.toLowerCase().split(/[^a-z0-9]+/i).filter(Boolean);
+}
+/**
+* Rank `docs` against `query` with BM25 (A4) — the lexical half of hybrid
+* retrieval. Scores keyword overlap with TF saturation (`k1`) and length
+* normalization (`b`) over the candidate set, so an exact-term match
+* surfaces even when dense embeddings miss it. Returns docs sorted by
+* score (highest first); zero-score docs are dropped.
+*
+* Operates over the supplied candidate set (typically the dense retriever's
+* over-fetch), so it needs no global corpus index — ideal for fusing with
+* a vector ranking via {@link reciprocalRankFusion}.
+*/
+function bm25Rank(query, docs) {
+	const queryTerms = [...new Set(tokenize(query))];
+	if (queryTerms.length === 0 || docs.length === 0) return [];
+	const tokenized = docs.map((doc) => ({
+		id: doc.id,
+		terms: tokenize(doc.text)
+	}));
+	const avgLen = tokenized.reduce((sum, d) => sum + d.terms.length, 0) / tokenized.length || 1;
+	const df = /* @__PURE__ */ new Map();
+	for (const term of queryTerms) df.set(term, tokenized.filter((d) => d.terms.includes(term)).length);
+	const n = tokenized.length;
+	return tokenized.map((doc) => {
+		const len = doc.terms.length || 1;
+		let score = 0;
+		for (const term of queryTerms) {
+			const tf = doc.terms.filter((t) => t === term).length;
+			if (tf === 0) continue;
+			const docFreq = df.get(term) ?? 0;
+			const idf = Math.log(1 + (n - docFreq + .5) / (docFreq + .5));
+			const numerator = tf * 2.5;
+			const denominator = tf + BM25_K1 * (1 - BM25_B + BM25_B * (len / avgLen));
+			score += idf * (numerator / denominator);
+		}
+		return {
+			id: doc.id,
+			score
+		};
+	}).filter((item) => item.score > 0).sort((a, b) => b.score - a.score);
+}
+
+//#endregion
+export { bm25Rank };
+//# sourceMappingURL=bm25.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,29 @@
+import { reciprocalRankFusion } from "./rrf.mjs";
+import { bm25Rank } from "./bm25.mjs";
+
+//#region ../@warlock.js/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
+* retrieval captures semantic similarity; BM25 captures exact-term
+* matches dense embeddings miss (names, ids, rare tokens). Fusing both
+* beats either alone for keyword-heavy queries.
+*
+* `dense` is the vector retriever's result in rank order; `candidates`
+* supplies the text for the lexical pass (typically the same over-fetched
+* set). Returns the fused ranking, highest score first.
+*
+* @example
+* const fused = hybridRank({
+*   query: "invoice 8842 refund",
+*   dense: vectorHits,                 // [{ id }, ...] in similarity order
+*   candidates: vectorHits.map(h => ({ id: h.id, text: h.text })),
+* });
+*/
+function hybridRank(params) {
+	return reciprocalRankFusion([params.dense.map((d) => d.id), bm25Rank(params.query, params.candidates).map((r) => r.id)], params.k);
+}
+
+//#endregion
+export { hybridRank };
+//# sourceMappingURL=hybrid-rank.mjs.map

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

@@ -0,0 +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"}

package/esm/ai/src/rag/hybrid/rrf.mjs

@@ -0,0 +1,30 @@
+//#region ../@warlock.js/ai/src/rag/hybrid/rrf.ts
+/**
+* Reciprocal Rank Fusion (A4) — combine several independently-ranked
+* lists of ids into one consensus ranking. Each list contributes
+* `1 / (k + rank)` to an id's score (rank is 0-based within that list), so
+* an id near the top of multiple lists rises even if no single list ranks
+* it first. The classic fusion for hybrid (dense + lexical) retrieval
+* because it needs no score calibration between the lists.
+*
+* `k` (default 60, the standard) dampens the contribution of lower ranks.
+* Returns ids sorted by fused score, highest first.
+*
+* @example
+* reciprocalRankFusion([["a", "b", "c"], ["b", "a"]]);
+* // → [{ id: "b", ... }, { id: "a", ... }, { id: "c", ... }]
+*/
+function reciprocalRankFusion(rankedLists, k = 60) {
+	const scores = /* @__PURE__ */ new Map();
+	for (const list of rankedLists) list.forEach((id, rank) => {
+		scores.set(id, (scores.get(id) ?? 0) + 1 / (k + rank));
+	});
+	return [...scores.entries()].map(([id, score]) => ({
+		id,
+		score
+	})).sort((a, b) => b.score - a.score);
+}
+
+//#endregion
+export { reciprocalRankFusion };
+//# sourceMappingURL=rrf.mjs.map

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

@@ -0,0 +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"}