wiki-graph-core 0.3.1

package/dist/wikilink/relation-discovery.js

@@ -0,0 +1,477 @@
+import { z } from "zod";
+import {
+  ParsedJsonError,
+  RESPONSE_INTENT_CLASSIFIER_PROMPT_TEMPLATE,
+  requestGuaranteedJson
+} from "../guaranteed/index.js";
+import {
+  EVIDENCE_SELECTION_JSON_SHAPE,
+  EVIDENCE_SELECTION_PROMPT_FRAGMENT,
+  EvidenceResolver,
+  normalizeEvidenceDisplayText,
+  resolveEvidenceSelectionList
+} from "../evidence-selection/index.js";
+import { FragmentProjection } from "../reader/chunk-batch/index.js";
+const evidenceAnchorSchema = z.object({
+  head: z.string().optional(),
+  mode: z.enum(["full", "head_tail"]).optional(),
+  tail: z.string().optional(),
+  text: z.string().optional()
+}).strict();
+const evidenceSelectionItemSchema = z.object({
+  quote: z.string().optional(),
+  sentence_id: z.string().optional()
+}).strict();
+const relationEvidenceSchema = z.union([
+  z.object({
+    end_anchor: z.union([z.string(), evidenceAnchorSchema]).optional(),
+    quote: z.string().optional(),
+    sentence_id: z.string().optional(),
+    start_anchor: z.union([z.string(), evidenceAnchorSchema]).optional()
+  }).strict(),
+  z.array(evidenceSelectionItemSchema)
+]);
+const relationSchema = z.object({
+  confidence: z.number().min(0).max(1).optional(),
+  evidence: relationEvidenceSchema,
+  predicate: z.string().min(1).max(64),
+  sourceMentionId: z.string().min(1),
+  targetMentionId: z.string().min(1)
+}).strict();
+const relationResponseSchema = z.object({
+  relations: z.array(relationSchema)
+}).strict();
+const SUGGESTED_PREDICATES = [
+  "instance_of",
+  "subclass_of",
+  "part_of",
+  "has_part",
+  "located_in",
+  "contains",
+  "member_of",
+  "owned_by",
+  "creator",
+  "author",
+  "developer",
+  "founded_by",
+  "leader",
+  "position_held",
+  "employer",
+  "educated_at",
+  "student_of",
+  "parent",
+  "child",
+  "spouse",
+  "sibling",
+  "relative",
+  "replaces",
+  "replaced_by",
+  "precedes",
+  "follows",
+  "influenced_by",
+  "influences",
+  "participant_in",
+  "participant",
+  "conflict",
+  "opposes",
+  "allied_with",
+  "supports",
+  "causes",
+  "caused_by",
+  "results_in",
+  "has_effect",
+  "uses",
+  "used_by",
+  "applies_to",
+  "based_on",
+  "derived_from",
+  "depicts",
+  "named_after",
+  "has_characteristic",
+  "related_to",
+  "associated_with",
+  "connected_to",
+  "corresponds_to",
+  "main_subject",
+  "about",
+  "context_for",
+  "described_as",
+  "refers_to",
+  "concerns",
+  "discusses",
+  "compares_with",
+  "overlaps_with",
+  "coexists_with",
+  "parallel_to",
+  "analogous_to",
+  "mentioned_with",
+  "points_to",
+  "interpreted_as",
+  "seen_as",
+  "different_from",
+  "distinct_from",
+  "not_same_as",
+  "not_to_be_confused_with",
+  "contrasts_with",
+  "opposite_of",
+  "conflicts_with",
+  "contradicts",
+  "excludes",
+  "incompatible_with",
+  "rejects",
+  "criticizes",
+  "denies",
+  "not_reducible_to"
+];
+const resolver = new EvidenceResolver();
+async function discoverWikilinkRelations(options) {
+  if (options.window.mentions.length < 2) {
+    return [];
+  }
+  try {
+    return await requestGuaranteedJson({
+      messages: buildRelationMessages(options),
+      parse: (response) => parseRelationResponse(options, response),
+      request: options.request,
+      responseIntentClassifierPrompt: RESPONSE_INTENT_CLASSIFIER_PROMPT_TEMPLATE,
+      schema: relationResponseSchema,
+      ...options.maxRetries === void 0 ? {} : { maxRetries: options.maxRetries }
+    });
+  } catch {
+    return [];
+  }
+}
+function parseRelationResponse(options, response) {
+  const mentionsById = new Map(
+    options.window.mentions.map((mention) => [mention.id, mention])
+  );
+  const projection = new FragmentProjection(
+    options.sentences.map((sentence, index) => ({
+      sentenceId: [options.chapterId, (options.fragmentId ?? 0) + index],
+      text: sentence.text,
+      wordsCount: sentence.wordsCount
+    }))
+  );
+  const sentenceOffsets = buildSentenceOffsets(options.sentences);
+  const evidenceSentences = projection.sentences.flatMap(
+    (sentence, sentenceIndex) => {
+      const offset = sentenceOffsets[sentenceIndex];
+      if (offset === void 0 || !rangesOverlap(offset, options.window.range)) {
+        return [];
+      }
+      return [
+        {
+          id: `S${sentenceIndex + 1}`,
+          sentenceId: sentence.sentenceId,
+          text: sentence.projectedText
+        }
+      ];
+    }
+  );
+  const issues = [];
+  const links = [];
+  const seenKeys = /* @__PURE__ */ new Set();
+  const sentenceIds = evidenceSentences.map((sentence) => sentence.sentenceId);
+  const sentenceTexts = evidenceSentences.map((sentence) => sentence.text);
+  for (const [index, relation] of response.relations.entries()) {
+    const prefix = `relations[${index}]`;
+    const source = mentionsById.get(relation.sourceMentionId);
+    const target = mentionsById.get(relation.targetMentionId);
+    if (source === void 0) {
+      issues.push(`${prefix}.sourceMentionId references an unknown mention.`);
+      continue;
+    }
+    if (target === void 0) {
+      issues.push(`${prefix}.targetMentionId references an unknown mention.`);
+      continue;
+    }
+    if (source.id === target.id) {
+      issues.push(
+        `${prefix} links a mention to itself. Use two different tagged mention IDs, or remove the relation if the other endpoint is not tagged.`
+      );
+      continue;
+    }
+    const predicate = normalizePredicate(relation.predicate);
+    if (predicate === "") {
+      issues.push(`${prefix}.predicate normalizes to an empty label.`);
+      continue;
+    }
+    if (predicate === "mentions") {
+      issues.push(
+        `${prefix}.predicate must be semantic; "mentions" is not a relation predicate.`
+      );
+      continue;
+    }
+    const [selectionResolution, selectionFailure] = resolveRelationEvidence({
+      evidence: createRelationEvidenceSelection(relation.evidence),
+      sentences: evidenceSentences
+    });
+    const [anchorResolution, anchorFailure] = !Array.isArray(relation.evidence) && selectionResolution === void 0 && selectionFailure === void 0 ? resolver.resolve(relation.evidence, sentenceIds, sentenceTexts) : [void 0, void 0];
+    const effectiveResolution = selectionResolution ?? anchorResolution;
+    const effectiveFailure = selectionFailure === void 0 ? anchorFailure : toEvidenceResolutionFailure(selectionFailure);
+    if (effectiveResolution === void 0) {
+      issues.push(
+        `${prefix}.evidence could not be resolved: ${effectiveFailure?.message ?? "unknown failure"}`
+      );
+      continue;
+    }
+    const evidenceSentenceIds = dedupeSentenceIds(
+      effectiveResolution.sentenceIds
+    );
+    if (evidenceSentenceIds.length === 0) {
+      issues.push(`${prefix}.evidence resolved to no sentences.`);
+      continue;
+    }
+    if (evidenceSentenceIds.some(
+      ([chapterId, sentenceIndex]) => chapterId !== options.chapterId || sentenceOffsets[sentenceIndex - (options.fragmentId ?? 0)] === void 0
+    )) {
+      issues.push(`${prefix}.evidence resolved outside this fragment.`);
+      continue;
+    }
+    const key = `${source.id}\0${target.id}\0${predicate}\0${evidenceSentenceIds.map((sentenceId) => sentenceId.join(":")).join(",")}`;
+    if (seenKeys.has(key)) {
+      continue;
+    }
+    seenKeys.add(key);
+    links.push({
+      ...relation.confidence === void 0 ? {} : { confidence: relation.confidence },
+      evidenceSentenceIds,
+      predicate,
+      sourceMentionId: source.id,
+      targetMentionId: target.id
+    });
+  }
+  if (issues.length > 0) {
+    throw new ParsedJsonError(issues);
+  }
+  return links;
+}
+function dedupeSentenceIds(sentenceIds) {
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const sentenceId of sentenceIds) {
+    const key = sentenceId.join(":");
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(sentenceId);
+  }
+  return deduped.sort(
+    ([leftChapter, leftSentence], [rightChapter, rightSentence]) => leftChapter - rightChapter || leftSentence - rightSentence
+  );
+}
+function buildRelationMessages(input) {
+  return [
+    {
+      content: formatRelationSystemPrompt(),
+      role: "system"
+    },
+    {
+      content: formatRelationUserPrompt(input),
+      role: "user"
+    }
+  ];
+}
+function formatRelationSystemPrompt() {
+  return [
+    "You discover semantic relations between grounded entity mentions in source text.",
+    "",
+    "Rules:",
+    "- Return JSON only.",
+    "- Return only relations that are directly supported by the source text.",
+    '- Every relation must connect two mention IDs from the <mention id="..." qid="..."> tags.',
+    "- A relation is valid only when both endpoints are explicitly tagged mentions in the source context.",
+    "- If a supported relation would require a subject or object that is not tagged with a mention ID, skip that relation.",
+    "- Do not invent mention IDs, and do not reuse another mention as a placeholder for an untagged endpoint.",
+    "- sourceMentionId and targetMentionId must be different mention IDs; never link a mention to itself.",
+    "- Do not create a relation just because two mentions are nearby.",
+    "- If the text explicitly states both a positive relation and a negated/distinction relation between mentions, return both relations when both are directly supported.",
+    "- Prefer the suggested predicates when one fits.",
+    "- If none fits, create one short snake_case predicate.",
+    "- Never use mentions as a predicate.",
+    EVIDENCE_SELECTION_PROMPT_FRAGMENT,
+    "- Source sentences may contain XML-like mention tags. Use those tags for mention IDs, but ignore the tags when copying evidence quote text.",
+    "- Do not use offsets or invented paraphrases as evidence.",
+    "",
+    "Suggested predicates:",
+    SUGGESTED_PREDICATES.join(", ")
+  ].join("\n");
+}
+function formatRelationUserPrompt(input) {
+  return [
+    "Source sentences with mention tags:",
+    formatTaggedEvidenceSentences(input),
+    "",
+    "Return this JSON shape:",
+    JSON.stringify(
+      {
+        relations: [
+          {
+            confidence: 0.86,
+            evidence: EVIDENCE_SELECTION_JSON_SHAPE,
+            predicate: "predicate_name",
+            sourceMentionId: "source mention id",
+            targetMentionId: "target mention id"
+          }
+        ]
+      },
+      null,
+      2
+    ),
+    "",
+    "If the source text does not support any semantic relation, return:",
+    JSON.stringify({ relations: [] })
+  ].join("\n");
+}
+function formatTaggedEvidenceSentences(input) {
+  const sourceOffsets = buildSentenceOffsets(input.sentences);
+  const lines = input.sentences.flatMap((sentence, index) => {
+    const offset = sourceOffsets[index];
+    if (offset === void 0 || !rangesOverlap(offset, input.window.range)) {
+      return [];
+    }
+    return [
+      `S${index + 1}: ${normalizeEvidenceDisplayText(
+        formatTaggedSentence({
+          mentions: input.window.mentions,
+          sentence,
+          sentenceOffset: offset
+        })
+      )}`
+    ];
+  });
+  return lines.length === 0 ? formatTaggedContext(input.window) : lines.join("\n");
+}
+function formatTaggedSentence(input) {
+  const mentions = input.mentions.filter(
+    (mention) => mention.range.start >= input.sentenceOffset.start && mention.range.end <= input.sentenceOffset.end
+  ).sort((left, right) => left.range.start - right.range.start);
+  const parts = [];
+  let cursor = input.sentenceOffset.start;
+  for (const mention of mentions) {
+    parts.push(
+      escapeXmlText(
+        input.sentence.text.slice(
+          cursor - input.sentenceOffset.start,
+          mention.range.start - input.sentenceOffset.start
+        )
+      )
+    );
+    parts.push(
+      `<mention id="${escapeXmlAttribute(mention.id)}" qid="${escapeXmlAttribute(
+        mention.qid ?? ""
+      )}">${escapeXmlText(
+        input.sentence.text.slice(
+          mention.range.start - input.sentenceOffset.start,
+          mention.range.end - input.sentenceOffset.start
+        )
+      )}</mention>`
+    );
+    cursor = mention.range.end;
+  }
+  parts.push(
+    escapeXmlText(
+      input.sentence.text.slice(cursor - input.sentenceOffset.start)
+    )
+  );
+  return parts.join("");
+}
+function rangesOverlap(left, right) {
+  return left.start < right.end && right.start < left.end;
+}
+function resolveRelationEvidence(input) {
+  if (input.evidence === void 0) {
+    return [void 0, void 0];
+  }
+  return resolveEvidenceSelectionList({
+    evidence: input.evidence,
+    sentences: input.sentences
+  });
+}
+function createRelationEvidenceSelection(evidence) {
+  if (Array.isArray(evidence)) {
+    return evidence.map(createRelationEvidenceSelectionItem);
+  }
+  const hasSelectionEvidence = typeof evidence.quote === "string" || typeof evidence.sentence_id === "string";
+  return hasSelectionEvidence ? createRelationEvidenceSelectionItem(evidence) : void 0;
+}
+function createRelationEvidenceSelectionItem(evidence) {
+  return {
+    ...typeof evidence.quote === "string" ? { quote: evidence.quote } : {},
+    ...typeof evidence.sentence_id === "string" ? { sentence_id: evidence.sentence_id } : {}
+  };
+}
+function toEvidenceResolutionFailure(failure) {
+  return {
+    candidates: failure.candidates.map((candidate) => ({
+      exactNormalized: candidate.exactNormalized,
+      exactRaw: candidate.exactRaw,
+      exactSubstring: candidate.exactSubstring,
+      index: candidate.index,
+      nextText: candidate.nextText,
+      occurrenceId: candidate.occurrenceId,
+      prevText: candidate.prevText,
+      score: candidate.score,
+      sentenceId: candidate.sentence.sentenceId,
+      text: candidate.sentence.text
+    })),
+    code: failure.code,
+    fieldName: "evidence",
+    message: failure.message
+  };
+}
+function formatTaggedContext(window) {
+  const mentions = [...window.mentions].sort(
+    (left, right) => left.range.start - right.range.start
+  );
+  const parts = [];
+  let cursor = window.range.start;
+  for (const mention of mentions) {
+    parts.push(
+      escapeXmlText(
+        window.text.slice(
+          cursor - window.range.start,
+          mention.range.start - window.range.start
+        )
+      )
+    );
+    parts.push(
+      `<mention id="${escapeXmlAttribute(mention.id)}" qid="${escapeXmlAttribute(
+        mention.qid ?? ""
+      )}">${escapeXmlText(
+        window.text.slice(
+          mention.range.start - window.range.start,
+          mention.range.end - window.range.start
+        )
+      )}</mention>`
+    );
+    cursor = mention.range.end;
+  }
+  parts.push(escapeXmlText(window.text.slice(cursor - window.range.start)));
+  return parts.join("");
+}
+function buildSentenceOffsets(sentences) {
+  const offsets = [];
+  let cursor = 0;
+  for (const sentence of sentences) {
+    const start = cursor;
+    const end = start + sentence.text.length;
+    offsets.push({ end, start });
+    cursor = end + 1;
+  }
+  return offsets;
+}
+function normalizePredicate(predicate) {
+  return predicate.trim().replace(/[\s-]+/gu, "_").replace(/_+/gu, "_").replace(/^_+|_+$/gu, "").toLowerCase();
+}
+function escapeXmlAttribute(value) {
+  return escapeXmlText(value).replaceAll('"', "&quot;");
+}
+function escapeXmlText(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+export {
+  discoverWikilinkRelations
+};
+//# sourceMappingURL=relation-discovery.js.map

package/dist/wikilink/relation-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wikilink/relation-discovery.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\";\nimport {\n  EVIDENCE_SELECTION_JSON_SHAPE,\n  EVIDENCE_SELECTION_PROMPT_FRAGMENT,\n  EvidenceResolver,\n  normalizeEvidenceDisplayText,\n  resolveEvidenceSelectionList,\n  type EvidenceSelectionCandidate,\n  type EvidenceSelectionList,\n  type EvidenceSelectionSentence,\n  type EvidenceResolutionFailure,\n} from \"../evidence-selection/index.js\";\nimport { FragmentProjection } from \"../reader/chunk-batch/index.js\";\nimport type { SentenceId } from \"../document/index.js\";\n\nimport type { WikilinkEvidenceWindow, WikilinkMention } from \"./types.js\";\n\nexport interface WikilinkSentence {\n  readonly text: string;\n  readonly wordsCount: number;\n}\n\nexport interface WikilinkDiscoveredRelation {\n  readonly confidence?: number;\n  readonly evidenceSentenceIds: readonly SentenceId[];\n  readonly predicate: string;\n  readonly sourceMentionId: string;\n  readonly targetMentionId: string;\n}\n\nexport interface DiscoverWikilinkRelationsOptions {\n  readonly chapterId: number;\n  readonly fragmentId?: number;\n  readonly maxRetries?: number;\n  readonly request: GuaranteedRequest;\n  readonly sentences: readonly WikilinkSentence[];\n  readonly window: WikilinkEvidenceWindow;\n}\n\nconst evidenceAnchorSchema = z\n  .object({\n    head: z.string().optional(),\n    mode: z.enum([\"full\", \"head_tail\"]).optional(),\n    tail: z.string().optional(),\n    text: z.string().optional(),\n  })\n  .strict();\nconst evidenceSelectionItemSchema = z\n  .object({\n    quote: z.string().optional(),\n    sentence_id: z.string().optional(),\n  })\n  .strict();\nconst relationEvidenceSchema = z.union([\n  z\n    .object({\n      end_anchor: z.union([z.string(), evidenceAnchorSchema]).optional(),\n      quote: z.string().optional(),\n      sentence_id: z.string().optional(),\n      start_anchor: z.union([z.string(), evidenceAnchorSchema]).optional(),\n    })\n    .strict(),\n  z.array(evidenceSelectionItemSchema),\n]);\n\nconst relationSchema = z\n  .object({\n    confidence: z.number().min(0).max(1).optional(),\n    evidence: relationEvidenceSchema,\n    predicate: z.string().min(1).max(64),\n    sourceMentionId: z.string().min(1),\n    targetMentionId: z.string().min(1),\n  })\n  .strict();\n\nconst relationResponseSchema = z\n  .object({\n    relations: z.array(relationSchema),\n  })\n  .strict();\n\ntype RelationEvidenceData = z.infer<typeof relationEvidenceSchema>;\n\nconst SUGGESTED_PREDICATES = [\n  \"instance_of\",\n  \"subclass_of\",\n  \"part_of\",\n  \"has_part\",\n  \"located_in\",\n  \"contains\",\n  \"member_of\",\n  \"owned_by\",\n  \"creator\",\n  \"author\",\n  \"developer\",\n  \"founded_by\",\n  \"leader\",\n  \"position_held\",\n  \"employer\",\n  \"educated_at\",\n  \"student_of\",\n  \"parent\",\n  \"child\",\n  \"spouse\",\n  \"sibling\",\n  \"relative\",\n  \"replaces\",\n  \"replaced_by\",\n  \"precedes\",\n  \"follows\",\n  \"influenced_by\",\n  \"influences\",\n  \"participant_in\",\n  \"participant\",\n  \"conflict\",\n  \"opposes\",\n  \"allied_with\",\n  \"supports\",\n  \"causes\",\n  \"caused_by\",\n  \"results_in\",\n  \"has_effect\",\n  \"uses\",\n  \"used_by\",\n  \"applies_to\",\n  \"based_on\",\n  \"derived_from\",\n  \"depicts\",\n  \"named_after\",\n  \"has_characteristic\",\n  \"related_to\",\n  \"associated_with\",\n  \"connected_to\",\n  \"corresponds_to\",\n  \"main_subject\",\n  \"about\",\n  \"context_for\",\n  \"described_as\",\n  \"refers_to\",\n  \"concerns\",\n  \"discusses\",\n  \"compares_with\",\n  \"overlaps_with\",\n  \"coexists_with\",\n  \"parallel_to\",\n  \"analogous_to\",\n  \"mentioned_with\",\n  \"points_to\",\n  \"interpreted_as\",\n  \"seen_as\",\n  \"different_from\",\n  \"distinct_from\",\n  \"not_same_as\",\n  \"not_to_be_confused_with\",\n  \"contrasts_with\",\n  \"opposite_of\",\n  \"conflicts_with\",\n  \"contradicts\",\n  \"excludes\",\n  \"incompatible_with\",\n  \"rejects\",\n  \"criticizes\",\n  \"denies\",\n  \"not_reducible_to\",\n] as const;\n\nconst resolver = new EvidenceResolver();\n\nexport async function discoverWikilinkRelations(\n  options: DiscoverWikilinkRelationsOptions,\n): Promise<readonly WikilinkDiscoveredRelation[]> {\n  if (options.window.mentions.length < 2) {\n    return [];\n  }\n\n  try {\n    return await requestGuaranteedJson({\n      messages: buildRelationMessages(options),\n      parse: (response) => parseRelationResponse(options, response),\n      request: options.request,\n      responseIntentClassifierPrompt:\n        RESPONSE_INTENT_CLASSIFIER_PROMPT_TEMPLATE,\n      schema: relationResponseSchema,\n      ...(options.maxRetries === undefined\n        ? {}\n        : { maxRetries: options.maxRetries }),\n    });\n  } catch {\n    return [];\n  }\n}\n\nfunction parseRelationResponse(\n  options: DiscoverWikilinkRelationsOptions,\n  response: z.infer<typeof relationResponseSchema>,\n): readonly WikilinkDiscoveredRelation[] {\n  const mentionsById = new Map(\n    options.window.mentions.map((mention) => [mention.id, mention]),\n  );\n  const projection = new FragmentProjection(\n    options.sentences.map((sentence, index) => ({\n      sentenceId: [options.chapterId, (options.fragmentId ?? 0) + index],\n      text: sentence.text,\n      wordsCount: sentence.wordsCount,\n    })),\n  );\n  const sentenceOffsets = buildSentenceOffsets(options.sentences);\n  const evidenceSentences = projection.sentences.flatMap(\n    (sentence, sentenceIndex) => {\n      const offset = sentenceOffsets[sentenceIndex];\n\n      if (\n        offset === undefined ||\n        !rangesOverlap(offset, options.window.range)\n      ) {\n        return [];\n      }\n\n      return [\n        {\n          id: `S${sentenceIndex + 1}`,\n          sentenceId: sentence.sentenceId,\n          text: sentence.projectedText,\n        },\n      ];\n    },\n  );\n  const issues: string[] = [];\n  const links: WikilinkDiscoveredRelation[] = [];\n  const seenKeys = new Set<string>();\n  const sentenceIds = evidenceSentences.map((sentence) => sentence.sentenceId);\n  const sentenceTexts = evidenceSentences.map((sentence) => sentence.text);\n\n  for (const [index, relation] of response.relations.entries()) {\n    const prefix = `relations[${index}]`;\n    const source = mentionsById.get(relation.sourceMentionId);\n    const target = mentionsById.get(relation.targetMentionId);\n\n    if (source === undefined) {\n      issues.push(`${prefix}.sourceMentionId references an unknown mention.`);\n      continue;\n    }\n    if (target === undefined) {\n      issues.push(`${prefix}.targetMentionId references an unknown mention.`);\n      continue;\n    }\n    if (source.id === target.id) {\n      issues.push(\n        `${prefix} links a mention to itself. ` +\n          \"Use two different tagged mention IDs, or remove the relation if the other endpoint is not tagged.\",\n      );\n      continue;\n    }\n\n    const predicate = normalizePredicate(relation.predicate);\n\n    if (predicate === \"\") {\n      issues.push(`${prefix}.predicate normalizes to an empty label.`);\n      continue;\n    }\n\n    if (predicate === \"mentions\") {\n      issues.push(\n        `${prefix}.predicate must be semantic; \"mentions\" is not a relation predicate.`,\n      );\n      continue;\n    }\n\n    const [selectionResolution, selectionFailure] = resolveRelationEvidence({\n      evidence: createRelationEvidenceSelection(relation.evidence),\n      sentences: evidenceSentences,\n    });\n    const [anchorResolution, anchorFailure] =\n      !Array.isArray(relation.evidence) &&\n      selectionResolution === undefined &&\n      selectionFailure === undefined\n        ? resolver.resolve(relation.evidence, sentenceIds, sentenceTexts)\n        : [undefined, undefined];\n    const effectiveResolution = selectionResolution ?? anchorResolution;\n    const effectiveFailure =\n      selectionFailure === undefined\n        ? anchorFailure\n        : toEvidenceResolutionFailure(selectionFailure);\n\n    if (effectiveResolution === undefined) {\n      issues.push(\n        `${prefix}.evidence could not be resolved: ${\n          effectiveFailure?.message ?? \"unknown failure\"\n        }`,\n      );\n      continue;\n    }\n\n    const evidenceSentenceIds = dedupeSentenceIds(\n      effectiveResolution.sentenceIds,\n    );\n\n    if (evidenceSentenceIds.length === 0) {\n      issues.push(`${prefix}.evidence resolved to no sentences.`);\n      continue;\n    }\n\n    if (\n      evidenceSentenceIds.some(\n        ([chapterId, sentenceIndex]) =>\n          chapterId !== options.chapterId ||\n          sentenceOffsets[sentenceIndex - (options.fragmentId ?? 0)] ===\n            undefined,\n      )\n    ) {\n      issues.push(`${prefix}.evidence resolved outside this fragment.`);\n      continue;\n    }\n\n    const key = `${source.id}\\0${target.id}\\0${predicate}\\0${evidenceSentenceIds.map((sentenceId) => sentenceId.join(\":\")).join(\",\")}`;\n\n    if (seenKeys.has(key)) {\n      continue;\n    }\n    seenKeys.add(key);\n\n    links.push({\n      ...(relation.confidence === undefined\n        ? {}\n        : { confidence: relation.confidence }),\n      evidenceSentenceIds,\n      predicate,\n      sourceMentionId: source.id,\n      targetMentionId: target.id,\n    });\n  }\n\n  if (issues.length > 0) {\n    throw new ParsedJsonError(issues);\n  }\n\n  return links;\n}\n\nfunction dedupeSentenceIds(\n  sentenceIds: readonly SentenceId[],\n): readonly SentenceId[] {\n  const seen = new Set<string>();\n  const deduped: SentenceId[] = [];\n\n  for (const sentenceId of sentenceIds) {\n    const key = sentenceId.join(\":\");\n\n    if (seen.has(key)) {\n      continue;\n    }\n\n    seen.add(key);\n    deduped.push(sentenceId);\n  }\n\n  return deduped.sort(\n    ([leftChapter, leftSentence], [rightChapter, rightSentence]) =>\n      leftChapter - rightChapter || leftSentence - rightSentence,\n  );\n}\n\nfunction buildRelationMessages(\n  input: DiscoverWikilinkRelationsOptions,\n): LLMessage[] {\n  return [\n    {\n      content: formatRelationSystemPrompt(),\n      role: \"system\",\n    },\n    {\n      content: formatRelationUserPrompt(input),\n      role: \"user\",\n    },\n  ];\n}\n\nfunction formatRelationSystemPrompt(): string {\n  return [\n    \"You discover semantic relations between grounded entity mentions in source text.\",\n    \"\",\n    \"Rules:\",\n    \"- Return JSON only.\",\n    \"- Return only relations that are directly supported by the source text.\",\n    '- Every relation must connect two mention IDs from the <mention id=\"...\" qid=\"...\"> tags.',\n    \"- A relation is valid only when both endpoints are explicitly tagged mentions in the source context.\",\n    \"- If a supported relation would require a subject or object that is not tagged with a mention ID, skip that relation.\",\n    \"- Do not invent mention IDs, and do not reuse another mention as a placeholder for an untagged endpoint.\",\n    \"- sourceMentionId and targetMentionId must be different mention IDs; never link a mention to itself.\",\n    \"- Do not create a relation just because two mentions are nearby.\",\n    \"- If the text explicitly states both a positive relation and a negated/distinction relation between mentions, return both relations when both are directly supported.\",\n    \"- Prefer the suggested predicates when one fits.\",\n    \"- If none fits, create one short snake_case predicate.\",\n    \"- Never use mentions as a predicate.\",\n    EVIDENCE_SELECTION_PROMPT_FRAGMENT,\n    \"- Source sentences may contain XML-like mention tags. Use those tags for mention IDs, but ignore the tags when copying evidence quote text.\",\n    \"- Do not use offsets or invented paraphrases as evidence.\",\n    \"\",\n    \"Suggested predicates:\",\n    SUGGESTED_PREDICATES.join(\", \"),\n  ].join(\"\\n\");\n}\n\nfunction formatRelationUserPrompt(\n  input: DiscoverWikilinkRelationsOptions,\n): string {\n  return [\n    \"Source sentences with mention tags:\",\n    formatTaggedEvidenceSentences(input),\n    \"\",\n    \"Return this JSON shape:\",\n    JSON.stringify(\n      {\n        relations: [\n          {\n            confidence: 0.86,\n            evidence: EVIDENCE_SELECTION_JSON_SHAPE,\n            predicate: \"predicate_name\",\n            sourceMentionId: \"source mention id\",\n            targetMentionId: \"target mention id\",\n          },\n        ],\n      },\n      null,\n      2,\n    ),\n    \"\",\n    \"If the source text does not support any semantic relation, return:\",\n    JSON.stringify({ relations: [] }),\n  ].join(\"\\n\");\n}\n\nfunction formatTaggedEvidenceSentences(\n  input: DiscoverWikilinkRelationsOptions,\n): string {\n  const sourceOffsets = buildSentenceOffsets(input.sentences);\n  const lines = input.sentences.flatMap((sentence, index) => {\n    const offset = sourceOffsets[index];\n\n    if (offset === undefined || !rangesOverlap(offset, input.window.range)) {\n      return [];\n    }\n\n    return [\n      `S${index + 1}: ${normalizeEvidenceDisplayText(\n        formatTaggedSentence({\n          mentions: input.window.mentions,\n          sentence,\n          sentenceOffset: offset,\n        }),\n      )}`,\n    ];\n  });\n\n  return lines.length === 0\n    ? formatTaggedContext(input.window)\n    : lines.join(\"\\n\");\n}\n\nfunction formatTaggedSentence(input: {\n  readonly mentions: readonly WikilinkMention[];\n  readonly sentence: WikilinkSentence;\n  readonly sentenceOffset: { readonly end: number; readonly start: number };\n}): string {\n  const mentions = input.mentions\n    .filter(\n      (mention) =>\n        mention.range.start >= input.sentenceOffset.start &&\n        mention.range.end <= input.sentenceOffset.end,\n    )\n    .sort((left, right) => left.range.start - right.range.start);\n  const parts: string[] = [];\n  let cursor = input.sentenceOffset.start;\n\n  for (const mention of mentions) {\n    parts.push(\n      escapeXmlText(\n        input.sentence.text.slice(\n          cursor - input.sentenceOffset.start,\n          mention.range.start - input.sentenceOffset.start,\n        ),\n      ),\n    );\n    parts.push(\n      `<mention id=\"${escapeXmlAttribute(mention.id)}\" qid=\"${escapeXmlAttribute(\n        mention.qid ?? \"\",\n      )}\">${escapeXmlText(\n        input.sentence.text.slice(\n          mention.range.start - input.sentenceOffset.start,\n          mention.range.end - input.sentenceOffset.start,\n        ),\n      )}</mention>`,\n    );\n    cursor = mention.range.end;\n  }\n\n  parts.push(\n    escapeXmlText(\n      input.sentence.text.slice(cursor - input.sentenceOffset.start),\n    ),\n  );\n\n  return parts.join(\"\");\n}\n\nfunction rangesOverlap(\n  left: { readonly end: number; readonly start: number },\n  right: { readonly end: number; readonly start: number },\n): boolean {\n  return left.start < right.end && right.start < left.end;\n}\n\nfunction resolveRelationEvidence(input: {\n  readonly evidence: EvidenceSelectionList | undefined;\n  readonly sentences: readonly EvidenceSelectionSentence[];\n}): readonly [\n  resolution:\n    | {\n        readonly sentenceIds: readonly (readonly [number, number])[];\n      }\n    | undefined,\n  failure:\n    | {\n        readonly candidates: readonly EvidenceSelectionCandidate[];\n        readonly code: string;\n        readonly message: string;\n      }\n    | undefined,\n] {\n  if (input.evidence === undefined) {\n    return [undefined, undefined];\n  }\n\n  return resolveEvidenceSelectionList({\n    evidence: input.evidence,\n    sentences: input.sentences,\n  });\n}\n\nfunction createRelationEvidenceSelection(\n  evidence: RelationEvidenceData,\n): EvidenceSelectionList | undefined {\n  if (Array.isArray(evidence)) {\n    return evidence.map(createRelationEvidenceSelectionItem);\n  }\n\n  const hasSelectionEvidence =\n    typeof evidence.quote === \"string\" ||\n    typeof evidence.sentence_id === \"string\";\n\n  return hasSelectionEvidence\n    ? createRelationEvidenceSelectionItem(evidence)\n    : undefined;\n}\n\nfunction createRelationEvidenceSelectionItem(evidence: {\n  readonly quote?: unknown;\n  readonly sentence_id?: unknown;\n}): {\n  readonly quote?: string;\n  readonly sentence_id?: string;\n} {\n  return {\n    ...(typeof evidence.quote === \"string\" ? { quote: evidence.quote } : {}),\n    ...(typeof evidence.sentence_id === \"string\"\n      ? { sentence_id: evidence.sentence_id }\n      : {}),\n  };\n}\n\nfunction toEvidenceResolutionFailure(failure: {\n  readonly candidates: readonly EvidenceSelectionCandidate[];\n  readonly code: string;\n  readonly message: string;\n}): EvidenceResolutionFailure {\n  return {\n    candidates: failure.candidates.map((candidate) => ({\n      exactNormalized: candidate.exactNormalized,\n      exactRaw: candidate.exactRaw,\n      exactSubstring: candidate.exactSubstring,\n      index: candidate.index,\n      nextText: candidate.nextText,\n      occurrenceId: candidate.occurrenceId,\n      prevText: candidate.prevText,\n      score: candidate.score,\n      sentenceId: candidate.sentence.sentenceId,\n      text: candidate.sentence.text,\n    })),\n    code: failure.code,\n    fieldName: \"evidence\",\n    message: failure.message,\n  };\n}\n\nfunction formatTaggedContext(window: WikilinkEvidenceWindow): string {\n  const mentions = [...window.mentions].sort(\n    (left, right) => left.range.start - right.range.start,\n  );\n  const parts: string[] = [];\n  let cursor = window.range.start;\n\n  for (const mention of mentions) {\n    parts.push(\n      escapeXmlText(\n        window.text.slice(\n          cursor - window.range.start,\n          mention.range.start - window.range.start,\n        ),\n      ),\n    );\n    parts.push(\n      `<mention id=\"${escapeXmlAttribute(mention.id)}\" qid=\"${escapeXmlAttribute(\n        mention.qid ?? \"\",\n      )}\">${escapeXmlText(\n        window.text.slice(\n          mention.range.start - window.range.start,\n          mention.range.end - window.range.start,\n        ),\n      )}</mention>`,\n    );\n    cursor = mention.range.end;\n  }\n\n  parts.push(escapeXmlText(window.text.slice(cursor - window.range.start)));\n\n  return parts.join(\"\");\n}\n\nfunction buildSentenceOffsets(\n  sentences: readonly WikilinkSentence[],\n): ReadonlyArray<{ readonly end: number; readonly start: number }> {\n  const offsets: Array<{ readonly end: number; readonly start: number }> = [];\n  let cursor = 0;\n\n  for (const sentence of sentences) {\n    const start = cursor;\n    const end = start + sentence.text.length;\n\n    offsets.push({ end, start });\n    cursor = end + 1;\n  }\n\n  return offsets;\n}\n\nfunction normalizePredicate(predicate: string): string {\n  return predicate\n    .trim()\n    .replace(/[\\s-]+/gu, \"_\")\n    .replace(/_+/gu, \"_\")\n    .replace(/^_+|_+$/gu, \"\")\n    .toLowerCase();\n}\n\nfunction escapeXmlAttribute(value: string): string {\n  return escapeXmlText(value).replaceAll('\"', \"&quot;\");\n}\n\nfunction escapeXmlText(value: string): string {\n  return value\n    .replaceAll(\"&\", \"&amp;\")\n    .replaceAll(\"<\", \"&lt;\")\n    .replaceAll(\">\", \"&gt;\");\n}\n"],"mappings":"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","names":[]}

package/dist/wikilink/types.d.ts

@@ -0,0 +1,23 @@
+import { WikimatchTextRange } from '../wikimatch/types.js';
+import '../wikipage/types.js';
+
+interface WikilinkMention {
+    readonly id: string;
+    readonly qid?: string;
+    readonly range: WikimatchTextRange;
+    readonly surface?: string;
+}
+interface WikilinkEvidenceWindow {
+    readonly baseOffset: number;
+    readonly mentions: readonly WikilinkMention[];
+    readonly range: WikimatchTextRange;
+    readonly text: string;
+}
+interface BuildWikilinkEvidenceWindowsOptions {
+    readonly maxEvidenceDistance: number;
+    readonly mentions: readonly WikilinkMention[];
+    readonly text: string;
+    readonly windowLength: number;
+}
+
+export type { BuildWikilinkEvidenceWindowsOptions, WikilinkEvidenceWindow, WikilinkMention };

package/dist/wikilink/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/wikilink/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/wikilink/window.d.ts

@@ -0,0 +1,7 @@
+import { BuildWikilinkEvidenceWindowsOptions, WikilinkEvidenceWindow } from './types.js';
+import '../wikimatch/types.js';
+import '../wikipage/types.js';
+
+declare function buildWikilinkEvidenceWindows(options: BuildWikilinkEvidenceWindowsOptions): readonly WikilinkEvidenceWindow[];
+
+export { buildWikilinkEvidenceWindows };

package/dist/wikilink/window.js

@@ -0,0 +1,53 @@
+function buildWikilinkEvidenceWindows(options) {
+  validateOptions(options);
+  const mentions = normalizeMentions(options.mentions);
+  if (mentions.length === 0 || options.text.length === 0) {
+    return [];
+  }
+  const stride = options.windowLength - options.maxEvidenceDistance;
+  const windows = [];
+  for (let start = 0; start < options.text.length; start = nextWindowStart(start, stride, options.text.length)) {
+    const end = Math.min(start + options.windowLength, options.text.length);
+    const windowMentions = mentions.filter(
+      (mention) => mention.range.start >= start && mention.range.end <= end
+    );
+    if (windowMentions.length >= 2) {
+      windows.push({
+        baseOffset: start,
+        mentions: windowMentions,
+        range: { end, start },
+        text: options.text.slice(start, end)
+      });
+    }
+    if (end >= options.text.length) {
+      break;
+    }
+  }
+  return windows;
+}
+function nextWindowStart(current, stride, textLength) {
+  return Math.min(current + stride, textLength);
+}
+function validateOptions(options) {
+  if (!Number.isInteger(options.windowLength) || options.windowLength <= 0) {
+    throw new Error("windowLength must be a positive integer.");
+  }
+  if (!Number.isInteger(options.maxEvidenceDistance) || options.maxEvidenceDistance <= 0) {
+    throw new Error("maxEvidenceDistance must be a positive integer.");
+  }
+  if (options.windowLength <= options.maxEvidenceDistance) {
+    throw new Error(
+      "windowLength must be greater than maxEvidenceDistance so eligible mention pairs are guaranteed to share at least one evidence window."
+    );
+  }
+}
+function normalizeMentions(mentions) {
+  return mentions.filter((mention) => mention.range.start < mention.range.end).sort(compareMention);
+}
+function compareMention(left, right) {
+  return left.range.start - right.range.start || left.range.end - right.range.end || left.id.localeCompare(right.id);
+}
+export {
+  buildWikilinkEvidenceWindows
+};
+//# sourceMappingURL=window.js.map

package/dist/wikilink/window.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wikilink/window.ts"],"sourcesContent":["import type {\n  BuildWikilinkEvidenceWindowsOptions,\n  WikilinkEvidenceWindow,\n  WikilinkMention,\n} from \"./types.js\";\n\nexport function buildWikilinkEvidenceWindows(\n  options: BuildWikilinkEvidenceWindowsOptions,\n): readonly WikilinkEvidenceWindow[] {\n  validateOptions(options);\n\n  const mentions = normalizeMentions(options.mentions);\n\n  if (mentions.length === 0 || options.text.length === 0) {\n    return [];\n  }\n\n  const stride = options.windowLength - options.maxEvidenceDistance;\n  const windows: WikilinkEvidenceWindow[] = [];\n\n  for (\n    let start = 0;\n    start < options.text.length;\n    start = nextWindowStart(start, stride, options.text.length)\n  ) {\n    const end = Math.min(start + options.windowLength, options.text.length);\n    const windowMentions = mentions.filter(\n      (mention) => mention.range.start >= start && mention.range.end <= end,\n    );\n\n    if (windowMentions.length >= 2) {\n      windows.push({\n        baseOffset: start,\n        mentions: windowMentions,\n        range: { end, start },\n        text: options.text.slice(start, end),\n      });\n    }\n    if (end >= options.text.length) {\n      break;\n    }\n  }\n\n  return windows;\n}\n\nfunction nextWindowStart(\n  current: number,\n  stride: number,\n  textLength: number,\n): number {\n  return Math.min(current + stride, textLength);\n}\n\nfunction validateOptions(options: BuildWikilinkEvidenceWindowsOptions): void {\n  if (!Number.isInteger(options.windowLength) || options.windowLength <= 0) {\n    throw new Error(\"windowLength must be a positive integer.\");\n  }\n  if (\n    !Number.isInteger(options.maxEvidenceDistance) ||\n    options.maxEvidenceDistance <= 0\n  ) {\n    throw new Error(\"maxEvidenceDistance must be a positive integer.\");\n  }\n  if (options.windowLength <= options.maxEvidenceDistance) {\n    throw new Error(\n      \"windowLength must be greater than maxEvidenceDistance so eligible mention pairs are guaranteed to share at least one evidence window.\",\n    );\n  }\n}\n\nfunction normalizeMentions(\n  mentions: readonly WikilinkMention[],\n): readonly WikilinkMention[] {\n  return mentions\n    .filter((mention) => mention.range.start < mention.range.end)\n    .sort(compareMention);\n}\n\nfunction compareMention(left: WikilinkMention, right: WikilinkMention): number {\n  return (\n    left.range.start - right.range.start ||\n    left.range.end - right.range.end ||\n    left.id.localeCompare(right.id)\n  );\n}\n"],"mappings":"AAMO,SAAS,6BACd,SACmC;AACnC,kBAAgB,OAAO;AAEvB,QAAM,WAAW,kBAAkB,QAAQ,QAAQ;AAEnD,MAAI,SAAS,WAAW,KAAK,QAAQ,KAAK,WAAW,GAAG;AACtD,WAAO,CAAC;AAAA,EACV;AAEA,QAAM,SAAS,QAAQ,eAAe,QAAQ;AAC9C,QAAM,UAAoC,CAAC;AAE3C,WACM,QAAQ,GACZ,QAAQ,QAAQ,KAAK,QACrB,QAAQ,gBAAgB,OAAO,QAAQ,QAAQ,KAAK,MAAM,GAC1D;AACA,UAAM,MAAM,KAAK,IAAI,QAAQ,QAAQ,cAAc,QAAQ,KAAK,MAAM;AACtE,UAAM,iBAAiB,SAAS;AAAA,MAC9B,CAAC,YAAY,QAAQ,MAAM,SAAS,SAAS,QAAQ,MAAM,OAAO;AAAA,IACpE;AAEA,QAAI,eAAe,UAAU,GAAG;AAC9B,cAAQ,KAAK;AAAA,QACX,YAAY;AAAA,QACZ,UAAU;AAAA,QACV,OAAO,EAAE,KAAK,MAAM;AAAA,QACpB,MAAM,QAAQ,KAAK,MAAM,OAAO,GAAG;AAAA,MACrC,CAAC;AAAA,IACH;AACA,QAAI,OAAO,QAAQ,KAAK,QAAQ;AAC9B;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAEA,SAAS,gBACP,SACA,QACA,YACQ;AACR,SAAO,KAAK,IAAI,UAAU,QAAQ,UAAU;AAC9C;AAEA,SAAS,gBAAgB,SAAoD;AAC3E,MAAI,CAAC,OAAO,UAAU,QAAQ,YAAY,KAAK,QAAQ,gBAAgB,GAAG;AACxE,UAAM,IAAI,MAAM,0CAA0C;AAAA,EAC5D;AACA,MACE,CAAC,OAAO,UAAU,QAAQ,mBAAmB,KAC7C,QAAQ,uBAAuB,GAC/B;AACA,UAAM,IAAI,MAAM,iDAAiD;AAAA,EACnE;AACA,MAAI,QAAQ,gBAAgB,QAAQ,qBAAqB;AACvD,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACF;AAEA,SAAS,kBACP,UAC4B;AAC5B,SAAO,SACJ,OAAO,CAAC,YAAY,QAAQ,MAAM,QAAQ,QAAQ,MAAM,GAAG,EAC3D,KAAK,cAAc;AACxB;AAEA,SAAS,eAAe,MAAuB,OAAgC;AAC7E,SACE,KAAK,MAAM,QAAQ,MAAM,MAAM,SAC/B,KAAK,MAAM,MAAM,MAAM,MAAM,OAC7B,KAAK,GAAG,cAAc,MAAM,EAAE;AAElC;","names":[]}

package/dist/wikimatch/enrichment.d.ts

@@ -0,0 +1,10 @@
+import { QidResolution, WikipageResolveProgressReporter, WikipageResolverOptions } from '../wikipage/types.js';
+import { WikimatchCandidate } from './types.js';
+
+declare function enrichWikimatchCandidates(candidates: readonly WikimatchCandidate[], options?: {
+    readonly progress?: WikipageResolveProgressReporter;
+    readonly resolverOptions?: Omit<WikipageResolverOptions, "progress">;
+}): Promise<readonly WikimatchCandidate[]>;
+declare function applyQidResolutions(candidates: readonly WikimatchCandidate[], resolutions: readonly QidResolution[]): readonly WikimatchCandidate[];
+
+export { applyQidResolutions, enrichWikimatchCandidates };