wiki-graph-core 0.3.1

package/dist/wikimatch/enrichment.js

@@ -0,0 +1,55 @@
+import { WikipageResolver } from "../wikipage/index.js";
+async function enrichWikimatchCandidates(candidates, options = {}) {
+  if (candidates.length === 0) {
+    return [];
+  }
+  const resolver = await WikipageResolver.open({
+    ...options.resolverOptions ?? {},
+    ...options.progress === void 0 ? {} : { progress: options.progress }
+  });
+  try {
+    return applyQidResolutions(
+      candidates,
+      await resolver.resolveQids(listQids(candidates))
+    );
+  } finally {
+    await resolver.close();
+  }
+}
+function applyQidResolutions(candidates, resolutions) {
+  const resolutionsByQid = new Map(
+    resolutions.map((resolution) => [resolution.qid, resolution])
+  );
+  return candidates.map((candidate) => ({
+    ...candidate,
+    qidOptions: candidate.qidOptions.map(
+      (option) => enrichQidOption(option, resolutionsByQid.get(option.qid))
+    )
+  }));
+}
+function enrichQidOption(option, resolution) {
+  if (resolution === void 0) {
+    return option;
+  }
+  return {
+    ...option,
+    ...resolution.description === void 0 ? {} : { description: resolution.description },
+    ...resolution.disambiguation === void 0 ? {} : { disambiguation: resolution.disambiguation },
+    isDisambiguation: resolution.isDisambiguation,
+    ...resolution.label === void 0 ? {} : { label: resolution.label }
+  };
+}
+function listQids(candidates) {
+  return [
+    ...new Set(
+      candidates.flatMap(
+        (candidate) => candidate.qidOptions.map((option) => option.qid)
+      )
+    )
+  ];
+}
+export {
+  applyQidResolutions,
+  enrichWikimatchCandidates
+};
+//# sourceMappingURL=enrichment.js.map

package/dist/wikimatch/enrichment.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wikimatch/enrichment.ts"],"sourcesContent":["import { WikipageResolver } from \"../wikipage/index.js\";\n\nimport type {\n  QidResolution,\n  WikipageResolverOptions,\n  WikipageResolveProgressReporter,\n} from \"../wikipage/index.js\";\nimport type { WikimatchCandidate, WikimatchQidOption } from \"./types.js\";\n\nexport async function enrichWikimatchCandidates(\n  candidates: readonly WikimatchCandidate[],\n  options: {\n    readonly progress?: WikipageResolveProgressReporter;\n    readonly resolverOptions?: Omit<WikipageResolverOptions, \"progress\">;\n  } = {},\n): Promise<readonly WikimatchCandidate[]> {\n  if (candidates.length === 0) {\n    return [];\n  }\n\n  const resolver = await WikipageResolver.open({\n    ...(options.resolverOptions ?? {}),\n    ...(options.progress === undefined ? {} : { progress: options.progress }),\n  });\n\n  try {\n    return applyQidResolutions(\n      candidates,\n      await resolver.resolveQids(listQids(candidates)),\n    );\n  } finally {\n    await resolver.close();\n  }\n}\n\nexport function applyQidResolutions(\n  candidates: readonly WikimatchCandidate[],\n  resolutions: readonly QidResolution[],\n): readonly WikimatchCandidate[] {\n  const resolutionsByQid = new Map(\n    resolutions.map((resolution) => [resolution.qid, resolution]),\n  );\n\n  return candidates.map((candidate) => ({\n    ...candidate,\n    qidOptions: candidate.qidOptions.map((option) =>\n      enrichQidOption(option, resolutionsByQid.get(option.qid)),\n    ),\n  }));\n}\n\nfunction enrichQidOption(\n  option: WikimatchQidOption,\n  resolution: QidResolution | undefined,\n): WikimatchQidOption {\n  if (resolution === undefined) {\n    return option;\n  }\n\n  return {\n    ...option,\n    ...(resolution.description === undefined\n      ? {}\n      : { description: resolution.description }),\n    ...(resolution.disambiguation === undefined\n      ? {}\n      : { disambiguation: resolution.disambiguation }),\n    isDisambiguation: resolution.isDisambiguation,\n    ...(resolution.label === undefined ? {} : { label: resolution.label }),\n  };\n}\n\nfunction listQids(\n  candidates: readonly WikimatchCandidate[],\n): readonly string[] {\n  return [\n    ...new Set(\n      candidates.flatMap((candidate) =>\n        candidate.qidOptions.map((option) => option.qid),\n      ),\n    ),\n  ];\n}\n"],"mappings":"AAAA,SAAS,wBAAwB;AASjC,eAAsB,0BACpB,YACA,UAGI,CAAC,GACmC;AACxC,MAAI,WAAW,WAAW,GAAG;AAC3B,WAAO,CAAC;AAAA,EACV;AAEA,QAAM,WAAW,MAAM,iBAAiB,KAAK;AAAA,IAC3C,GAAI,QAAQ,mBAAmB,CAAC;AAAA,IAChC,GAAI,QAAQ,aAAa,SAAY,CAAC,IAAI,EAAE,UAAU,QAAQ,SAAS;AAAA,EACzE,CAAC;AAED,MAAI;AACF,WAAO;AAAA,MACL;AAAA,MACA,MAAM,SAAS,YAAY,SAAS,UAAU,CAAC;AAAA,IACjD;AAAA,EACF,UAAE;AACA,UAAM,SAAS,MAAM;AAAA,EACvB;AACF;AAEO,SAAS,oBACd,YACA,aAC+B;AAC/B,QAAM,mBAAmB,IAAI;AAAA,IAC3B,YAAY,IAAI,CAAC,eAAe,CAAC,WAAW,KAAK,UAAU,CAAC;AAAA,EAC9D;AAEA,SAAO,WAAW,IAAI,CAAC,eAAe;AAAA,IACpC,GAAG;AAAA,IACH,YAAY,UAAU,WAAW;AAAA,MAAI,CAAC,WACpC,gBAAgB,QAAQ,iBAAiB,IAAI,OAAO,GAAG,CAAC;AAAA,IAC1D;AAAA,EACF,EAAE;AACJ;AAEA,SAAS,gBACP,QACA,YACoB;AACpB,MAAI,eAAe,QAAW;AAC5B,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAI,WAAW,gBAAgB,SAC3B,CAAC,IACD,EAAE,aAAa,WAAW,YAAY;AAAA,IAC1C,GAAI,WAAW,mBAAmB,SAC9B,CAAC,IACD,EAAE,gBAAgB,WAAW,eAAe;AAAA,IAChD,kBAAkB,WAAW;AAAA,IAC7B,GAAI,WAAW,UAAU,SAAY,CAAC,IAAI,EAAE,OAAO,WAAW,MAAM;AAAA,EACtE;AACF;AAEA,SAAS,SACP,YACmB;AACnB,SAAO;AAAA,IACL,GAAG,IAAI;AAAA,MACL,WAAW;AAAA,QAAQ,CAAC,cAClB,UAAU,WAAW,IAAI,CAAC,WAAW,OAAO,GAAG;AAAA,MACjD;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/wikimatch/index.d.ts

@@ -0,0 +1,16 @@
+export { JudgeWikimatchPolicyOptions, formatCandidateForPrompt, judgeWikimatchPolicy, parsePolicyResponse, validatePolicyResponse } from './policy-judge.js';
+export { NarrowWikimatchCandidateOptionsOptions, narrowWikimatchCandidateOptions, parseNarrowingResponse, validateNarrowingResponse } from './option-narrowing.js';
+export { countWikimatchCandidateOptions, countWikimatchQidOption, filterCandidateQidOptions, listCandidateSelectableQids, sliceCandidateByOptionBudget, splitCandidateByOptionBudget } from './options.js';
+export { applyQidResolutions, enrichWikimatchCandidates } from './enrichment.js';
+export { JudgeWikimatchSurfaceProtectionOptions, judgeWikimatchSurfaceProtection, parseSurfaceProtectionResponse, validateSurfaceProtectionResponse } from './surface-screening.js';
+export { buildWikimatchSurfaceProtectionInput } from './surface-window.js';
+export { suppressContainedRanges } from './range-suppression.js';
+export { DEFAULT_WIKISPINE_FETCH_ENDPOINT, MatchWikispineSentenceCandidatesOptions, TestWikispineRuntimeOptions, WikispineProvider, WikispineRuntimeTestResult, matchWikispineSentenceCandidates, testWikispineRuntime } from './wikispine.js';
+export { buildWikimatchWindows } from './window.js';
+export { expandRangeByWords, listWordBoundaries } from './words.js';
+export { BuildWikimatchSurfaceProtectionInputOptions, BuildWikimatchWindowsOptions, NarrowWikimatchCandidateOptionsInput, WikimatchAcceptedMention, WikimatchCandidate, WikimatchCandidateOptionNarrowingFallback, WikimatchCandidateOptionNarrowingItemOutput, WikimatchCandidateOptionNarrowingResponse, WikimatchCandidateOptionNarrowingResult, WikimatchConflictGroup, WikimatchPolicyContinuation, WikimatchPolicyDecision, WikimatchPolicyDecisionOutput, WikimatchPolicyFallback, WikimatchPolicyJudgeInput, WikimatchPolicyJudgeResult, WikimatchPolicyResponse, WikimatchPolicyUpdate, WikimatchProtectedSurface, WikimatchQidOption, WikimatchSentence, WikimatchSurface, WikimatchSurfaceProtectionBuildResult, WikimatchSurfaceProtectionFallback, WikimatchSurfaceProtectionInput, WikimatchSurfaceProtectionResponse, WikimatchSurfaceProtectionResult, WikimatchTextRange, WikimatchWindow } from './types.js';
+import '../guaranteed/types.js';
+import '../llm/types.js';
+import 'ai';
+import 'zod';
+import '../wikipage/types.js';

package/dist/wikimatch/index.js

@@ -0,0 +1,66 @@
+import {
+  judgeWikimatchPolicy,
+  formatCandidateForPrompt,
+  parsePolicyResponse,
+  validatePolicyResponse
+} from "./policy-judge.js";
+import {
+  narrowWikimatchCandidateOptions,
+  parseNarrowingResponse,
+  validateNarrowingResponse
+} from "./option-narrowing.js";
+import {
+  countWikimatchCandidateOptions,
+  countWikimatchQidOption,
+  filterCandidateQidOptions,
+  listCandidateSelectableQids,
+  sliceCandidateByOptionBudget,
+  splitCandidateByOptionBudget
+} from "./options.js";
+import {
+  applyQidResolutions,
+  enrichWikimatchCandidates
+} from "./enrichment.js";
+import {
+  judgeWikimatchSurfaceProtection,
+  parseSurfaceProtectionResponse,
+  validateSurfaceProtectionResponse
+} from "./surface-screening.js";
+import { buildWikimatchSurfaceProtectionInput } from "./surface-window.js";
+import { suppressContainedRanges } from "./range-suppression.js";
+import {
+  DEFAULT_WIKISPINE_FETCH_ENDPOINT,
+  matchWikispineSentenceCandidates,
+  testWikispineRuntime
+} from "./wikispine.js";
+import { buildWikimatchWindows } from "./window.js";
+import { expandRangeByWords, listWordBoundaries } from "./words.js";
+export {
+  DEFAULT_WIKISPINE_FETCH_ENDPOINT,
+  applyQidResolutions,
+  buildWikimatchSurfaceProtectionInput,
+  buildWikimatchWindows,
+  countWikimatchCandidateOptions,
+  countWikimatchQidOption,
+  enrichWikimatchCandidates,
+  expandRangeByWords,
+  filterCandidateQidOptions,
+  formatCandidateForPrompt,
+  judgeWikimatchPolicy,
+  judgeWikimatchSurfaceProtection,
+  listCandidateSelectableQids,
+  listWordBoundaries,
+  matchWikispineSentenceCandidates,
+  narrowWikimatchCandidateOptions,
+  parseNarrowingResponse,
+  parsePolicyResponse,
+  parseSurfaceProtectionResponse,
+  sliceCandidateByOptionBudget,
+  splitCandidateByOptionBudget,
+  suppressContainedRanges,
+  testWikispineRuntime,
+  validateNarrowingResponse,
+  validatePolicyResponse,
+  validateSurfaceProtectionResponse
+};
+//# sourceMappingURL=index.js.map

package/dist/wikimatch/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wikimatch/index.ts"],"sourcesContent":["export {\n  judgeWikimatchPolicy,\n  formatCandidateForPrompt,\n  parsePolicyResponse,\n  validatePolicyResponse,\n  type JudgeWikimatchPolicyOptions,\n} from \"./policy-judge.js\";\nexport {\n  narrowWikimatchCandidateOptions,\n  parseNarrowingResponse,\n  validateNarrowingResponse,\n  type NarrowWikimatchCandidateOptionsOptions,\n} from \"./option-narrowing.js\";\nexport {\n  countWikimatchCandidateOptions,\n  countWikimatchQidOption,\n  filterCandidateQidOptions,\n  listCandidateSelectableQids,\n  sliceCandidateByOptionBudget,\n  splitCandidateByOptionBudget,\n} from \"./options.js\";\nexport {\n  applyQidResolutions,\n  enrichWikimatchCandidates,\n} from \"./enrichment.js\";\nexport {\n  judgeWikimatchSurfaceProtection,\n  parseSurfaceProtectionResponse,\n  validateSurfaceProtectionResponse,\n  type JudgeWikimatchSurfaceProtectionOptions,\n} from \"./surface-screening.js\";\nexport { buildWikimatchSurfaceProtectionInput } from \"./surface-window.js\";\nexport { suppressContainedRanges } from \"./range-suppression.js\";\nexport {\n  DEFAULT_WIKISPINE_FETCH_ENDPOINT,\n  matchWikispineSentenceCandidates,\n  type MatchWikispineSentenceCandidatesOptions,\n  testWikispineRuntime,\n  type TestWikispineRuntimeOptions,\n  type WikispineProvider,\n  type WikispineRuntimeTestResult,\n} from \"./wikispine.js\";\nexport { buildWikimatchWindows } from \"./window.js\";\nexport { expandRangeByWords, listWordBoundaries } from \"./words.js\";\nexport type {\n  BuildWikimatchWindowsOptions,\n  BuildWikimatchSurfaceProtectionInputOptions,\n  WikimatchAcceptedMention,\n  WikimatchCandidate,\n  WikimatchCandidateOptionNarrowingFallback,\n  WikimatchCandidateOptionNarrowingItemOutput,\n  WikimatchCandidateOptionNarrowingResponse,\n  WikimatchCandidateOptionNarrowingResult,\n  WikimatchConflictGroup,\n  NarrowWikimatchCandidateOptionsInput,\n  WikimatchPolicyDecision,\n  WikimatchPolicyContinuation,\n  WikimatchPolicyDecisionOutput,\n  WikimatchPolicyFallback,\n  WikimatchPolicyJudgeInput,\n  WikimatchPolicyJudgeResult,\n  WikimatchPolicyResponse,\n  WikimatchPolicyUpdate,\n  WikimatchQidOption,\n  WikimatchSentence,\n  WikimatchProtectedSurface,\n  WikimatchSurface,\n  WikimatchSurfaceProtectionBuildResult,\n  WikimatchSurfaceProtectionFallback,\n  WikimatchSurfaceProtectionInput,\n  WikimatchSurfaceProtectionResponse,\n  WikimatchSurfaceProtectionResult,\n  WikimatchTextRange,\n  WikimatchWindow,\n} from \"./types.js\";\n"],"mappings":"AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AACP,SAAS,4CAA4C;AACrD,SAAS,+BAA+B;AACxC;AAAA,EACE;AAAA,EACA;AAAA,EAEA;AAAA,OAIK;AACP,SAAS,6BAA6B;AACtC,SAAS,oBAAoB,0BAA0B;","names":[]}

package/dist/wikimatch/option-narrowing.d.ts

@@ -0,0 +1,17 @@
+import { GuaranteedRequest } from '../guaranteed/types.js';
+import { NarrowWikimatchCandidateOptionsInput, WikimatchCandidateOptionNarrowingResult, WikimatchCandidate, WikimatchCandidateOptionNarrowingResponse } from './types.js';
+import '../llm/types.js';
+import 'ai';
+import 'zod';
+import '../wikipage/types.js';
+
+interface NarrowWikimatchCandidateOptionsOptions extends NarrowWikimatchCandidateOptionsInput {
+    readonly maxRetries?: number;
+    readonly optionBudget: number;
+    readonly request: GuaranteedRequest;
+}
+declare function narrowWikimatchCandidateOptions(options: NarrowWikimatchCandidateOptionsOptions): Promise<WikimatchCandidateOptionNarrowingResult>;
+declare function parseNarrowingResponse(candidate: WikimatchCandidate, response: WikimatchCandidateOptionNarrowingResponse): WikimatchCandidateOptionNarrowingResult;
+declare function validateNarrowingResponse(candidate: WikimatchCandidate, response: WikimatchCandidateOptionNarrowingResponse): readonly string[];
+
+export { type NarrowWikimatchCandidateOptionsOptions, narrowWikimatchCandidateOptions, parseNarrowingResponse, validateNarrowingResponse };

package/dist/wikimatch/option-narrowing.js

@@ -0,0 +1,208 @@
+import { z } from "zod";
+import {
+  ParsedJsonError,
+  RESPONSE_INTENT_CLASSIFIER_PROMPT_TEMPLATE,
+  requestGuaranteedJson
+} from "../guaranteed/index.js";
+import {
+  filterCandidateQidOptions,
+  listCandidateSelectableQids,
+  splitCandidateByOptionBudget
+} from "./options.js";
+import { formatCandidateForPrompt } from "./policy-judge.js";
+const narrowingItemSchema = z.object({
+  decision: z.enum(["keep", "reject"]),
+  qid: z.string().regex(/^Q[1-9][0-9]*$/)
+}).strict();
+const narrowingResponseSchema = z.object({
+  qids: z.array(narrowingItemSchema)
+}).strict();
+async function narrowWikimatchCandidateOptions(options) {
+  const keptQids = /* @__PURE__ */ new Set();
+  const issues = [];
+  for (const chunk of splitCandidateByOptionBudget(
+    options.candidate,
+    options.optionBudget
+  )) {
+    const result = await requestNarrowedChunk({
+      ...options,
+      candidate: chunk
+    });
+    if (result.fallback !== void 0) {
+      issues.push(...result.fallback.issues);
+      continue;
+    }
+    for (const qid of listCandidateSelectableQids(result.candidate)) {
+      keptQids.add(qid);
+    }
+  }
+  if (issues.length > 0) {
+    return {
+      candidate: {
+        ...options.candidate,
+        qidOptions: []
+      },
+      fallback: {
+        issues,
+        reason: "guaranteed_json_failed"
+      }
+    };
+  }
+  return {
+    candidate: filterCandidateQidOptions(options.candidate, keptQids)
+  };
+}
+async function requestNarrowedChunk(options) {
+  try {
+    return await requestGuaranteedJson({
+      messages: buildNarrowingMessages(options),
+      parse: (response) => parseNarrowingResponse(
+        options.candidate,
+        normalizeNarrowingResponse(response)
+      ),
+      request: options.request,
+      responseIntentClassifierPrompt: RESPONSE_INTENT_CLASSIFIER_PROMPT_TEMPLATE,
+      schema: narrowingResponseSchema,
+      ...options.maxRetries === void 0 ? {} : { maxRetries: options.maxRetries }
+    });
+  } catch (error) {
+    return {
+      candidate: {
+        ...options.candidate,
+        qidOptions: []
+      },
+      fallback: {
+        issues: [formatFallbackIssue(error)],
+        reason: "guaranteed_json_failed"
+      }
+    };
+  }
+}
+function normalizeNarrowingResponse(response) {
+  return {
+    qids: response.qids.map((item) => ({
+      decision: item.decision,
+      qid: item.qid
+    }))
+  };
+}
+function parseNarrowingResponse(candidate, response) {
+  const issues = validateNarrowingResponse(candidate, response);
+  if (issues.length > 0) {
+    throw new ParsedJsonError(issues);
+  }
+  return {
+    candidate: filterCandidateQidOptions(
+      candidate,
+      new Set(
+        response.qids.filter((item) => item.decision === "keep").map((item) => item.qid)
+      )
+    )
+  };
+}
+function validateNarrowingResponse(candidate, response) {
+  const issues = [];
+  const allowedQids = new Set(listCandidateSelectableQids(candidate));
+  const seenQids = /* @__PURE__ */ new Set();
+  for (const item of response.qids) {
+    if (!allowedQids.has(item.qid)) {
+      issues.push(
+        `Unknown qid "${item.qid}" for candidate ${candidate.id}. Use exactly these QIDs: ${[
+          ...allowedQids
+        ].join(", ")}.`
+      );
+      continue;
+    }
+    if (seenQids.has(item.qid)) {
+      issues.push(`Duplicate narrowing result for qid ${item.qid}.`);
+      continue;
+    }
+    seenQids.add(item.qid);
+  }
+  for (const qid of allowedQids) {
+    if (!seenQids.has(qid)) {
+      issues.push(
+        `Missing narrowing result for qid ${qid}. Return exactly one keep/reject decision for every input QID.`
+      );
+    }
+  }
+  return issues;
+}
+function buildNarrowingMessages(input) {
+  return [
+    {
+      role: "system",
+      content: formatNarrowingSystemPrompt(input)
+    },
+    {
+      role: "user",
+      content: formatNarrowingPrompt(input)
+    }
+  ];
+}
+function formatNarrowingSystemPrompt(input) {
+  return [
+    "You narrow an oversized Wikidata candidate option list before final mention grounding.",
+    "",
+    "Recall policy:",
+    input.policyPrompt,
+    "",
+    "Rules:",
+    "- Return JSON only.",
+    "- Return exactly one keep/reject decision for every input QID.",
+    "- Keep any QID that could plausibly ground this surface in the current context.",
+    "- Reject QIDs that are clearly unrelated to the surface and context.",
+    "- Be conservative when uncertain; keep plausible meanings so the final grounding request can decide.",
+    "- Do not invent QIDs."
+  ].join("\n");
+}
+function formatNarrowingPrompt(input) {
+  return [
+    "Context:",
+    input.text,
+    "",
+    "Oversized candidate:",
+    JSON.stringify(
+      formatCandidateForPrompt(input.candidate, {
+        candidateIds: [input.candidate.id],
+        id: "g1",
+        range: input.candidate.range
+      }),
+      null,
+      2
+    ),
+    "",
+    "Return this JSON shape:",
+    JSON.stringify(
+      {
+        qids: [
+          {
+            decision: "keep | reject",
+            qid: "QID from the input"
+          }
+        ]
+      },
+      null,
+      2
+    )
+  ].join("\n");
+}
+function formatFallbackIssue(error) {
+  if (error instanceof ParsedJsonError) {
+    return error.issues.join("\n");
+  }
+  if (error instanceof Error) {
+    const issues = error.issues;
+    if (Array.isArray(issues) && issues.every((issue) => typeof issue === "string")) {
+      return issues.join("\n");
+    }
+    return error.message;
+  }
+  return String(error);
+}
+export {
+  narrowWikimatchCandidateOptions,
+  parseNarrowingResponse,
+  validateNarrowingResponse
+};
+//# sourceMappingURL=option-narrowing.js.map

package/dist/wikimatch/option-narrowing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wikimatch/option-narrowing.ts"],"sourcesContent":["import { z } from \"zod\";\n\nimport {\n  ParsedJsonError,\n  RESPONSE_INTENT_CLASSIFIER_PROMPT_TEMPLATE,\n  requestGuaranteedJson,\n  type GuaranteedRequest,\n} from \"../guaranteed/index.js\";\nimport type { LLMessage } from \"../llm/index.js\";\n\nimport {\n  filterCandidateQidOptions,\n  listCandidateSelectableQids,\n  splitCandidateByOptionBudget,\n} from \"./options.js\";\nimport { formatCandidateForPrompt } from \"./policy-judge.js\";\nimport type {\n  NarrowWikimatchCandidateOptionsInput,\n  WikimatchCandidate,\n  WikimatchCandidateOptionNarrowingResponse,\n  WikimatchCandidateOptionNarrowingResult,\n} from \"./types.js\";\n\nconst narrowingItemSchema = z\n  .object({\n    decision: z.enum([\"keep\", \"reject\"]),\n    qid: z.string().regex(/^Q[1-9][0-9]*$/),\n  })\n  .strict();\n\nconst narrowingResponseSchema = z\n  .object({\n    qids: z.array(narrowingItemSchema),\n  })\n  .strict();\n\nexport interface NarrowWikimatchCandidateOptionsOptions extends NarrowWikimatchCandidateOptionsInput {\n  readonly maxRetries?: number;\n  readonly optionBudget: number;\n  readonly request: GuaranteedRequest;\n}\n\nexport async function narrowWikimatchCandidateOptions(\n  options: NarrowWikimatchCandidateOptionsOptions,\n): Promise<WikimatchCandidateOptionNarrowingResult> {\n  const keptQids = new Set<string>();\n  const issues: string[] = [];\n\n  for (const chunk of splitCandidateByOptionBudget(\n    options.candidate,\n    options.optionBudget,\n  )) {\n    const result = await requestNarrowedChunk({\n      ...options,\n      candidate: chunk,\n    });\n\n    if (result.fallback !== undefined) {\n      issues.push(...result.fallback.issues);\n      continue;\n    }\n\n    for (const qid of listCandidateSelectableQids(result.candidate)) {\n      keptQids.add(qid);\n    }\n  }\n\n  if (issues.length > 0) {\n    return {\n      candidate: {\n        ...options.candidate,\n        qidOptions: [],\n      },\n      fallback: {\n        issues,\n        reason: \"guaranteed_json_failed\",\n      },\n    };\n  }\n\n  return {\n    candidate: filterCandidateQidOptions(options.candidate, keptQids),\n  };\n}\n\nasync function requestNarrowedChunk(\n  options: NarrowWikimatchCandidateOptionsOptions,\n): Promise<WikimatchCandidateOptionNarrowingResult> {\n  try {\n    return await requestGuaranteedJson({\n      messages: buildNarrowingMessages(options),\n      parse: (response) =>\n        parseNarrowingResponse(\n          options.candidate,\n          normalizeNarrowingResponse(response),\n        ),\n      request: options.request,\n      responseIntentClassifierPrompt:\n        RESPONSE_INTENT_CLASSIFIER_PROMPT_TEMPLATE,\n      schema: narrowingResponseSchema,\n      ...(options.maxRetries === undefined\n        ? {}\n        : { maxRetries: options.maxRetries }),\n    });\n  } catch (error) {\n    return {\n      candidate: {\n        ...options.candidate,\n        qidOptions: [],\n      },\n      fallback: {\n        issues: [formatFallbackIssue(error)],\n        reason: \"guaranteed_json_failed\",\n      },\n    };\n  }\n}\n\nfunction normalizeNarrowingResponse(\n  response: z.infer<typeof narrowingResponseSchema>,\n): WikimatchCandidateOptionNarrowingResponse {\n  return {\n    qids: response.qids.map((item) => ({\n      decision: item.decision,\n      qid: item.qid,\n    })),\n  };\n}\n\nexport function parseNarrowingResponse(\n  candidate: WikimatchCandidate,\n  response: WikimatchCandidateOptionNarrowingResponse,\n): WikimatchCandidateOptionNarrowingResult {\n  const issues = validateNarrowingResponse(candidate, response);\n\n  if (issues.length > 0) {\n    throw new ParsedJsonError(issues);\n  }\n\n  return {\n    candidate: filterCandidateQidOptions(\n      candidate,\n      new Set(\n        response.qids\n          .filter((item) => item.decision === \"keep\")\n          .map((item) => item.qid),\n      ),\n    ),\n  };\n}\n\nexport function validateNarrowingResponse(\n  candidate: WikimatchCandidate,\n  response: WikimatchCandidateOptionNarrowingResponse,\n): readonly string[] {\n  const issues: string[] = [];\n  const allowedQids = new Set(listCandidateSelectableQids(candidate));\n  const seenQids = new Set<string>();\n\n  for (const item of response.qids) {\n    if (!allowedQids.has(item.qid)) {\n      issues.push(\n        `Unknown qid \"${item.qid}\" for candidate ${candidate.id}. Use exactly these QIDs: ${[\n          ...allowedQids,\n        ].join(\", \")}.`,\n      );\n      continue;\n    }\n    if (seenQids.has(item.qid)) {\n      issues.push(`Duplicate narrowing result for qid ${item.qid}.`);\n      continue;\n    }\n\n    seenQids.add(item.qid);\n  }\n\n  for (const qid of allowedQids) {\n    if (!seenQids.has(qid)) {\n      issues.push(\n        `Missing narrowing result for qid ${qid}. Return exactly one keep/reject decision for every input QID.`,\n      );\n    }\n  }\n\n  return issues;\n}\n\nfunction buildNarrowingMessages(\n  input: NarrowWikimatchCandidateOptionsInput,\n): LLMessage[] {\n  return [\n    {\n      role: \"system\",\n      content: formatNarrowingSystemPrompt(input),\n    },\n    {\n      role: \"user\",\n      content: formatNarrowingPrompt(input),\n    },\n  ];\n}\n\nfunction formatNarrowingSystemPrompt(\n  input: NarrowWikimatchCandidateOptionsInput,\n): string {\n  return [\n    \"You narrow an oversized Wikidata candidate option list before final mention grounding.\",\n    \"\",\n    \"Recall policy:\",\n    input.policyPrompt,\n    \"\",\n    \"Rules:\",\n    \"- Return JSON only.\",\n    \"- Return exactly one keep/reject decision for every input QID.\",\n    \"- Keep any QID that could plausibly ground this surface in the current context.\",\n    \"- Reject QIDs that are clearly unrelated to the surface and context.\",\n    \"- Be conservative when uncertain; keep plausible meanings so the final grounding request can decide.\",\n    \"- Do not invent QIDs.\",\n  ].join(\"\\n\");\n}\n\nfunction formatNarrowingPrompt(\n  input: NarrowWikimatchCandidateOptionsInput,\n): string {\n  return [\n    \"Context:\",\n    input.text,\n    \"\",\n    \"Oversized candidate:\",\n    JSON.stringify(\n      formatCandidateForPrompt(input.candidate, {\n        candidateIds: [input.candidate.id],\n        id: \"g1\",\n        range: input.candidate.range,\n      }),\n      null,\n      2,\n    ),\n    \"\",\n    \"Return this JSON shape:\",\n    JSON.stringify(\n      {\n        qids: [\n          {\n            decision: \"keep | reject\",\n            qid: \"QID from the input\",\n          },\n        ],\n      },\n      null,\n      2,\n    ),\n  ].join(\"\\n\");\n}\n\nfunction formatFallbackIssue(error: unknown): string {\n  if (error instanceof ParsedJsonError) {\n    return error.issues.join(\"\\n\");\n  }\n  if (error instanceof Error) {\n    const issues = (error as { readonly issues?: unknown }).issues;\n\n    if (\n      Array.isArray(issues) &&\n      issues.every((issue) => typeof issue === \"string\")\n    ) {\n      return issues.join(\"\\n\");\n    }\n\n    return error.message;\n  }\n\n  return String(error);\n}\n"],"mappings":"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","names":[]}

package/dist/wikimatch/options.d.ts

@@ -0,0 +1,14 @@
+import { WikimatchCandidate, WikimatchQidOption } from './types.js';
+import '../wikipage/types.js';
+
+declare function countWikimatchCandidateOptions(candidate: WikimatchCandidate): number;
+declare function countWikimatchQidOption(option: WikimatchQidOption): number;
+declare function listCandidateSelectableQids(candidate: WikimatchCandidate): readonly string[];
+declare function filterCandidateQidOptions(candidate: WikimatchCandidate, allowedQids: ReadonlySet<string>): WikimatchCandidate;
+declare function splitCandidateByOptionBudget(candidate: WikimatchCandidate, optionBudget: number): readonly WikimatchCandidate[];
+declare function sliceCandidateByOptionBudget(candidate: WikimatchCandidate, optionBudget: number, offset: number): {
+    readonly candidate: WikimatchCandidate;
+    readonly nextOffset?: number;
+};
+
+export { countWikimatchCandidateOptions, countWikimatchQidOption, filterCandidateQidOptions, listCandidateSelectableQids, sliceCandidateByOptionBudget, splitCandidateByOptionBudget };

package/dist/wikimatch/options.js

@@ -0,0 +1,155 @@
+function countWikimatchCandidateOptions(candidate) {
+  return candidate.qidOptions.reduce(
+    (total, option) => total + countWikimatchQidOption(option),
+    0
+  );
+}
+function countWikimatchQidOption(option) {
+  if (option.disambiguation === void 0) {
+    return 1;
+  }
+  return listSelectableQids(option).length;
+}
+function listCandidateSelectableQids(candidate) {
+  return [
+    ...new Set(
+      candidate.qidOptions.flatMap((option) => listSelectableQids(option))
+    )
+  ];
+}
+function filterCandidateQidOptions(candidate, allowedQids) {
+  return {
+    ...candidate,
+    qidOptions: candidate.qidOptions.flatMap((option) => {
+      const filtered = filterQidOption(option, allowedQids);
+      return filtered === void 0 ? [] : [filtered];
+    })
+  };
+}
+function splitCandidateByOptionBudget(candidate, optionBudget) {
+  if (!Number.isFinite(optionBudget) || optionBudget <= 0) {
+    throw new Error("Wikimatch option budget must be positive.");
+  }
+  const chunks = [];
+  let pendingOptions = [];
+  let pendingCost = 0;
+  for (const option of candidate.qidOptions) {
+    const optionChunks = splitQidOptionByBudget(option, optionBudget);
+    for (const optionChunk of optionChunks) {
+      const cost = countWikimatchQidOption(optionChunk);
+      if (pendingOptions.length > 0 && pendingCost + cost > optionBudget) {
+        chunks.push({
+          ...candidate,
+          qidOptions: pendingOptions
+        });
+        pendingOptions = [];
+        pendingCost = 0;
+      }
+      pendingOptions.push(optionChunk);
+      pendingCost += cost;
+    }
+  }
+  if (pendingOptions.length > 0) {
+    chunks.push({
+      ...candidate,
+      qidOptions: pendingOptions
+    });
+  }
+  return chunks;
+}
+function sliceCandidateByOptionBudget(candidate, optionBudget, offset) {
+  if (!Number.isFinite(optionBudget) || optionBudget <= 0) {
+    throw new Error("Wikimatch option budget must be positive.");
+  }
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new Error("Wikimatch option offset must be a non-negative integer.");
+  }
+  const selectedQids = listCandidateSelectableQids(candidate).slice(
+    offset,
+    offset + optionBudget
+  );
+  const filtered = filterCandidateQidOptions(candidate, new Set(selectedQids));
+  const nextOffset = offset + selectedQids.length < listCandidateSelectableQids(candidate).length ? offset + selectedQids.length : void 0;
+  return {
+    candidate: {
+      ...filtered,
+      ...nextOffset === void 0 ? {} : { hasMoreOptions: true }
+    },
+    ...nextOffset === void 0 ? {} : { nextOffset }
+  };
+}
+function splitQidOptionByBudget(option, optionBudget) {
+  if (option.disambiguation === void 0) {
+    return [option];
+  }
+  const selectableQids = listSelectableQids(option);
+  if (selectableQids.length <= optionBudget) {
+    return [option];
+  }
+  const chunks = [];
+  for (let index = 0; index < selectableQids.length; index += optionBudget) {
+    const qids = new Set(selectableQids.slice(index, index + optionBudget));
+    const filtered = filterQidOption(option, qids);
+    if (filtered !== void 0) {
+      chunks.push(filtered);
+    }
+  }
+  return chunks;
+}
+function filterQidOption(option, allowedQids) {
+  if (option.disambiguation === void 0) {
+    return allowedQids.has(option.qid) ? option : void 0;
+  }
+  const linkedQids = option.disambiguation.linkedQids.filter(
+    (item) => allowedQids.has(item.qid)
+  );
+  const profile = filterDisambiguationProfile(
+    option.disambiguation.profile,
+    allowedQids
+  );
+  const hasProfileMeanings = (profile?.meanings.length ?? 0) > 0;
+  if (linkedQids.length === 0 && !hasProfileMeanings) {
+    return void 0;
+  }
+  return {
+    ...option,
+    disambiguation: {
+      ...option.disambiguation,
+      linkedQids,
+      ...profile === void 0 ? {} : { profile }
+    }
+  };
+}
+function filterDisambiguationProfile(profile, allowedQids) {
+  if (profile === void 0) {
+    return void 0;
+  }
+  return {
+    ...profile,
+    meanings: profile.meanings.filter(
+      (meaning) => allowedQids.has(meaning.qid)
+    )
+  };
+}
+function listSelectableQids(option) {
+  if (option.disambiguation === void 0) {
+    return [option.qid];
+  }
+  return [
+    .../* @__PURE__ */ new Set([
+      ...option.disambiguation.profile?.meanings.map(
+        (meaning) => meaning.qid
+      ) ?? [],
+      ...option.disambiguation.linkedQids.map((item) => item.qid)
+    ])
+  ];
+}
+export {
+  countWikimatchCandidateOptions,
+  countWikimatchQidOption,
+  filterCandidateQidOptions,
+  listCandidateSelectableQids,
+  sliceCandidateByOptionBudget,
+  splitCandidateByOptionBudget
+};
+//# sourceMappingURL=options.js.map

package/dist/wikimatch/options.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wikimatch/options.ts"],"sourcesContent":["import type { DisambiguationProfile } from \"../wikipage/index.js\";\n\nimport type { WikimatchCandidate, WikimatchQidOption } from \"./types.js\";\n\nexport function countWikimatchCandidateOptions(\n  candidate: WikimatchCandidate,\n): number {\n  return candidate.qidOptions.reduce(\n    (total, option) => total + countWikimatchQidOption(option),\n    0,\n  );\n}\n\nexport function countWikimatchQidOption(option: WikimatchQidOption): number {\n  if (option.disambiguation === undefined) {\n    return 1;\n  }\n\n  return listSelectableQids(option).length;\n}\n\nexport function listCandidateSelectableQids(\n  candidate: WikimatchCandidate,\n): readonly string[] {\n  return [\n    ...new Set(\n      candidate.qidOptions.flatMap((option) => listSelectableQids(option)),\n    ),\n  ];\n}\n\nexport function filterCandidateQidOptions(\n  candidate: WikimatchCandidate,\n  allowedQids: ReadonlySet<string>,\n): WikimatchCandidate {\n  return {\n    ...candidate,\n    qidOptions: candidate.qidOptions.flatMap((option) => {\n      const filtered = filterQidOption(option, allowedQids);\n\n      return filtered === undefined ? [] : [filtered];\n    }),\n  };\n}\n\nexport function splitCandidateByOptionBudget(\n  candidate: WikimatchCandidate,\n  optionBudget: number,\n): readonly WikimatchCandidate[] {\n  if (!Number.isFinite(optionBudget) || optionBudget <= 0) {\n    throw new Error(\"Wikimatch option budget must be positive.\");\n  }\n\n  const chunks: WikimatchCandidate[] = [];\n  let pendingOptions: WikimatchQidOption[] = [];\n  let pendingCost = 0;\n\n  for (const option of candidate.qidOptions) {\n    const optionChunks = splitQidOptionByBudget(option, optionBudget);\n\n    for (const optionChunk of optionChunks) {\n      const cost = countWikimatchQidOption(optionChunk);\n\n      if (pendingOptions.length > 0 && pendingCost + cost > optionBudget) {\n        chunks.push({\n          ...candidate,\n          qidOptions: pendingOptions,\n        });\n        pendingOptions = [];\n        pendingCost = 0;\n      }\n\n      pendingOptions.push(optionChunk);\n      pendingCost += cost;\n    }\n  }\n\n  if (pendingOptions.length > 0) {\n    chunks.push({\n      ...candidate,\n      qidOptions: pendingOptions,\n    });\n  }\n\n  return chunks;\n}\n\nexport function sliceCandidateByOptionBudget(\n  candidate: WikimatchCandidate,\n  optionBudget: number,\n  offset: number,\n): {\n  readonly candidate: WikimatchCandidate;\n  readonly nextOffset?: number;\n} {\n  if (!Number.isFinite(optionBudget) || optionBudget <= 0) {\n    throw new Error(\"Wikimatch option budget must be positive.\");\n  }\n  if (!Number.isInteger(offset) || offset < 0) {\n    throw new Error(\"Wikimatch option offset must be a non-negative integer.\");\n  }\n\n  const selectedQids = listCandidateSelectableQids(candidate).slice(\n    offset,\n    offset + optionBudget,\n  );\n  const filtered = filterCandidateQidOptions(candidate, new Set(selectedQids));\n  const nextOffset =\n    offset + selectedQids.length < listCandidateSelectableQids(candidate).length\n      ? offset + selectedQids.length\n      : undefined;\n\n  return {\n    candidate: {\n      ...filtered,\n      ...(nextOffset === undefined ? {} : { hasMoreOptions: true }),\n    },\n    ...(nextOffset === undefined ? {} : { nextOffset }),\n  };\n}\n\nfunction splitQidOptionByBudget(\n  option: WikimatchQidOption,\n  optionBudget: number,\n): readonly WikimatchQidOption[] {\n  if (option.disambiguation === undefined) {\n    return [option];\n  }\n\n  const selectableQids = listSelectableQids(option);\n\n  if (selectableQids.length <= optionBudget) {\n    return [option];\n  }\n\n  const chunks: WikimatchQidOption[] = [];\n\n  for (let index = 0; index < selectableQids.length; index += optionBudget) {\n    const qids = new Set(selectableQids.slice(index, index + optionBudget));\n    const filtered = filterQidOption(option, qids);\n\n    if (filtered !== undefined) {\n      chunks.push(filtered);\n    }\n  }\n\n  return chunks;\n}\n\nfunction filterQidOption(\n  option: WikimatchQidOption,\n  allowedQids: ReadonlySet<string>,\n): WikimatchQidOption | undefined {\n  if (option.disambiguation === undefined) {\n    return allowedQids.has(option.qid) ? option : undefined;\n  }\n\n  const linkedQids = option.disambiguation.linkedQids.filter((item) =>\n    allowedQids.has(item.qid),\n  );\n  const profile = filterDisambiguationProfile(\n    option.disambiguation.profile,\n    allowedQids,\n  );\n  const hasProfileMeanings = (profile?.meanings.length ?? 0) > 0;\n\n  if (linkedQids.length === 0 && !hasProfileMeanings) {\n    return undefined;\n  }\n\n  return {\n    ...option,\n    disambiguation: {\n      ...option.disambiguation,\n      linkedQids,\n      ...(profile === undefined ? {} : { profile }),\n    },\n  };\n}\n\nfunction filterDisambiguationProfile(\n  profile: DisambiguationProfile | undefined,\n  allowedQids: ReadonlySet<string>,\n): DisambiguationProfile | undefined {\n  if (profile === undefined) {\n    return undefined;\n  }\n\n  return {\n    ...profile,\n    meanings: profile.meanings.filter((meaning) =>\n      allowedQids.has(meaning.qid),\n    ),\n  };\n}\n\nfunction listSelectableQids(option: WikimatchQidOption): readonly string[] {\n  if (option.disambiguation === undefined) {\n    return [option.qid];\n  }\n\n  return [\n    ...new Set([\n      ...(option.disambiguation.profile?.meanings.map(\n        (meaning) => meaning.qid,\n      ) ?? []),\n      ...option.disambiguation.linkedQids.map((item) => item.qid),\n    ]),\n  ];\n}\n"],"mappings":"AAIO,SAAS,+BACd,WACQ;AACR,SAAO,UAAU,WAAW;AAAA,IAC1B,CAAC,OAAO,WAAW,QAAQ,wBAAwB,MAAM;AAAA,IACzD;AAAA,EACF;AACF;AAEO,SAAS,wBAAwB,QAAoC;AAC1E,MAAI,OAAO,mBAAmB,QAAW;AACvC,WAAO;AAAA,EACT;AAEA,SAAO,mBAAmB,MAAM,EAAE;AACpC;AAEO,SAAS,4BACd,WACmB;AACnB,SAAO;AAAA,IACL,GAAG,IAAI;AAAA,MACL,UAAU,WAAW,QAAQ,CAAC,WAAW,mBAAmB,MAAM,CAAC;AAAA,IACrE;AAAA,EACF;AACF;AAEO,SAAS,0BACd,WACA,aACoB;AACpB,SAAO;AAAA,IACL,GAAG;AAAA,IACH,YAAY,UAAU,WAAW,QAAQ,CAAC,WAAW;AACnD,YAAM,WAAW,gBAAgB,QAAQ,WAAW;AAEpD,aAAO,aAAa,SAAY,CAAC,IAAI,CAAC,QAAQ;AAAA,IAChD,CAAC;AAAA,EACH;AACF;AAEO,SAAS,6BACd,WACA,cAC+B;AAC/B,MAAI,CAAC,OAAO,SAAS,YAAY,KAAK,gBAAgB,GAAG;AACvD,UAAM,IAAI,MAAM,2CAA2C;AAAA,EAC7D;AAEA,QAAM,SAA+B,CAAC;AACtC,MAAI,iBAAuC,CAAC;AAC5C,MAAI,cAAc;AAElB,aAAW,UAAU,UAAU,YAAY;AACzC,UAAM,eAAe,uBAAuB,QAAQ,YAAY;AAEhE,eAAW,eAAe,cAAc;AACtC,YAAM,OAAO,wBAAwB,WAAW;AAEhD,UAAI,eAAe,SAAS,KAAK,cAAc,OAAO,cAAc;AAClE,eAAO,KAAK;AAAA,UACV,GAAG;AAAA,UACH,YAAY;AAAA,QACd,CAAC;AACD,yBAAiB,CAAC;AAClB,sBAAc;AAAA,MAChB;AAEA,qBAAe,KAAK,WAAW;AAC/B,qBAAe;AAAA,IACjB;AAAA,EACF;AAEA,MAAI,eAAe,SAAS,GAAG;AAC7B,WAAO,KAAK;AAAA,MACV,GAAG;AAAA,MACH,YAAY;AAAA,IACd,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAEO,SAAS,6BACd,WACA,cACA,QAIA;AACA,MAAI,CAAC,OAAO,SAAS,YAAY,KAAK,gBAAgB,GAAG;AACvD,UAAM,IAAI,MAAM,2CAA2C;AAAA,EAC7D;AACA,MAAI,CAAC,OAAO,UAAU,MAAM,KAAK,SAAS,GAAG;AAC3C,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AAEA,QAAM,eAAe,4BAA4B,SAAS,EAAE;AAAA,IAC1D;AAAA,IACA,SAAS;AAAA,EACX;AACA,QAAM,WAAW,0BAA0B,WAAW,IAAI,IAAI,YAAY,CAAC;AAC3E,QAAM,aACJ,SAAS,aAAa,SAAS,4BAA4B,SAAS,EAAE,SAClE,SAAS,aAAa,SACtB;AAEN,SAAO;AAAA,IACL,WAAW;AAAA,MACT,GAAG;AAAA,MACH,GAAI,eAAe,SAAY,CAAC,IAAI,EAAE,gBAAgB,KAAK;AAAA,IAC7D;AAAA,IACA,GAAI,eAAe,SAAY,CAAC,IAAI,EAAE,WAAW;AAAA,EACnD;AACF;AAEA,SAAS,uBACP,QACA,cAC+B;AAC/B,MAAI,OAAO,mBAAmB,QAAW;AACvC,WAAO,CAAC,MAAM;AAAA,EAChB;AAEA,QAAM,iBAAiB,mBAAmB,MAAM;AAEhD,MAAI,eAAe,UAAU,cAAc;AACzC,WAAO,CAAC,MAAM;AAAA,EAChB;AAEA,QAAM,SAA+B,CAAC;AAEtC,WAAS,QAAQ,GAAG,QAAQ,eAAe,QAAQ,SAAS,cAAc;AACxE,UAAM,OAAO,IAAI,IAAI,eAAe,MAAM,OAAO,QAAQ,YAAY,CAAC;AACtE,UAAM,WAAW,gBAAgB,QAAQ,IAAI;AAE7C,QAAI,aAAa,QAAW;AAC1B,aAAO,KAAK,QAAQ;AAAA,IACtB;AAAA,EACF;AAEA,SAAO;AACT;AAEA,SAAS,gBACP,QACA,aACgC;AAChC,MAAI,OAAO,mBAAmB,QAAW;AACvC,WAAO,YAAY,IAAI,OAAO,GAAG,IAAI,SAAS;AAAA,EAChD;AAEA,QAAM,aAAa,OAAO,eAAe,WAAW;AAAA,IAAO,CAAC,SAC1D,YAAY,IAAI,KAAK,GAAG;AAAA,EAC1B;AACA,QAAM,UAAU;AAAA,IACd,OAAO,eAAe;AAAA,IACtB;AAAA,EACF;AACA,QAAM,sBAAsB,SAAS,SAAS,UAAU,KAAK;AAE7D,MAAI,WAAW,WAAW,KAAK,CAAC,oBAAoB;AAClD,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,gBAAgB;AAAA,MACd,GAAG,OAAO;AAAA,MACV;AAAA,MACA,GAAI,YAAY,SAAY,CAAC,IAAI,EAAE,QAAQ;AAAA,IAC7C;AAAA,EACF;AACF;AAEA,SAAS,4BACP,SACA,aACmC;AACnC,MAAI,YAAY,QAAW;AACzB,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,UAAU,QAAQ,SAAS;AAAA,MAAO,CAAC,YACjC,YAAY,IAAI,QAAQ,GAAG;AAAA,IAC7B;AAAA,EACF;AACF;AAEA,SAAS,mBAAmB,QAA+C;AACzE,MAAI,OAAO,mBAAmB,QAAW;AACvC,WAAO,CAAC,OAAO,GAAG;AAAA,EACpB;AAEA,SAAO;AAAA,IACL,GAAG,oBAAI,IAAI;AAAA,MACT,GAAI,OAAO,eAAe,SAAS,SAAS;AAAA,QAC1C,CAAC,YAAY,QAAQ;AAAA,MACvB,KAAK,CAAC;AAAA,MACN,GAAG,OAAO,eAAe,WAAW,IAAI,CAAC,SAAS,KAAK,GAAG;AAAA,IAC5D,CAAC;AAAA,EACH;AACF;","names":[]}

package/dist/wikimatch/policy-judge.d.ts

@@ -0,0 +1,17 @@
+import { GuaranteedRequest } from '../guaranteed/types.js';
+import { WikimatchPolicyJudgeInput, WikimatchCandidate, WikimatchConflictGroup, WikimatchPolicyJudgeResult, WikimatchPolicyResponse } from './types.js';
+import '../llm/types.js';
+import 'ai';
+import 'zod';
+import '../wikipage/types.js';
+
+interface JudgeWikimatchPolicyOptions extends WikimatchPolicyJudgeInput {
+    readonly maxRetries?: number;
+    readonly request: GuaranteedRequest;
+}
+declare function judgeWikimatchPolicy(options: JudgeWikimatchPolicyOptions): Promise<WikimatchPolicyJudgeResult>;
+declare function parsePolicyResponse(candidates: readonly WikimatchCandidate[], response: WikimatchPolicyResponse, groups?: readonly WikimatchConflictGroup[]): WikimatchPolicyJudgeResult;
+declare function validatePolicyResponse(candidates: readonly WikimatchCandidate[], response: WikimatchPolicyResponse, groups?: readonly WikimatchConflictGroup[]): readonly string[];
+declare function formatCandidateForPrompt(candidate: WikimatchCandidate, _group?: WikimatchConflictGroup): object;
+
+export { type JudgeWikimatchPolicyOptions, formatCandidateForPrompt, judgeWikimatchPolicy, parsePolicyResponse, validatePolicyResponse };