@graphorin/memory 0.5.0

package/dist/search/iterative.d.ts

@@ -0,0 +1,223 @@
+import { Provider, ProviderRequest } from "@graphorin/core";
+
+//#region src/search/iterative.d.ts
+
+/** Default hard ceiling on total retrieval passes (gate + cap mandatory). */
+declare const DEFAULT_MAX_ITERATIONS = 3;
+/**
+ * Absolute clamp on total retrieval passes, applied regardless of the
+ * caller's `maxIterations` — a latency guardrail so a mis-configured
+ * caller can never unbound the loop.
+ */
+declare const MAX_ITERATIONS_CEILING = 5;
+/** Default score (0..1) at or above which a query is classified as hard. */
+declare const DEFAULT_DIFFICULTY_THRESHOLD = 0.5;
+/**
+ * Outcome of the heuristic difficulty gate. `hard` is the gating
+ * decision (`score >= threshold`); `signals` lists which heuristic
+ * categories fired, for explainability / tracing.
+ *
+ * @stable
+ */
+interface DifficultyAssessment {
+  readonly hard: boolean;
+  /** Aggregate difficulty score, clamped to `[0, 1]`. */
+  readonly score: number;
+  /** Heuristic categories that fired (`'multi-hop'`, `'temporal'`, …). */
+  readonly signals: ReadonlyArray<string>;
+}
+/**
+ * Tuning for {@link assessQueryDifficulty}.
+ *
+ * @stable
+ */
+interface DifficultyGateOptions {
+  /** Minimum score (0..1) to classify the query as hard. Default 0.5. */
+  readonly threshold?: number;
+}
+/**
+ * Score a query's retrieval difficulty with cheap, deterministic, fully
+ * **local** heuristics (no I/O). Conservative by design — it prefers to
+ * leave a query single-shot (`hard: false`) unless several
+ * multi-hop / temporal / comparison signals stack up, so the gate adds
+ * passes only where they are likely to help. Used by
+ * {@link runIterativeRetrieval} to decide whether to enter the loop.
+ *
+ * @stable
+ */
+declare function assessQueryDifficulty(query: string, options?: DifficultyGateOptions): DifficultyAssessment;
+/**
+ * Verdict from grading a retrieved candidate set against a query.
+ *
+ * @stable
+ */
+interface RetrievalGrade {
+  /** Whether the retrieved memories suffice to answer the query. */
+  readonly sufficient: boolean;
+  /** Grader confidence, clamped to `[0, 1]`. */
+  readonly confidence: number;
+  /**
+   * A single better search query to try next, or `null` when the grader
+   * proposes none (the loop then stops / abstains).
+   */
+  readonly reformulation: string | null;
+  /** Optional short rationale (never surfaced in spans). */
+  readonly reason?: string;
+}
+/**
+ * Per-call options for a {@link RetrievalGrader}.
+ *
+ * @stable
+ */
+interface RetrievalGradeOptions {
+  /** Cancellation signal forwarded to the underlying provider call. */
+  readonly signal?: AbortSignal;
+  /**
+   * Reformulations already attempted (MRET-11). Surfaced to the grader
+   * as context so it can propose something genuinely new — the grade
+   * itself is ALWAYS judged against the original question, never a
+   * reformulation (a narrowed sub-query must not be declared
+   * "sufficient" while the original multi-hop question is not).
+   */
+  readonly triedQueries?: ReadonlyArray<string>;
+}
+/**
+ * Pluggable retrieval-grader seam consumed by the iterative loop. The
+ * built-in provider-backed implementation lives in
+ * {@link createProviderRetrievalGrader}; advanced callers can supply a
+ * bespoke grader (e.g. a deterministic heuristic).
+ *
+ * Implementations MUST degrade gracefully — return a "stop" grade rather
+ * than throw — so a grader failure never breaks recall.
+ *
+ * @stable
+ */
+interface RetrievalGrader {
+  grade(query: string, snippets: ReadonlyArray<string>, options?: RetrievalGradeOptions): Promise<RetrievalGrade>;
+}
+/**
+ * System prompt for the retrieval grader. Asks for a bare JSON verdict;
+ * {@link parseGrade} also tolerates a chatty model.
+ *
+ * @internal
+ */
+declare const RETRIEVAL_GRADE_SYSTEM_PROMPT: string;
+/**
+ * Build the grade request. Pure — no I/O. Temperature 0 so the verdict
+ * is as stable as the model allows.
+ *
+ * @stable
+ */
+declare function buildGradeRequest(query: string, snippets: ReadonlyArray<string>, options?: {
+  readonly maxTokens?: number;
+  readonly signal?: AbortSignal;
+  readonly triedQueries?: ReadonlyArray<string>;
+}): ProviderRequest;
+/**
+ * Parse a grader model output into a {@link RetrievalGrade}. Tolerates a
+ * bare JSON object, a fenced block, and chatty text around the object.
+ *
+ * **Fail-safe = stop.** When the verdict can't be read (undefined / empty
+ * / unparseable / missing `sufficient`), returns
+ * `{ sufficient: true, confidence: 0, reformulation: null }` so a broken
+ * grader degrades to a single pass rather than looping or falsely
+ * abstaining. A *parsed* `sufficient: false` (a real insufficiency
+ * verdict) is preserved.
+ *
+ * @stable
+ */
+declare function parseGrade(text: string | undefined): RetrievalGrade;
+/**
+ * Wrap a {@link Provider} as a {@link RetrievalGrader}. **Resilient**: a
+ * provider error or unparseable response degrades to the
+ * {@link parseGrade} "stop" grade so grading never throws into the loop
+ * (and a flaky grader can't drive endless reformulation).
+ *
+ * @stable
+ */
+declare function createProviderRetrievalGrader(provider: Provider, options?: {
+  readonly maxTokens?: number;
+}): RetrievalGrader;
+/**
+ * Result of an iterative retrieval run.
+ *
+ * @stable
+ */
+interface IterativeRetrievalResult<H> {
+  /** Accumulated hits across all passes (deduped, in discovery order). */
+  readonly hits: ReadonlyArray<H>;
+  /** Number of retrieval passes performed (≥ 1). */
+  readonly iterations: number;
+  /** Difficulty-gate verdict (whether the loop was eligible to run). */
+  readonly gateHard: boolean;
+  /** Final sufficiency verdict. */
+  readonly sufficient: boolean;
+  /**
+   * `true` when the loop exhausted its cap / ran out of reformulations
+   * while still judged insufficient — the caller should abstain rather
+   * than answer from `hits`.
+   */
+  readonly abstained: boolean;
+  /** The sequence of queries tried (original first). */
+  readonly queries: ReadonlyArray<string>;
+}
+/**
+ * Dependencies injected into {@link runIterativeRetrieval}. The loop does
+ * no I/O of its own — `retrieve` and `grader` own all side effects.
+ *
+ * @stable
+ */
+interface IterativeRetrievalDeps<H> {
+  /**
+   * Run one retrieval pass for `query`. `widen` is `true` on
+   * reformulation passes so the caller can broaden recall (e.g. enable
+   * P2-1 one-hop graph expansion).
+   */
+  retrieve(query: string, widen: boolean, signal?: AbortSignal): Promise<ReadonlyArray<H>>;
+  /** Snippet shown to the grader for a hit. */
+  snippetOf(hit: H): string;
+  /** Stable id used to dedup hits across passes. */
+  idOf(hit: H): string;
+  /** Grader; `null` ⇒ single-shot (no grading, no provider call). */
+  grader: RetrievalGrader | null;
+  /**
+   * Re-fuse the per-pass hit lists into one ranked list (MRET-2).
+   * Receives one list per pass in pass order; the result feeds the
+   * final `maxResults` cut so a pass-2 find can outrank pass-1 noise.
+   * Absent ⇒ the loop falls back to round-robin interleaving (still
+   * strictly better than the old discovery-order cut).
+   */
+  fuse?(lists: ReadonlyArray<ReadonlyArray<H>>): ReadonlyArray<H>;
+}
+/**
+ * Options for {@link runIterativeRetrieval}.
+ *
+ * @stable
+ */
+interface IterativeRetrievalOptions {
+  /** Total-pass cap; clamped to `[1, {@link MAX_ITERATIONS_CEILING}]`. */
+  readonly maxIterations?: number;
+  /** Difficulty-gate tuning. */
+  readonly difficulty?: DifficultyGateOptions;
+  /** Skip the heuristic gate and force the loop (still capped). */
+  readonly forceHard?: boolean;
+  /** Max snippets passed to the grader per pass. Default 8. */
+  readonly maxGradeSnippets?: number;
+  /** Cap on the returned hit count (omitted ⇒ all accumulated). */
+  readonly maxResults?: number;
+  readonly signal?: AbortSignal;
+}
+/**
+ * Run the gated grade-then-reformulate loop.
+ *
+ * Flow: assess difficulty → retrieve (pass 1) → if not hard *or* no
+ * grader, return single-shot → else grade; if sufficient, return; if
+ * weak and a reformulation is offered and the cap is not hit, retrieve
+ * again (widened) and re-grade; otherwise **abstain**.
+ *
+ * @stable
+ */
+declare function runIterativeRetrieval<H>(query: string, deps: IterativeRetrievalDeps<H>, options?: IterativeRetrievalOptions): Promise<IterativeRetrievalResult<H>>;
+//#endregion
+export { DEFAULT_DIFFICULTY_THRESHOLD, DEFAULT_MAX_ITERATIONS, DifficultyAssessment, DifficultyGateOptions, IterativeRetrievalDeps, IterativeRetrievalOptions, IterativeRetrievalResult, MAX_ITERATIONS_CEILING, RETRIEVAL_GRADE_SYSTEM_PROMPT, RetrievalGrade, RetrievalGradeOptions, RetrievalGrader, assessQueryDifficulty, buildGradeRequest, createProviderRetrievalGrader, parseGrade, runIterativeRetrieval };
+//# sourceMappingURL=iterative.d.ts.map

package/dist/search/iterative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterative.d.ts","names":[],"sources":["../../src/search/iterative.ts"],"sourcesContent":[],"mappings":";;;;;AAmXiE,cA9UpD,sBAAA,GA8UoD,CAAA;;;;;;AAclD,cArVF,sBAAA,GAqVE,CAAA;;AAAkC,cAlVpC,4BAAA,GAkVoC,GAAA;;AAQjD;AAwBA;;;;;AAIW,UAnWM,oBAAA,CAmWN;EAAR,SAAA,IAAA,EAAA,OAAA;EAAO;;;oBA9VU;;;;;;;UAQH,qBAAA;;;;;;;;;;;;;;iBAqCD,qBAAA,0BAEL,wBACR;;;;;;UA8Cc,cAAA;;;;;;;;;;;;;;;;;;UAmBA,qBAAA;;oBAEG;;;;;;;;0BAQM;;;;;;;;;;;;;UAcT,eAAA;iCAGH,iCACA,wBACT,QAAQ;;;;;;;;cASA;;;;;;;iBAiBG,iBAAA,0BAEJ;;oBAGU;0BACM;IAEzB;;;;;;;;;;;;;;iBAkCa,UAAA,4BAAsC;;;;;;;;;iBA4BtC,6BAAA,WACJ;;IAET;;;;;;UA4Bc;;iBAEA,cAAc;;;;;;;;;;;;;;oBAcX;;;;;;;;UASH;;;;;;mDAMkC,cAAc,QAAQ,cAAc;;iBAEtE;;YAEL;;UAEF;;;;;;;;eAQK,cAAc,cAAc,MAAM,cAAc;;;;;;;UAQ9C,yBAAA;;;;wBAIO;;;;;;;oBAOJ;;;;;;;;;;;;iBAaE,8CAEd,uBAAuB,cACpB,4BACR,QAAQ,yBAAyB"}

package/dist/search/iterative.js

@@ -0,0 +1,330 @@
+//#region src/search/iterative.ts
+/** Default hard ceiling on total retrieval passes (gate + cap mandatory). */
+const DEFAULT_MAX_ITERATIONS = 3;
+/**
+* Absolute clamp on total retrieval passes, applied regardless of the
+* caller's `maxIterations` — a latency guardrail so a mis-configured
+* caller can never unbound the loop.
+*/
+const MAX_ITERATIONS_CEILING = 5;
+/** Default score (0..1) at or above which a query is classified as hard. */
+const DEFAULT_DIFFICULTY_THRESHOLD = .5;
+/** Default output-token ceiling for a single grade call. */
+const DEFAULT_GRADE_MAX_TOKENS = 256;
+/** Default number of retrieved snippets shown to the grader per pass. */
+const DEFAULT_MAX_GRADE_SNIPPETS = 8;
+/** Relational / referential markers implying a hop to another entity. */
+const RE_REL_PRONOUN = /\b(?:who|whom|whose|which)\b/iu;
+const RE_OF_CHAIN = /\bthe\s+\w+\s+of\b/iu;
+const RE_POSSESSIVE = /\b[\w-]+'s\b/giu;
+const RE_DESC_REF = /\bthe\s+(?:person|people|place|thing|one|company|team|book|restaurant|project|guy|woman|man)\b/iu;
+/** Temporal ordering / relative-time markers. */
+const RE_TEMPORAL = /\b(?:before|after|when|while|during|since|until|first|last|earliest|latest|previously|originally|ago|prior|then|recently|used\s+to)\b/iu;
+/** Comparison / superlative markers. */
+const RE_COMPARISON = /\b(?:most|least|more|less|fewer|greater|biggest|largest|smallest|oldest|newest|best|worst|highest|lowest|compared?|versus|vs\.?|between)\b/iu;
+/** Clause-joining conjunctions used to count clauses. */
+const RE_CONJUNCTION = /\b(?:and|or|but|then)\b/giu;
+const W_MULTI_HOP = .4;
+const W_TEMPORAL = .3;
+const W_COMPARISON = .3;
+const W_MULTI_CLAUSE = .2;
+const W_LONG = .15;
+const LONG_WORD_COUNT = 12;
+/**
+* Score a query's retrieval difficulty with cheap, deterministic, fully
+* **local** heuristics (no I/O). Conservative by design — it prefers to
+* leave a query single-shot (`hard: false`) unless several
+* multi-hop / temporal / comparison signals stack up, so the gate adds
+* passes only where they are likely to help. Used by
+* {@link runIterativeRetrieval} to decide whether to enter the loop.
+*
+* @stable
+*/
+function assessQueryDifficulty(query, options = {}) {
+	const threshold = options.threshold ?? DEFAULT_DIFFICULTY_THRESHOLD;
+	const signals = [];
+	let score = 0;
+	const possessiveCount = (query.match(RE_POSSESSIVE) ?? []).length;
+	if (RE_REL_PRONOUN.test(query) || RE_OF_CHAIN.test(query) || RE_DESC_REF.test(query) || possessiveCount >= 2) {
+		signals.push("multi-hop");
+		score += W_MULTI_HOP;
+	}
+	if (RE_TEMPORAL.test(query)) {
+		signals.push("temporal");
+		score += W_TEMPORAL;
+	}
+	if (RE_COMPARISON.test(query)) {
+		signals.push("comparison");
+		score += W_COMPARISON;
+	}
+	if ((query.match(RE_CONJUNCTION) ?? []).length + countCommas(query) >= 2 || questionMarkCount(query) >= 2) {
+		signals.push("multi-clause");
+		score += W_MULTI_CLAUSE;
+	}
+	if (wordCount(query) >= LONG_WORD_COUNT) {
+		signals.push("long");
+		score += W_LONG;
+	}
+	const clamped = Math.min(1, score);
+	return {
+		hard: clamped >= threshold,
+		score: clamped,
+		signals
+	};
+}
+/**
+* System prompt for the retrieval grader. Asks for a bare JSON verdict;
+* {@link parseGrade} also tolerates a chatty model.
+*
+* @internal
+*/
+const RETRIEVAL_GRADE_SYSTEM_PROMPT = "You are a retrieval grader for a personal memory store. Given a question and a numbered list of retrieved memories, judge whether they are SUFFICIENT to answer the question correctly and completely. Respond with ONLY a JSON object: {\"sufficient\": boolean, \"confidence\": number between 0 and 1, \"reformulation\": string or null, \"reason\": string}. Set \"sufficient\" to true only if the memories actually contain the answer — do not guess. When insufficient, set \"reformulation\" to a single alternative search query likely to retrieve the missing information (vary entities, time frame, or specificity); otherwise null. Output only the JSON object — no prose, no markdown.";
+/**
+* Build the grade request. Pure — no I/O. Temperature 0 so the verdict
+* is as stable as the model allows.
+*
+* @stable
+*/
+function buildGradeRequest(query, snippets, options = {}) {
+	return {
+		messages: [{
+			role: "user",
+			content: `Question: ${query}\n\nRetrieved memories:\n${snippets.length === 0 ? "(none)" : snippets.map((s, i) => `[${i + 1}] ${s}`).join("\n")}${options.triedQueries !== void 0 && options.triedQueries.length > 0 ? `\n\nQueries already tried (do not repeat them): ${options.triedQueries.join(" | ")}` : ""}\n\nGrade whether these memories are sufficient to answer the question. If not, propose a single better search query.`
+		}],
+		systemMessage: RETRIEVAL_GRADE_SYSTEM_PROMPT,
+		temperature: 0,
+		maxTokens: options.maxTokens ?? DEFAULT_GRADE_MAX_TOKENS,
+		...options.signal !== void 0 ? { signal: options.signal } : {},
+		outputType: { kind: "structured" }
+	};
+}
+/**
+* Parse a grader model output into a {@link RetrievalGrade}. Tolerates a
+* bare JSON object, a fenced block, and chatty text around the object.
+*
+* **Fail-safe = stop.** When the verdict can't be read (undefined / empty
+* / unparseable / missing `sufficient`), returns
+* `{ sufficient: true, confidence: 0, reformulation: null }` so a broken
+* grader degrades to a single pass rather than looping or falsely
+* abstaining. A *parsed* `sufficient: false` (a real insufficiency
+* verdict) is preserved.
+*
+* @stable
+*/
+function parseGrade(text) {
+	const stop = {
+		sufficient: true,
+		confidence: 0,
+		reformulation: null
+	};
+	if (text === void 0) return stop;
+	const stripped = stripFence(text).trim();
+	if (stripped.length === 0) return stop;
+	const obj = tryParseObject(stripped);
+	if (obj === null) return stop;
+	const sufficient = coerceBool(obj.sufficient);
+	if (sufficient === null) return stop;
+	const confidence = coerceConfidence(obj.confidence, sufficient);
+	const reformulation = sufficient ? null : coerceReformulation(obj.reformulation);
+	const reason = coerceReason(obj.reason);
+	return {
+		sufficient,
+		confidence,
+		reformulation,
+		...reason !== void 0 ? { reason } : {}
+	};
+}
+/**
+* Wrap a {@link Provider} as a {@link RetrievalGrader}. **Resilient**: a
+* provider error or unparseable response degrades to the
+* {@link parseGrade} "stop" grade so grading never throws into the loop
+* (and a flaky grader can't drive endless reformulation).
+*
+* @stable
+*/
+function createProviderRetrievalGrader(provider, options = {}) {
+	const maxTokens = options.maxTokens ?? DEFAULT_GRADE_MAX_TOKENS;
+	return { async grade(query, snippets, opts = {}) {
+		try {
+			const request = buildGradeRequest(query, snippets, {
+				maxTokens,
+				...opts.signal !== void 0 ? { signal: opts.signal } : {},
+				...opts.triedQueries !== void 0 ? { triedQueries: opts.triedQueries } : {}
+			});
+			return parseGrade((await provider.generate(request)).text);
+		} catch {
+			return {
+				sufficient: true,
+				confidence: 0,
+				reformulation: null
+			};
+		}
+	} };
+}
+/**
+* Run the gated grade-then-reformulate loop.
+*
+* Flow: assess difficulty → retrieve (pass 1) → if not hard *or* no
+* grader, return single-shot → else grade; if sufficient, return; if
+* weak and a reformulation is offered and the cap is not hit, retrieve
+* again (widened) and re-grade; otherwise **abstain**.
+*
+* @stable
+*/
+async function runIterativeRetrieval(query, deps, options = {}) {
+	const gate = options.forceHard === true ? {
+		hard: true,
+		score: 1,
+		signals: ["forced"]
+	} : assessQueryDifficulty(query, options.difficulty ?? {});
+	const cap = clampIterations(options.maxIterations);
+	const maxSnippets = Math.max(1, options.maxGradeSnippets ?? DEFAULT_MAX_GRADE_SNIPPETS);
+	const signal = options.signal;
+	const passLists = [];
+	const accumulate = (hits) => {
+		passLists.push([...hits]);
+	};
+	const queries = [query];
+	const tried = new Set([query.trim().toLowerCase()]);
+	accumulate(await deps.retrieve(query, false, signal));
+	const grader = deps.grader;
+	if (!gate.hard || grader === null) return finalize(deps, passLists, 1, gate.hard, true, false, queries, options.maxResults);
+	let passes = 1;
+	for (;;) {
+		const window = interleave(passLists, maxSnippets, deps.idOf).map(deps.snippetOf);
+		const grade = await grader.grade(query, window, {
+			...signal !== void 0 ? { signal } : {},
+			...queries.length > 1 ? { triedQueries: queries.slice(1) } : {}
+		});
+		if (grade.sufficient) return finalize(deps, passLists, passes, true, true, false, queries, options.maxResults);
+		if (passes >= cap) break;
+		const next = normalizeReformulation(grade.reformulation, tried);
+		if (next === null) break;
+		passes += 1;
+		queries.push(next);
+		tried.add(next.toLowerCase());
+		accumulate(await deps.retrieve(next, true, signal));
+	}
+	return finalize(deps, passLists, passes, true, false, true, queries, options.maxResults);
+}
+/**
+* Round-robin interleave of per-pass lists, deduped by id: hit 1 of
+* every pass, then hit 2 of every pass, … — guarantees the latest
+* pass's top hits enter a window of any size.
+*/
+function interleave(lists, limit, idOf) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	const longest = lists.reduce((max, l) => Math.max(max, l.length), 0);
+	for (let rank = 0; rank < longest && out.length < limit; rank += 1) for (const list of lists) {
+		const hit = list[rank];
+		if (hit === void 0) continue;
+		const id = idOf(hit);
+		if (seen.has(id)) continue;
+		seen.add(id);
+		out.push(hit);
+		if (out.length >= limit) break;
+	}
+	return out;
+}
+function finalize(deps, passLists, iterations, gateHard, sufficient, abstained, queries, maxResults) {
+	const ranked = typeof deps.fuse === "function" ? dedupBy(deps.fuse(passLists), deps.idOf) : interleave(passLists, Number.POSITIVE_INFINITY, deps.idOf);
+	return {
+		hits: maxResults !== void 0 && maxResults >= 0 ? ranked.slice(0, maxResults) : ranked.slice(),
+		iterations,
+		gateHard,
+		sufficient,
+		abstained,
+		queries: [...queries]
+	};
+}
+function dedupBy(hits, idOf) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const hit of hits) {
+		const id = idOf(hit);
+		if (seen.has(id)) continue;
+		seen.add(id);
+		out.push(hit);
+	}
+	return out;
+}
+function clampIterations(value) {
+	const n = value ?? DEFAULT_MAX_ITERATIONS;
+	if (!Number.isFinite(n)) return DEFAULT_MAX_ITERATIONS;
+	return Math.min(MAX_ITERATIONS_CEILING, Math.max(1, Math.floor(n)));
+}
+/**
+* Normalise a proposed reformulation: trim, drop empties, and reject a
+* query already tried (case-insensitive) so the loop never re-treads and
+* cannot spin.
+*/
+function normalizeReformulation(raw, tried) {
+	if (raw === null) return null;
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) return null;
+	if (tried.has(trimmed.toLowerCase())) return null;
+	return trimmed;
+}
+function wordCount(text) {
+	const trimmed = text.trim();
+	return trimmed.length === 0 ? 0 : trimmed.split(/\s+/u).length;
+}
+function countCommas(text) {
+	return (text.match(/,/gu) ?? []).length;
+}
+function questionMarkCount(text) {
+	return (text.match(/\?/gu) ?? []).length;
+}
+function coerceBool(value) {
+	if (typeof value === "boolean") return value;
+	if (typeof value === "string") {
+		const v = value.trim().toLowerCase();
+		if (v === "true" || v === "yes" || v === "sufficient") return true;
+		if (v === "false" || v === "no" || v === "insufficient") return false;
+	}
+	return null;
+}
+function coerceConfidence(value, sufficient) {
+	if (typeof value === "number" && Number.isFinite(value)) return Math.min(1, Math.max(0, value));
+	return sufficient ? .8 : .3;
+}
+function coerceReformulation(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return null;
+	return trimmed.length > 1024 ? trimmed.slice(0, 1024) : trimmed;
+}
+function coerceReason(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length === 0 ? void 0 : trimmed;
+}
+function tryParseObject(text) {
+	const direct = tryJson(text);
+	if (isRecord(direct)) return direct;
+	const start = text.indexOf("{");
+	const end = text.lastIndexOf("}");
+	if (start >= 0 && end > start) {
+		const sliced = tryJson(text.slice(start, end + 1));
+		if (isRecord(sliced)) return sliced;
+	}
+	return null;
+}
+function tryJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+function stripFence(text) {
+	return /^```[^\n]*\n([\s\S]*?)\n```/u.exec(text.trim())?.[1] ?? text;
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+//#endregion
+export { DEFAULT_DIFFICULTY_THRESHOLD, DEFAULT_MAX_ITERATIONS, MAX_ITERATIONS_CEILING, RETRIEVAL_GRADE_SYSTEM_PROMPT, assessQueryDifficulty, buildGradeRequest, createProviderRetrievalGrader, parseGrade, runIterativeRetrieval };
+//# sourceMappingURL=iterative.js.map

package/dist/search/iterative.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterative.js","names":["signals: string[]","stop: RetrievalGrade","passLists: Array<ReadonlyArray<H>>","queries: string[]","out: H[]"],"sources":["../../src/search/iterative.ts"],"sourcesContent":["/**\n * Agentic / iterative retrieval for hard queries (P2-4) — a **gated**,\n * CRAG/Self-RAG-style grade-then-reformulate loop.\n *\n * Some multi-hop / temporal questions can't be answered from a single\n * retrieval pass; the naive system returns a confident-but-wrong answer\n * instead of retrieving again. This module adds a small loop: grade the\n * retrieved memories for sufficiency and, when weak, reformulate the\n * query and retrieve once more (optionally widening to the P2-1 graph) —\n * up to a hard iteration cap, then **abstain** rather than confabulate.\n *\n * Both CRAG (arXiv:2401.15884) and Self-RAG (arXiv:2310.11511) add\n * latency/cost, so the literature's advice — and this module's design —\n * is to *gate* the loop, not make it default:\n *\n *   1. A cheap, **local** {@link assessQueryDifficulty} heuristic decides\n *      whether a query is even a candidate; simple lookups never enter\n *      the loop (no provider call) and stay single-shot.\n *   2. The grade/reformulate step needs a {@link RetrievalGrader}; with\n *      none configured the loop degrades to a single retrieval pass. The\n *      only provider-backed grader, {@link createProviderRetrievalGrader},\n *      is **resilient**: any provider error or unparseable output degrades\n *      to a \"stop\" grade rather than throwing or looping forever.\n *   3. A mandatory iteration cap bounds the worst case regardless of the\n *      grader.\n *\n * The module is provider-agnostic — it imports only `@graphorin/core`\n * types and never performs I/O itself; {@link runIterativeRetrieval} is a\n * pure orchestrator over an injected `retrieve` function + grader, so the\n * loop is unit-testable without a store or a model.\n *\n * @packageDocumentation\n */\n\nimport type { Provider, ProviderRequest } from '@graphorin/core';\n\n/** Default hard ceiling on total retrieval passes (gate + cap mandatory). */\nexport const DEFAULT_MAX_ITERATIONS = 3;\n\n/**\n * Absolute clamp on total retrieval passes, applied regardless of the\n * caller's `maxIterations` — a latency guardrail so a mis-configured\n * caller can never unbound the loop.\n */\nexport const MAX_ITERATIONS_CEILING = 5;\n\n/** Default score (0..1) at or above which a query is classified as hard. */\nexport const DEFAULT_DIFFICULTY_THRESHOLD = 0.5;\n\n/** Default output-token ceiling for a single grade call. */\nconst DEFAULT_GRADE_MAX_TOKENS = 256;\n\n/** Default number of retrieved snippets shown to the grader per pass. */\nconst DEFAULT_MAX_GRADE_SNIPPETS = 8;\n\n// ---------------------------------------------------------------------------\n// Difficulty gate (pure, local — no I/O, no provider)\n// ---------------------------------------------------------------------------\n\n/**\n * Outcome of the heuristic difficulty gate. `hard` is the gating\n * decision (`score >= threshold`); `signals` lists which heuristic\n * categories fired, for explainability / tracing.\n *\n * @stable\n */\nexport interface DifficultyAssessment {\n  readonly hard: boolean;\n  /** Aggregate difficulty score, clamped to `[0, 1]`. */\n  readonly score: number;\n  /** Heuristic categories that fired (`'multi-hop'`, `'temporal'`, …). */\n  readonly signals: ReadonlyArray<string>;\n}\n\n/**\n * Tuning for {@link assessQueryDifficulty}.\n *\n * @stable\n */\nexport interface DifficultyGateOptions {\n  /** Minimum score (0..1) to classify the query as hard. Default 0.5. */\n  readonly threshold?: number;\n}\n\n/** Relational / referential markers implying a hop to another entity. */\nconst RE_REL_PRONOUN = /\\b(?:who|whom|whose|which)\\b/iu;\nconst RE_OF_CHAIN = /\\bthe\\s+\\w+\\s+of\\b/iu;\nconst RE_POSSESSIVE = /\\b[\\w-]+'s\\b/giu;\nconst RE_DESC_REF =\n  /\\bthe\\s+(?:person|people|place|thing|one|company|team|book|restaurant|project|guy|woman|man)\\b/iu;\n/** Temporal ordering / relative-time markers. */\nconst RE_TEMPORAL =\n  /\\b(?:before|after|when|while|during|since|until|first|last|earliest|latest|previously|originally|ago|prior|then|recently|used\\s+to)\\b/iu;\n/** Comparison / superlative markers. */\nconst RE_COMPARISON =\n  /\\b(?:most|least|more|less|fewer|greater|biggest|largest|smallest|oldest|newest|best|worst|highest|lowest|compared?|versus|vs\\.?|between)\\b/iu;\n/** Clause-joining conjunctions used to count clauses. */\nconst RE_CONJUNCTION = /\\b(?:and|or|but|then)\\b/giu;\n\nconst W_MULTI_HOP = 0.4;\nconst W_TEMPORAL = 0.3;\nconst W_COMPARISON = 0.3;\nconst W_MULTI_CLAUSE = 0.2;\nconst W_LONG = 0.15;\nconst LONG_WORD_COUNT = 12;\n\n/**\n * Score a query's retrieval difficulty with cheap, deterministic, fully\n * **local** heuristics (no I/O). Conservative by design — it prefers to\n * leave a query single-shot (`hard: false`) unless several\n * multi-hop / temporal / comparison signals stack up, so the gate adds\n * passes only where they are likely to help. Used by\n * {@link runIterativeRetrieval} to decide whether to enter the loop.\n *\n * @stable\n */\nexport function assessQueryDifficulty(\n  query: string,\n  options: DifficultyGateOptions = {},\n): DifficultyAssessment {\n  const threshold = options.threshold ?? DEFAULT_DIFFICULTY_THRESHOLD;\n  const signals: string[] = [];\n  let score = 0;\n\n  const possessiveCount = (query.match(RE_POSSESSIVE) ?? []).length;\n  const multiHop =\n    RE_REL_PRONOUN.test(query) ||\n    RE_OF_CHAIN.test(query) ||\n    RE_DESC_REF.test(query) ||\n    possessiveCount >= 2;\n  if (multiHop) {\n    signals.push('multi-hop');\n    score += W_MULTI_HOP;\n  }\n  if (RE_TEMPORAL.test(query)) {\n    signals.push('temporal');\n    score += W_TEMPORAL;\n  }\n  if (RE_COMPARISON.test(query)) {\n    signals.push('comparison');\n    score += W_COMPARISON;\n  }\n  const clauseSignals = (query.match(RE_CONJUNCTION) ?? []).length + countCommas(query);\n  if (clauseSignals >= 2 || questionMarkCount(query) >= 2) {\n    signals.push('multi-clause');\n    score += W_MULTI_CLAUSE;\n  }\n  if (wordCount(query) >= LONG_WORD_COUNT) {\n    signals.push('long');\n    score += W_LONG;\n  }\n\n  const clamped = Math.min(1, score);\n  return { hard: clamped >= threshold, score: clamped, signals };\n}\n\n// ---------------------------------------------------------------------------\n// Retrieval grader seam (provider-agnostic)\n// ---------------------------------------------------------------------------\n\n/**\n * Verdict from grading a retrieved candidate set against a query.\n *\n * @stable\n */\nexport interface RetrievalGrade {\n  /** Whether the retrieved memories suffice to answer the query. */\n  readonly sufficient: boolean;\n  /** Grader confidence, clamped to `[0, 1]`. */\n  readonly confidence: number;\n  /**\n   * A single better search query to try next, or `null` when the grader\n   * proposes none (the loop then stops / abstains).\n   */\n  readonly reformulation: string | null;\n  /** Optional short rationale (never surfaced in spans). */\n  readonly reason?: string;\n}\n\n/**\n * Per-call options for a {@link RetrievalGrader}.\n *\n * @stable\n */\nexport interface RetrievalGradeOptions {\n  /** Cancellation signal forwarded to the underlying provider call. */\n  readonly signal?: AbortSignal;\n  /**\n   * Reformulations already attempted (MRET-11). Surfaced to the grader\n   * as context so it can propose something genuinely new — the grade\n   * itself is ALWAYS judged against the original question, never a\n   * reformulation (a narrowed sub-query must not be declared\n   * \"sufficient\" while the original multi-hop question is not).\n   */\n  readonly triedQueries?: ReadonlyArray<string>;\n}\n\n/**\n * Pluggable retrieval-grader seam consumed by the iterative loop. The\n * built-in provider-backed implementation lives in\n * {@link createProviderRetrievalGrader}; advanced callers can supply a\n * bespoke grader (e.g. a deterministic heuristic).\n *\n * Implementations MUST degrade gracefully — return a \"stop\" grade rather\n * than throw — so a grader failure never breaks recall.\n *\n * @stable\n */\nexport interface RetrievalGrader {\n  grade(\n    query: string,\n    snippets: ReadonlyArray<string>,\n    options?: RetrievalGradeOptions,\n  ): Promise<RetrievalGrade>;\n}\n\n/**\n * System prompt for the retrieval grader. Asks for a bare JSON verdict;\n * {@link parseGrade} also tolerates a chatty model.\n *\n * @internal\n */\nexport const RETRIEVAL_GRADE_SYSTEM_PROMPT =\n  'You are a retrieval grader for a personal memory store. Given a question and a ' +\n  'numbered list of retrieved memories, judge whether they are SUFFICIENT to answer ' +\n  'the question correctly and completely. Respond with ONLY a JSON object: ' +\n  '{\"sufficient\": boolean, \"confidence\": number between 0 and 1, \"reformulation\": ' +\n  'string or null, \"reason\": string}. Set \"sufficient\" to true only if the memories ' +\n  'actually contain the answer — do not guess. When insufficient, set \"reformulation\" ' +\n  'to a single alternative search query likely to retrieve the missing information ' +\n  '(vary entities, time frame, or specificity); otherwise null. Output only the JSON ' +\n  'object — no prose, no markdown.';\n\n/**\n * Build the grade request. Pure — no I/O. Temperature 0 so the verdict\n * is as stable as the model allows.\n *\n * @stable\n */\nexport function buildGradeRequest(\n  query: string,\n  snippets: ReadonlyArray<string>,\n  options: {\n    readonly maxTokens?: number;\n    readonly signal?: AbortSignal;\n    readonly triedQueries?: ReadonlyArray<string>;\n  } = {},\n): ProviderRequest {\n  const body =\n    snippets.length === 0 ? '(none)' : snippets.map((s, i) => `[${i + 1}] ${s}`).join('\\n');\n  const tried =\n    options.triedQueries !== undefined && options.triedQueries.length > 0\n      ? `\\n\\nQueries already tried (do not repeat them): ${options.triedQueries.join(' | ')}`\n      : '';\n  const content =\n    `Question: ${query}\\n\\nRetrieved memories:\\n${body}${tried}\\n\\n` +\n    'Grade whether these memories are sufficient to answer the question. If not, ' +\n    'propose a single better search query.';\n  return {\n    messages: [{ role: 'user', content }],\n    systemMessage: RETRIEVAL_GRADE_SYSTEM_PROMPT,\n    temperature: 0,\n    maxTokens: options.maxTokens ?? DEFAULT_GRADE_MAX_TOKENS,\n    ...(options.signal !== undefined ? { signal: options.signal } : {}),\n    outputType: { kind: 'structured' },\n  };\n}\n\n/**\n * Parse a grader model output into a {@link RetrievalGrade}. Tolerates a\n * bare JSON object, a fenced block, and chatty text around the object.\n *\n * **Fail-safe = stop.** When the verdict can't be read (undefined / empty\n * / unparseable / missing `sufficient`), returns\n * `{ sufficient: true, confidence: 0, reformulation: null }` so a broken\n * grader degrades to a single pass rather than looping or falsely\n * abstaining. A *parsed* `sufficient: false` (a real insufficiency\n * verdict) is preserved.\n *\n * @stable\n */\nexport function parseGrade(text: string | undefined): RetrievalGrade {\n  const stop: RetrievalGrade = { sufficient: true, confidence: 0, reformulation: null };\n  if (text === undefined) return stop;\n  const stripped = stripFence(text).trim();\n  if (stripped.length === 0) return stop;\n  const obj = tryParseObject(stripped);\n  if (obj === null) return stop;\n  const sufficient = coerceBool(obj.sufficient);\n  if (sufficient === null) return stop;\n  const confidence = coerceConfidence(obj.confidence, sufficient);\n  const reformulation = sufficient ? null : coerceReformulation(obj.reformulation);\n  const reason = coerceReason(obj.reason);\n  return {\n    sufficient,\n    confidence,\n    reformulation,\n    ...(reason !== undefined ? { reason } : {}),\n  };\n}\n\n/**\n * Wrap a {@link Provider} as a {@link RetrievalGrader}. **Resilient**: a\n * provider error or unparseable response degrades to the\n * {@link parseGrade} \"stop\" grade so grading never throws into the loop\n * (and a flaky grader can't drive endless reformulation).\n *\n * @stable\n */\nexport function createProviderRetrievalGrader(\n  provider: Provider,\n  options: { readonly maxTokens?: number } = {},\n): RetrievalGrader {\n  const maxTokens = options.maxTokens ?? DEFAULT_GRADE_MAX_TOKENS;\n  return {\n    async grade(query, snippets, opts = {}): Promise<RetrievalGrade> {\n      try {\n        const request = buildGradeRequest(query, snippets, {\n          maxTokens,\n          ...(opts.signal !== undefined ? { signal: opts.signal } : {}),\n          ...(opts.triedQueries !== undefined ? { triedQueries: opts.triedQueries } : {}),\n        });\n        const response = await provider.generate(request);\n        return parseGrade(response.text);\n      } catch {\n        return { sufficient: true, confidence: 0, reformulation: null };\n      }\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// The bounded loop (pure orchestration over injected retrieve + grader)\n// ---------------------------------------------------------------------------\n\n/**\n * Result of an iterative retrieval run.\n *\n * @stable\n */\nexport interface IterativeRetrievalResult<H> {\n  /** Accumulated hits across all passes (deduped, in discovery order). */\n  readonly hits: ReadonlyArray<H>;\n  /** Number of retrieval passes performed (≥ 1). */\n  readonly iterations: number;\n  /** Difficulty-gate verdict (whether the loop was eligible to run). */\n  readonly gateHard: boolean;\n  /** Final sufficiency verdict. */\n  readonly sufficient: boolean;\n  /**\n   * `true` when the loop exhausted its cap / ran out of reformulations\n   * while still judged insufficient — the caller should abstain rather\n   * than answer from `hits`.\n   */\n  readonly abstained: boolean;\n  /** The sequence of queries tried (original first). */\n  readonly queries: ReadonlyArray<string>;\n}\n\n/**\n * Dependencies injected into {@link runIterativeRetrieval}. The loop does\n * no I/O of its own — `retrieve` and `grader` own all side effects.\n *\n * @stable\n */\nexport interface IterativeRetrievalDeps<H> {\n  /**\n   * Run one retrieval pass for `query`. `widen` is `true` on\n   * reformulation passes so the caller can broaden recall (e.g. enable\n   * P2-1 one-hop graph expansion).\n   */\n  retrieve(query: string, widen: boolean, signal?: AbortSignal): Promise<ReadonlyArray<H>>;\n  /** Snippet shown to the grader for a hit. */\n  snippetOf(hit: H): string;\n  /** Stable id used to dedup hits across passes. */\n  idOf(hit: H): string;\n  /** Grader; `null` ⇒ single-shot (no grading, no provider call). */\n  grader: RetrievalGrader | null;\n  /**\n   * Re-fuse the per-pass hit lists into one ranked list (MRET-2).\n   * Receives one list per pass in pass order; the result feeds the\n   * final `maxResults` cut so a pass-2 find can outrank pass-1 noise.\n   * Absent ⇒ the loop falls back to round-robin interleaving (still\n   * strictly better than the old discovery-order cut).\n   */\n  fuse?(lists: ReadonlyArray<ReadonlyArray<H>>): ReadonlyArray<H>;\n}\n\n/**\n * Options for {@link runIterativeRetrieval}.\n *\n * @stable\n */\nexport interface IterativeRetrievalOptions {\n  /** Total-pass cap; clamped to `[1, {@link MAX_ITERATIONS_CEILING}]`. */\n  readonly maxIterations?: number;\n  /** Difficulty-gate tuning. */\n  readonly difficulty?: DifficultyGateOptions;\n  /** Skip the heuristic gate and force the loop (still capped). */\n  readonly forceHard?: boolean;\n  /** Max snippets passed to the grader per pass. Default 8. */\n  readonly maxGradeSnippets?: number;\n  /** Cap on the returned hit count (omitted ⇒ all accumulated). */\n  readonly maxResults?: number;\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Run the gated grade-then-reformulate loop.\n *\n * Flow: assess difficulty → retrieve (pass 1) → if not hard *or* no\n * grader, return single-shot → else grade; if sufficient, return; if\n * weak and a reformulation is offered and the cap is not hit, retrieve\n * again (widened) and re-grade; otherwise **abstain**.\n *\n * @stable\n */\nexport async function runIterativeRetrieval<H>(\n  query: string,\n  deps: IterativeRetrievalDeps<H>,\n  options: IterativeRetrievalOptions = {},\n): Promise<IterativeRetrievalResult<H>> {\n  const gate =\n    options.forceHard === true\n      ? { hard: true, score: 1, signals: ['forced'] as ReadonlyArray<string> }\n      : assessQueryDifficulty(query, options.difficulty ?? {});\n  const cap = clampIterations(options.maxIterations);\n  const maxSnippets = Math.max(1, options.maxGradeSnippets ?? DEFAULT_MAX_GRADE_SNIPPETS);\n  const signal = options.signal;\n\n  // MRET-2: hits are tracked PER PASS — RAW, including cross-pass\n  // repeats, so rank fusion can reward consensus between passes. The\n  // grade window and the final list dedup by id at read time. The old\n  // flat append meant pass 1 saturated the first `maxSnippets` forever\n  // and the final cut ran in discovery order.\n  const passLists: Array<ReadonlyArray<H>> = [];\n  const accumulate = (hits: ReadonlyArray<H>): void => {\n    passLists.push([...hits]);\n  };\n  const queries: string[] = [query];\n  const tried = new Set<string>([query.trim().toLowerCase()]);\n\n  // Pass 1 — always single-shot, no widening.\n  accumulate(await deps.retrieve(query, false, signal));\n\n  // Gate: the loop is eligible only when the query is judged hard *and* a\n  // grader exists. Otherwise stay single-shot — we did not grade, so we\n  // make no abstention claim.\n  const grader = deps.grader;\n  if (!gate.hard || grader === null) {\n    return finalize(deps, passLists, 1, gate.hard, true, false, queries, options.maxResults);\n  }\n\n  let passes = 1;\n  for (;;) {\n    // MRET-2: the grade window interleaves the TOP hits of every pass\n    // (latest pass included) instead of replaying pass 1's head.\n    // MRET-11: sufficiency is always judged against the ORIGINAL\n    // question; reformulations ride along as already-tried context.\n    const window = interleave(passLists, maxSnippets, deps.idOf).map(deps.snippetOf);\n    const grade = await grader.grade(query, window, {\n      ...(signal !== undefined ? { signal } : {}),\n      ...(queries.length > 1 ? { triedQueries: queries.slice(1) } : {}),\n    });\n    if (grade.sufficient) {\n      return finalize(deps, passLists, passes, true, true, false, queries, options.maxResults);\n    }\n    if (passes >= cap) break;\n    const next = normalizeReformulation(grade.reformulation, tried);\n    if (next === null) break;\n    passes += 1;\n    queries.push(next);\n    tried.add(next.toLowerCase());\n    accumulate(await deps.retrieve(next, true, signal));\n  }\n  // Cap reached or no further reformulation while still insufficient ⇒ abstain.\n  return finalize(deps, passLists, passes, true, false, true, queries, options.maxResults);\n}\n\n/**\n * Round-robin interleave of per-pass lists, deduped by id: hit 1 of\n * every pass, then hit 2 of every pass, … — guarantees the latest\n * pass's top hits enter a window of any size.\n */\nfunction interleave<H>(\n  lists: ReadonlyArray<ReadonlyArray<H>>,\n  limit: number,\n  idOf: (hit: H) => string,\n): H[] {\n  const out: H[] = [];\n  const seen = new Set<string>();\n  const longest = lists.reduce((max, l) => Math.max(max, l.length), 0);\n  for (let rank = 0; rank < longest && out.length < limit; rank += 1) {\n    for (const list of lists) {\n      const hit = list[rank];\n      if (hit === undefined) continue;\n      const id = idOf(hit);\n      if (seen.has(id)) continue;\n      seen.add(id);\n      out.push(hit);\n      if (out.length >= limit) break;\n    }\n  }\n  return out;\n}\n\nfunction finalize<H>(\n  deps: IterativeRetrievalDeps<H>,\n  passLists: ReadonlyArray<ReadonlyArray<H>>,\n  iterations: number,\n  gateHard: boolean,\n  sufficient: boolean,\n  abstained: boolean,\n  queries: ReadonlyArray<string>,\n  maxResults: number | undefined,\n): IterativeRetrievalResult<H> {\n  // MRET-2: re-rank ACROSS passes before the cut — discovery order let\n  // pass-1 noise crowd out the pass-2 hit that actually answers.\n  const ranked =\n    typeof deps.fuse === 'function'\n      ? dedupBy(deps.fuse(passLists), deps.idOf)\n      : interleave(passLists, Number.POSITIVE_INFINITY, deps.idOf);\n  const capped =\n    maxResults !== undefined && maxResults >= 0 ? ranked.slice(0, maxResults) : ranked.slice();\n  return { hits: capped, iterations, gateHard, sufficient, abstained, queries: [...queries] };\n}\n\nfunction dedupBy<H>(hits: ReadonlyArray<H>, idOf: (hit: H) => string): H[] {\n  const seen = new Set<string>();\n  const out: H[] = [];\n  for (const hit of hits) {\n    const id = idOf(hit);\n    if (seen.has(id)) continue;\n    seen.add(id);\n    out.push(hit);\n  }\n  return out;\n}\n\nfunction clampIterations(value: number | undefined): number {\n  const n = value ?? DEFAULT_MAX_ITERATIONS;\n  if (!Number.isFinite(n)) return DEFAULT_MAX_ITERATIONS;\n  return Math.min(MAX_ITERATIONS_CEILING, Math.max(1, Math.floor(n)));\n}\n\n/**\n * Normalise a proposed reformulation: trim, drop empties, and reject a\n * query already tried (case-insensitive) so the loop never re-treads and\n * cannot spin.\n */\nfunction normalizeReformulation(raw: string | null, tried: ReadonlySet<string>): string | null {\n  if (raw === null) return null;\n  const trimmed = raw.trim();\n  if (trimmed.length === 0) return null;\n  if (tried.has(trimmed.toLowerCase())) return null;\n  return trimmed;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction wordCount(text: string): number {\n  const trimmed = text.trim();\n  return trimmed.length === 0 ? 0 : trimmed.split(/\\s+/u).length;\n}\n\nfunction countCommas(text: string): number {\n  return (text.match(/,/gu) ?? []).length;\n}\n\nfunction questionMarkCount(text: string): number {\n  return (text.match(/\\?/gu) ?? []).length;\n}\n\nfunction coerceBool(value: unknown): boolean | null {\n  if (typeof value === 'boolean') return value;\n  if (typeof value === 'string') {\n    const v = value.trim().toLowerCase();\n    if (v === 'true' || v === 'yes' || v === 'sufficient') return true;\n    if (v === 'false' || v === 'no' || v === 'insufficient') return false;\n  }\n  return null;\n}\n\nfunction coerceConfidence(value: unknown, sufficient: boolean): number {\n  if (typeof value === 'number' && Number.isFinite(value)) {\n    return Math.min(1, Math.max(0, value));\n  }\n  return sufficient ? 0.8 : 0.3;\n}\n\nfunction coerceReformulation(value: unknown): string | null {\n  if (typeof value !== 'string') return null;\n  const trimmed = value.trim();\n  if (trimmed.length === 0) return null;\n  return trimmed.length > 1024 ? trimmed.slice(0, 1024) : trimmed;\n}\n\nfunction coerceReason(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined;\n  const trimmed = value.trim();\n  return trimmed.length === 0 ? undefined : trimmed;\n}\n\nfunction tryParseObject(text: string): Record<string, unknown> | null {\n  const direct = tryJson(text);\n  if (isRecord(direct)) return direct;\n  const start = text.indexOf('{');\n  const end = text.lastIndexOf('}');\n  if (start >= 0 && end > start) {\n    const sliced = tryJson(text.slice(start, end + 1));\n    if (isRecord(sliced)) return sliced;\n  }\n  return null;\n}\n\nfunction tryJson(text: string): unknown {\n  try {\n    return JSON.parse(text);\n  } catch {\n    return undefined;\n  }\n}\n\nfunction stripFence(text: string): string {\n  const match = /^```[^\\n]*\\n([\\s\\S]*?)\\n```/u.exec(text.trim());\n  return match?.[1] ?? text;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n"],"mappings":"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"}