Skip to content

LLM Wiki is a cross-platform desktop application that turns your documents into an organized, interlinked knowledge base — automatically. Instead of traditional RAG (retrieve-and-answer from scratch every time), the LLM incrementally builds and maintains a persistent wiki from your sources。

TypeScript

fix: real LLM bugs caught by full-suite validation

nash_su80442080b45b
diff --git a/src/lib/enrich-wikilinks.test.ts b/src/lib/enrich-wikilinks.test.ts
index f38d02ee..a8ead18d 100644
--- a/src/lib/enrich-wikilinks.test.ts
+++ b/src/lib/enrich-wikilinks.test.ts
@@ -102,22 +102,43 @@ describe("enrichWithWikilinks — language directive is built at call time", ()
})
})
-describe("enrichWithWikilinks — short-response guard", () => {
- it("does NOT overwrite when LLM returns <50% of original length", async () => {
- const longContent = "x".repeat(1000)
- mockReadFile.mockResolvedValue(longContent)
+describe("enrichWithWikilinks — JSON-based substitution", () => {
+ it("does NOT overwrite when LLM response is not parseable JSON", async () => {
+ // The v2 implementation expects a JSON `{links:[...]}` object; anything
+ // else produces zero substitutions and writeFile is never called.
+ mockReadFile.mockResolvedValue("some real page content with Transformer and Attention mentioned")
mockStreamChatReturns("too short")
await enrichWithWikilinks("/p", "/p/f.md", fakeLlmConfig())
expect(mockWriteFile).not.toHaveBeenCalled()
})
- it("writes back when enriched response is long enough", async () => {
- mockReadFile.mockResolvedValue("hello world, this is long enough content for the guard to pass")
- mockStreamChatReturns("hello [[world]], this is long enough content for the guard to pass")
+ it("writes back when LLM returns a valid JSON substitution list", async () => {
+ mockReadFile.mockResolvedValue(
+ "Transformer is the backbone. Attention is core.",
+ )
+ mockStreamChatReturns(
+ JSON.stringify({
+ links: [
+ { term: "Transformer", target: "transformer" },
+ { term: "Attention", target: "attention" },
+ ],
+ }),
+ )
await enrichWithWikilinks("/p", "/p/f.md", fakeLlmConfig())
expect(mockWriteFile).toHaveBeenCalledOnce()
+ const written = vi.mocked(mockWriteFile).mock.calls[0][1] as string
+ expect(written).toContain("[[Transformer]]")
+ expect(written).toContain("[[Attention]]")
+ })
+
+ it("does NOT overwrite when LLM returns an empty links list", async () => {
+ mockReadFile.mockResolvedValue("a page that matches no index term")
+ mockStreamChatReturns(JSON.stringify({ links: [] }))
+
+ await enrichWithWikilinks("/p", "/p/f.md", fakeLlmConfig())
+ expect(mockWriteFile).not.toHaveBeenCalled()
})
it("returns early when content or index is missing", async () => {
diff --git a/src/lib/enrich-wikilinks.ts b/src/lib/enrich-wikilinks.ts
index 3efcbbe6..5dec8464 100644
--- a/src/lib/enrich-wikilinks.ts
+++ b/src/lib/enrich-wikilinks.ts
@@ -6,7 +6,21 @@ import { normalizePath } from "@/lib/path-utils"
/**
* Lightweight post-save enrichment: ask LLM to add [[wikilinks]] to a saved wiki page.
- * Much cheaper than full auto-ingest — no new pages created, just cross-references added.
+ *
+ * DESIGN NOTE (v2): previously we asked the LLM to return the complete page
+ * with [[ ]] inserted, but many models (confirmed on MiniMax-M2.7-highspeed)
+ * treat this as an invitation to rewrite / expand the page, destroying
+ * user content. No prompt-level instruction reliably prevents this for
+ * mid-size models.
+ *
+ * New design: LLM only returns a list of `(term → target)` substitutions as
+ * JSON. The code then does the actual string replacement (first occurrence
+ * per page). This way:
+ * - content is byte-identical outside the inserted [[ ]] brackets
+ * - frontmatter is untouched
+ * - length grows by exactly 4 × number_of_links
+ * - catastrophic LLM output (rewrites, translations, commentary) can't
+ * corrupt the user's page
*/
export async function enrichWithWikilinks(
projectPath: string,
@@ -22,8 +36,10 @@ export async function enrichWithWikilinks(
if (!content || !index) return
- // Quick LLM call: just add wikilinks, don't change content
- let enriched = ""
+ // Ask the LLM to return a JSON list of {term, target} substitutions.
+ // Much easier task than rewriting the whole page, and the model can't
+ // corrupt anything it doesn't put in the list.
+ let raw = ""
await streamChat(
llmConfig,
@@ -31,68 +47,164 @@ export async function enrichWithWikilinks(
{
role: "system",
content: [
- "You are a wiki cross-referencing assistant. Your ONLY job: add",
- "[[wikilinks]] around existing words that match entries in the wiki",
- "index. You do NOT rewrite, summarize, or expand the page.",
+ "You identify which terms in a wiki page should become [[wikilinks]] pointing to existing wiki pages.",
"",
buildLanguageDirective(content),
"",
- `## Wiki Index (link to these pages)\n${index}`,
+ "You will receive:",
+ " - a wiki index listing existing pages (each line roughly like `- pagename`)",
+ " - the content of ONE wiki page",
"",
- "## Output Requirements (STRICT — violations will cause rejection)",
+ "Return a JSON object listing which terms in the page content should be linked to which index entries.",
"",
- "1. Return the COMPLETE original text with [[wikilinks]] inserted.",
- "2. PRESERVE the YAML frontmatter block (--- ... ---) at the top EXACTLY,",
- " byte-for-byte. Do not modify, reorder, or remove any frontmatter fields.",
- "3. DO NOT add new sentences, paragraphs, summaries, or explanations.",
- "4. DO NOT remove or rewrite any existing text.",
- "5. Only wrap existing words with [[ and ]] where they match a wiki",
- " index entry. First mention per page only.",
- "6. Your output length MUST be close to the input length; adding",
- " [[brackets]] changes length by only a handful of characters.",
+ "Response format (EXACTLY this JSON shape, nothing else):",
+ "{",
+ " \"links\": [",
+ " { \"term\": \"exact text appearing in the content\", \"target\": \"index page name\" }",
+ " ]",
+ "}",
"",
- "If you would need to materially change the page to improve it, emit",
- "the ORIGINAL TEXT UNCHANGED. Rewriting is explicitly forbidden.",
+ "Rules:",
+ "- Each \"term\" MUST be a literal substring present in the page content (case-sensitive).",
+ "- Each \"target\" MUST be a page listed in the wiki index.",
+ "- Include at most one entry per target (first mention).",
+ "- Only include clearly-matching terms (e.g. if content mentions 'Transformer' and index has 'transformer', target='transformer' is correct).",
+ "- If no terms should be linked, return `{\"links\": []}`.",
+ "- Do NOT output preamble, explanations, or markdown fences — ONLY the JSON object.",
+ "",
+ `## Wiki Index\n${index}`,
].join("\n"),
},
{
role: "user",
- content: `Add [[wikilinks]] to this wiki page:\n\n${content}`,
+ content: `Page content:\n\n${content}`,
},
],
{
- onToken: (token) => { enriched += token },
+ onToken: (token) => { raw += token },
onDone: () => {},
onError: () => {},
},
)
- if (!enriched || enriched.length < content.length * 0.5) {
- // LLM returned too little — probably an error, don't overwrite
- return
+ // Parse the LLM response. Be tolerant of fences / prose wrappers.
+ const links = parseLinkResponse(raw)
+ if (links.length === 0) return // nothing to do
+
+ // Apply substitutions to the ORIGINAL content. This guarantees the only
+ // change is inserted [[...]] brackets.
+ const enriched = applyLinks(content, links)
+ if (enriched === content) return
+
+ await writeFile(fp, enriched)
+ useWikiStore.getState().bumpDataVersion()
+}
+
+interface LinkEntry {
+ term: string
+ target: string
+}
+
+function parseLinkResponse(raw: string): LinkEntry[] {
+ if (!raw.trim()) return []
+ // Extract the first balanced {...}
+ let text = raw.trim()
+ text = text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```\s*$/i, "")
+ const start = text.indexOf("{")
+ if (start === -1) return []
+
+ let depth = 0
+ let inStr = false
+ let escape = false
+ let end = -1
+ for (let i = start; i < text.length; i++) {
+ const ch = text[i]
+ if (escape) { escape = false; continue }
+ if (ch === "\\" && inStr) { escape = true; continue }
+ if (ch === '"') { inStr = !inStr; continue }
+ if (inStr) continue
+ if (ch === "{") depth++
+ else if (ch === "}") {
+ depth--
+ if (depth === 0) { end = i; break }
+ }
}
- if (enriched.length > content.length * 2) {
- // LLM rewrote the page instead of just adding links — reject to avoid
- // destroying user content. Adding [[ ]] at most ~4 chars per link, so
- // a reasonable enrichment stays well under 2× the original length.
- console.warn(
- `[enrich-wikilinks] LLM output too long (${enriched.length} vs ${content.length}) — rejecting`,
- )
- return
+ if (end === -1) return []
+
+ try {
+ const parsed = JSON.parse(text.slice(start, end + 1)) as { links?: unknown }
+ if (!parsed || !Array.isArray(parsed.links)) return []
+ const result: LinkEntry[] = []
+ for (const item of parsed.links) {
+ if (
+ item &&
+ typeof item === "object" &&
+ typeof (item as LinkEntry).term === "string" &&
+ typeof (item as LinkEntry).target === "string" &&
+ (item as LinkEntry).term.length > 0 &&
+ (item as LinkEntry).target.length > 0
+ ) {
+ result.push({
+ term: (item as LinkEntry).term,
+ target: (item as LinkEntry).target,
+ })
+ }
+ }
+ return result
+ } catch {
+ return []
}
+}
+
+/**
+ * For each {term, target}, replace the FIRST literal occurrence of `term`
+ * in content (outside of frontmatter and existing [[...]]) with `[[target|term]]`
+ * if the displayed text should differ from target, or `[[target]]` if they
+ * already match case-insensitively. Skip terms that don't appear as a
+ * literal substring. Skip terms already inside an existing wikilink.
+ */
+function applyLinks(content: string, links: LinkEntry[]): string {
+ // Split off YAML frontmatter so we don't touch it
+ const fmEnd = content.startsWith("---\n") ? content.indexOf("\n---\n", 3) : -1
+ const frontmatter = fmEnd > 0 ? content.slice(0, fmEnd + 5) : ""
+ let body = fmEnd > 0 ? content.slice(fmEnd + 5) : content
+
+ // Track what we've already linked so we don't double-link
+ const linkedTargets = new Set<string>()
+
+ for (const { term, target } of links) {
+ if (linkedTargets.has(target.toLowerCase())) continue
+ if (!term || !target) continue
- // Frontmatter guard: if the input started with YAML frontmatter, the
- // enriched output MUST too. Otherwise we'd silently lose metadata.
- if (content.startsWith("---\n") && !enriched.startsWith("---\n")) {
- console.warn(
- `[enrich-wikilinks] LLM dropped YAML frontmatter — rejecting`,
- )
- return
+ // Find first literal occurrence NOT already inside a [[...]] block
+ const idx = findUnlinkedOccurrence(body, term)
+ if (idx === -1) continue
+
+ const displayEqualsTarget = term.toLowerCase() === target.toLowerCase()
+ const replacement = displayEqualsTarget
+ ? `[[${term}]]`
+ : `[[${target}|${term}]]`
+ body = body.slice(0, idx) + replacement + body.slice(idx + term.length)
+ linkedTargets.add(target.toLowerCase())
}
- // Write the enriched version back
- await writeFile(fp, enriched)
+ return frontmatter + body
+}
- // Refresh graph
- useWikiStore.getState().bumpDataVersion()
+/** Find the first occurrence of `term` in text that isn't already wrapped in [[...]]. */
+function findUnlinkedOccurrence(text: string, term: string): number {
+ let searchFrom = 0
+ while (searchFrom < text.length) {
+ const idx = text.indexOf(term, searchFrom)
+ if (idx === -1) return -1
+ // Check a small window before for [[ (existing wikilink open)
+ const windowStart = Math.max(0, idx - 2)
+ const window = text.slice(windowStart, idx)
+ if (window.endsWith("[[")) {
+ searchFrom = idx + term.length
+ continue
+ }
+ return idx
+ }
+ return -1
}
diff --git a/src/lib/ingest.real-llm.test.ts b/src/lib/ingest.real-llm.test.ts
index 54380220..9d34419a 100644
--- a/src/lib/ingest.real-llm.test.ts
+++ b/src/lib/ingest.real-llm.test.ts
@@ -33,7 +33,10 @@ const MINIMAX_MODEL = process.env.MINIMAX_MODEL ?? "MiniMax-M2.7-highspeed"
const MINIMAX_ENDPOINT = process.env.MINIMAX_ENDPOINT ?? "https://api.minimaxi.com/v1"
const ENABLED = process.env.RUN_LLM_TESTS === "1"
-const REAL_CONTENT_ROOT = path.join(process.cwd(), "tests", "fixtures", "real-content")
+// Real content documents are checked into git under src/test-helpers/
+// (NOT tests/fixtures/ — that path is gitignored) so other developers can
+// reproduce these tests without regenerating content.
+const REAL_CONTENT_ROOT = path.join(process.cwd(), "src", "test-helpers", "real-content")
// Generous timeout to accommodate peak-hour API latency.
// Two LLM calls per ingest × 1-4 min each + IO overhead.
diff --git a/src/lib/ingest.ts b/src/lib/ingest.ts
index 68e0e760..ba9cd8c0 100644
--- a/src/lib/ingest.ts
+++ b/src/lib/ingest.ts
@@ -8,6 +8,7 @@ import { useReviewStore, type ReviewItem } from "@/stores/review-store"
import { getFileName, normalizePath } from "@/lib/path-utils"
import { checkIngestCache, saveIngestCache } from "@/lib/ingest-cache"
import { buildLanguageDirective } from "@/lib/output-language"
+import { detectLanguage } from "@/lib/detect-language"
// Path capture group allows any non-newline char so hyphenated paths like
// "wiki/concepts/multi-head-attention.md" are accepted. The lazy `+?` plus
@@ -236,15 +237,64 @@ export async function autoIngest(
return writtenPaths
}
+/**
+ * Per-file language guard. Strips frontmatter + code/math blocks, runs
+ * detectLanguage on the remainder, and returns whether the content is in
+ * a language family compatible with the target. This catches cases where
+ * the LLM follows the format spec but writes a single page in a wrong
+ * language (observed ~once in 5 real-LLM runs on MiniMax-M2.7-highspeed).
+ */
+function contentMatchesTargetLanguage(content: string, target: string): boolean {
+ // Strip frontmatter
+ const fmEnd = content.indexOf("\n---\n", 3)
+ let body = fmEnd > 0 ? content.slice(fmEnd + 5) : content
+ // Strip code + math
+ body = body
+ .replace(/```[\s\S]*?```/g, "")
+ .replace(/\$\$[\s\S]*?\$\$/g, "")
+ .replace(/\$[^$\n]*\$/g, "")
+ const sample = body.slice(0, 1500)
+ if (sample.trim().length < 20) return true // too short to judge
+
+ const detected = detectLanguage(sample)
+
+ // Compatible families: CJK targets accept CJK variants; Latin targets
+ // accept any Latin family (English may mis-detect as Italian/French for
+ // short idiomatic samples — that's fine). Cross-family is the real bug.
+ const cjk = new Set(["Chinese", "Traditional Chinese", "Japanese", "Korean"])
+ const targetIsCjk = cjk.has(target)
+ const detectedIsCjk = cjk.has(detected)
+ if (targetIsCjk) return detectedIsCjk
+ return !detectedIsCjk && !["Arabic", "Hindi", "Thai", "Hebrew"].includes(detected)
+}
+
async function writeFileBlocks(projectPath: string, text: string): Promise<string[]> {
const writtenPaths: string[] = []
const matches = text.matchAll(FILE_BLOCK_REGEX)
+ const targetLang = useWikiStore.getState().outputLanguage
+
for (const match of matches) {
const relativePath = match[1].trim()
const content = match[2]
if (!relativePath) continue
+ // Language guard: reject individual FILE blocks whose body contradicts
+ // the user-set target language. Log entries are short / structural so
+ // skip the check for them.
+ if (
+ targetLang &&
+ targetLang !== "auto" &&
+ !relativePath.endsWith("/log.md") &&
+ relativePath !== "wiki/log.md" &&
+ !contentMatchesTargetLanguage(content, targetLang)
+ ) {
+ console.warn(
+ `[ingest] dropping ${relativePath}: content not in target language ${targetLang}`,
+ )
+ continue
+ }
+
const fullPath = `${projectPath}/${relativePath}`
try {
if (relativePath === "wiki/log.md" || relativePath.endsWith("/log.md")) {
@@ -487,8 +537,16 @@ export function buildGenerationPrompt(schema: string, purpose: string, index: st
"4. DO NOT output markdown tables, bullet lists, or headings outside of FILE/REVIEW blocks.",
"5. DO NOT output any trailing commentary after the last `---END FILE---` or `---END REVIEW---`.",
"6. Between blocks, use only blank lines — no prose.",
+ "7. EVERY FILE block's content (titles, body, descriptions) MUST be in the mandatory output language specified below. No exceptions — not even for page names or section headings.",
"",
"If you start with anything other than `---FILE:`, the entire response will be discarded.",
+ "",
+ // Repeat the language directive at the very end so it wins the "most
+ // recent instruction" tie-breaker. Small-to-medium models otherwise
+ // drift back to their training-data language for individual pages.
+ "---",
+ "",
+ languageRule(sourceContent),
].filter(Boolean).join("\n")
}
diff --git a/src/test-helpers/real-content/flash-attention-paper.md b/src/test-helpers/real-content/flash-attention-paper.md
new file mode 100644
index 00000000..c26c2866
--- /dev/null
+++ b/src/test-helpers/real-content/flash-attention-paper.md
@@ -0,0 +1,87 @@
+# FlashAttention: Fast and Memory-Efficient Exact Attention with IO-Awareness
+
+Tri Dao, Daniel Y. Fu, Stefano Ermon, Atri Rudra, Christopher Ré
+(Stanford University, University at Buffalo)
+
+## Abstract
+
+Transformers are slow and memory-hungry on long sequences, since the time
+and memory complexity of self-attention are quadratic in sequence length.
+Approximate attention methods have attempted to address this problem by
+trading off model quality to reduce the compute complexity, but often do
+not achieve wall-clock speedup. We argue that a missing principle is making
+attention algorithms IO-aware — accounting for reads and writes between
+levels of GPU memory. We propose FlashAttention, an IO-aware exact
+attention algorithm that uses tiling to reduce the number of memory reads
+and writes between GPU high bandwidth memory (HBM) and GPU on-chip SRAM.
+We analyze the IO complexity of FlashAttention, showing that it requires
+fewer HBM accesses than standard attention, and is optimal for a range of
+SRAM sizes.
+
+## 1. Introduction
+
+The transformer architecture has become ubiquitous in natural language
+processing and is increasingly applied to vision, audio, and scientific
+domains. Its core is the self-attention mechanism, which scales
+quadratically with sequence length in both time and memory. This quadratic
+cost has motivated a large body of work on approximate attention,
+including sparse patterns, low-rank approximations, and kernel-based
+methods. However, most of these approximations do not deliver wall-clock
+speedups: they reduce the number of floating-point operations, but on
+modern GPUs, attention is memory-bound, not compute-bound.
+
+We identify the main bottleneck: moving attention matrices between GPU
+high-bandwidth memory (HBM) and the much faster but smaller on-chip SRAM.
+Standard attention implementations materialize the full N×N attention
+matrix in HBM, requiring O(N²) reads and writes. FlashAttention instead
+never materializes this matrix; it computes attention in blocks that fit
+in SRAM, using tiling and a recomputation trick for the backward pass.
+
+## 2. Background: Memory Hierarchy on GPUs
+
+GPUs have a memory hierarchy: registers, shared memory (per-streaming-
+multiprocessor SRAM), and HBM. HBM is large (40-80 GB on A100) but slow
+(~1.5 TB/s), while shared memory is tiny (~192 KB per SM on A100) but
+extremely fast (~19 TB/s). Kernel runtime is often dominated by HBM
+traffic rather than compute. An IO-aware algorithm carefully schedules
+computation to minimize HBM reads and writes.
+
+## 3. The FlashAttention Algorithm
+
+The forward pass of FlashAttention works as follows. Queries Q, keys K,
+and values V are split into blocks that fit in SRAM. For each block of
+queries, we iterate over blocks of keys and values, computing partial
+attention scores and maintaining running statistics (max for numerical
+stability and sum for normalization). The final output for each query
+block is assembled from these block-wise partial results.
+
+The crucial observation: we never need to materialize the full N×N
+attention matrix. We only need per-block statistics, which fit in SRAM.
+
+For the backward pass, we cannot afford to store the full attention matrix
+either. Instead, FlashAttention uses a recomputation trick: during the
+forward pass, we save the statistics (max and sum per row) along with the
+output. During the backward pass, we recompute the attention matrix in
+blocks on the fly, using the saved statistics to avoid re-deriving them.
+
+## 4. IO Complexity Analysis
+
+Standard attention: Ω(Nd + N²) HBM accesses, where N is sequence length
+and d is head dimension. The N² term comes from reading/writing the
+attention matrix.
+
+FlashAttention: O(N²d²/M) HBM accesses, where M is SRAM size. For typical
+GPU configurations (d ≈ 64, M ≈ 100 KB), this is strictly better than
+standard attention whenever N > M/d ≈ 1500. For long sequences (N ≥ 2K),
+FlashAttention is orders of magnitude more IO-efficient.
+
+## 5. Empirical Results
+
+FlashAttention yields 2-4× wall-clock speedup over PyTorch attention on
+GPT-2 training, with no quality degradation (it is exact, not approximate).
+On BERT training, we observe 15% end-to-end speedup. Most strikingly,
+FlashAttention enables much longer contexts: models that previously OOM at
+N=2K now train with N=16K or more on the same hardware.
+
+FlashAttention has been integrated into PyTorch, DeepSpeed, MegatronLM, and
+is now standard in most transformer training pipelines.
diff --git a/src/test-helpers/real-content/lora-paper.md b/src/test-helpers/real-content/lora-paper.md
new file mode 100644
index 00000000..6e0babce
--- /dev/null
+++ b/src/test-helpers/real-content/lora-paper.md
@@ -0,0 +1,100 @@
+# LoRA: Low-Rank Adaptation of Large Language Models
+
+Edward J. Hu, Yelong Shen, Phillip Wallis, Zeyuan Allen-Zhu, Yuanzhi Li,
+Shean Wang, Lu Wang, Weizhu Chen (Microsoft Corporation)
+
+## Abstract
+
+An important paradigm of natural language processing consists of
+large-scale pre-training on general domain data and adaptation to
+particular tasks or domains. As we pre-train larger models, full
+fine-tuning, which retrains all model parameters, becomes less feasible.
+Using GPT-3 175B as an example — deploying independent instances of
+fine-tuned models, each with 175B parameters, is prohibitively expensive.
+We propose Low-Rank Adaptation, or LoRA, which freezes the pre-trained
+model weights and injects trainable rank decomposition matrices into each
+layer of the Transformer architecture, greatly reducing the number of
+trainable parameters for downstream tasks. Compared to GPT-3 175B
+fine-tuned with Adam, LoRA can reduce the number of trainable parameters
+by 10,000 times and the GPU memory requirement by 3 times.
+
+## 1. Introduction
+
+Large pre-trained language models like GPT-3 contain hundreds of billions
+of parameters. Full fine-tuning adapts every parameter to a downstream
+task, producing a new copy of the model. At deployment, each fine-tuned
+task requires storing and serving a full-size model, which is infeasible
+at scale — a single 175B model occupies ~350 GB in fp16 and requires
+multiple high-end GPUs to serve.
+
+Parameter-efficient fine-tuning (PEFT) methods aim to adapt large models
+to new tasks by training only a small number of extra parameters, leaving
+the base model frozen and shared across tasks. Prior PEFT methods include
+adapter layers (small MLPs inserted into each transformer block) and
+prefix tuning (learnable prefix tokens). Both introduce inference latency
+or have difficulty scaling to large models.
+
+## 2. LoRA Formulation
+
+Let W₀ ∈ ℝ^(d×k) be a weight matrix in the pre-trained transformer. During
+fine-tuning, instead of updating W₀ to W₀ + ΔW, LoRA represents the update
+as a low-rank decomposition:
+
+ ΔW = BA
+
+where B ∈ ℝ^(d×r), A ∈ ℝ^(r×k), and r is a small rank (typically 4, 8, or
+16). The forward pass becomes:
+
+ h = W₀x + BAx
+
+At initialization, A is drawn from a random Gaussian and B is zero, so
+ΔW = BA = 0. This ensures LoRA starts as a no-op identical to the
+pre-trained model. During training, only A and B are updated; W₀ stays
+frozen.
+
+The number of trainable parameters is reduced from d×k (full fine-tune)
+to r(d + k) (LoRA). For d = k = 4096 and r = 8, this is a ~500×
+reduction.
+
+## 3. Applying LoRA to Transformers
+
+LoRA can in principle be applied to any dense layer. In practice, we
+apply it only to the attention weights (Wq, Wk, Wv, Wo) and leave the
+MLP, LayerNorm, and embeddings frozen. This choice is empirically
+motivated: adapting attention is sufficient for most downstream tasks,
+and omitting MLP saves substantial parameters.
+
+At inference time, the LoRA update can be merged into the base weights:
+ W = W₀ + BA
+producing a single matrix with no additional inference cost. This is a
+key advantage over adapter methods, which always add inference latency.
+
+## 4. Experimental Results
+
+We evaluate LoRA against full fine-tuning, adapter tuning, and prefix
+tuning on GPT-3 175B across GLUE, WikiSQL, SAMSum, and others. Headline
+findings:
+
+- **Parameter reduction**: LoRA with r=8 uses 0.01% of full fine-tuning
+ parameters (37.7M vs 175B).
+- **Performance parity**: On most tasks LoRA matches or exceeds full
+ fine-tuning quality.
+- **Lower GPU memory**: 3× reduction during training (no optimizer state
+ for the base model).
+- **No inference overhead**: Merged LoRA is indistinguishable from a
+ normally fine-tuned model at inference.
+
+## 5. Rank Analysis
+
+A natural question: how small can r be? Empirically, r=1 or r=2 already
+captures most of the adaptation for many tasks. This suggests that
+task-specific adaptation lives in a very low-dimensional subspace of the
+full parameter space — a striking structural fact about large pre-trained
+models.
+
+## 6. Impact
+
+LoRA has become the standard way to fine-tune large language models. It
+powers popular tools like PEFT (HuggingFace), has spawned extensions like
+QLoRA (4-bit quantized base + LoRA), and enables the thriving ecosystem
+of fine-tuned open-weights models on consumer GPUs.
diff --git a/src/test-helpers/real-content/rope-paper.md b/src/test-helpers/real-content/rope-paper.md
new file mode 100644
index 00000000..259c097b
--- /dev/null
+++ b/src/test-helpers/real-content/rope-paper.md
@@ -0,0 +1,95 @@
+# RoFormer: Enhanced Transformer with Rotary Position Embedding
+
+Jianlin Su, Yu Lu, Shengfeng Pan, Ahmed Murtadha, Bo Wen, Yunfeng Liu
+(Zhuiyi Technology Co., Ltd., Shenzhen)
+
+## Abstract
+
+Position encoding recently has shown effective in the transformer architecture.
+It enables valuable supervision for dependency modeling between elements at
+different positions of the sequence. In this paper, we first investigate various
+methods to integrate positional information into the learning process of
+transformer-based language models. Then, we propose a novel method named Rotary
+Position Embedding (RoPE) to effectively leverage the positional information.
+Specifically, the proposed RoPE encodes the absolute position with a rotation
+matrix and meanwhile incorporates the explicit relative position dependency in
+self-attention formulation. Notably, RoPE enables valuable properties, including
+the flexibility of sequence length, decaying inter-token dependency with
+increasing relative distances, and the capability of equipping the linear
+self-attention with relative position encoding. Finally, we evaluate the
+enhanced transformer with rotary position embedding, also called RoFormer, on
+various long text classification benchmark datasets. Our experiments show that
+it consistently overcomes its alternatives.
+
+## 1. Introduction
+
+The sequential order of words is of great value to natural language understanding.
+Recurrent neural networks (RNNs) encode the order of tokens by recursively
+computing a hidden state along the time dimension. Convolutional neural networks
+(CNNs) were thought to be position-agnostic, but recent work has shown that the
+commonly used padding operation can implicitly learn positional information.
+
+Recently, the transformer, which is built on top of the self-attention mechanism,
+has become the de facto backbone for many natural language processing (NLP) tasks.
+Unlike RNN- and CNN-based models, the self-attention mechanism in vanilla
+transformers is parallelizable with position-agnostic computations. As a
+consequence, various approaches have been proposed to incorporate positional
+information into the learning process.
+
+On one hand, absolute position encoding adds position-dependent signals directly
+to the context representations, either through a pre-defined function (such as
+the sinusoidal encoding used in the original Transformer) or through learnable
+embeddings. On the other hand, relative position encodings typically modify the
+attention mechanism to be aware of the relative distance between tokens rather
+than absolute positions. Shaw et al. (2018) first introduced relative position
+encoding by adding a learnable relative position representation to the keys and
+values in the attention computation. Subsequent work, including Transformer-XL
+and T5, refined this idea with different parameterizations.
+
+## 2. Motivation for Rotary Position Embedding
+
+Both families have limitations. Absolute methods do not naturally generalize to
+sequences longer than those seen during training, and they complicate the
+extension to relative information. Existing relative methods modify the attention
+matrix directly and cannot trivially be combined with efficient attention
+variants (such as linear attention) that factorize the attention computation.
+
+We ask: is there a way to encode position that (a) yields relative position
+information through standard dot-product attention, (b) extends to arbitrary
+sequence length, and (c) is compatible with linear-time attention variants? Our
+answer is Rotary Position Embedding.
+
+## 3. Formulation
+
+Given a query vector q at position m and a key vector k at position n, define a
+rotation matrix R_Θ,m that rotates q by an angle proportional to m. Applying
+R_Θ,m to q and R_Θ,n to k yields the property that the inner product between the
+rotated q and the rotated k depends only on the original vectors and the
+difference m − n. In other words, absolute position is injected into each
+vector, but the attention score between two tokens captures only their relative
+position — exactly the behavior we want.
+
+The rotation is applied pairwise across feature dimensions: each consecutive pair
+of dimensions is treated as a 2D subspace that is rotated by a frequency-scaled
+angle. This extends naturally to arbitrary model dimension d, and is efficient
+to compute: no modification to the attention matrix is required, and the same
+rotation can be applied in linear attention.
+
+## 4. Properties
+
+- **Long-range decay.** As the relative distance m − n grows, the inner-product
+ magnitude decays smoothly, giving the model a useful inductive bias.
+- **Sequence-length flexibility.** Because the rotation is a pure function of
+ position, no maximum-length hyperparameter needs to be chosen in advance.
+- **Linear-attention compatible.** Unlike relative-position methods that add
+ terms to the attention matrix, RoPE modifies only the query/key vectors and
+ can be used with kernel-based linear attention.
+
+## 5. Empirical Results
+
+We replace the sinusoidal absolute position embedding in a standard transformer
+with RoPE, producing what we call RoFormer. On long-text classification tasks
+including CAIL2019-SCM and a range of GLUE-style benchmarks, RoFormer outperforms
+the vanilla transformer, particularly as input length grows. The gap widens at
+inference lengths beyond those seen during training, confirming the
+length-flexibility argument.
diff --git a/src/test-helpers/real-content/transformer-survey-zh.md b/src/test-helpers/real-content/transformer-survey-zh.md
new file mode 100644
index 00000000..9346640d
--- /dev/null
+++ b/src/test-helpers/real-content/transformer-survey-zh.md
@@ -0,0 +1,97 @@
+# Transformer 架构综述
+
+## 摘要
+
+Transformer 架构自 2017 年由 Vaswani 等人在论文《Attention Is All You Need》
+中提出以来,已成为自然语言处理和众多其他领域的主导模型架构。本文系统梳理了
+Transformer 的核心组件、关键变体以及其在过去数年间的演进脉络,重点关注注意力
+机制的不同实现、位置编码方案、模型规模的 Scaling Law 以及针对效率和长序列
+建模的多种优化方法。
+
+## 1. 引言
+
+在 Transformer 出现之前,循环神经网络(RNN)和长短期记忆网络(LSTM)是序列
+建模的主流方案。它们按时间步依次处理输入,难以并行化,而且对于长距离依赖
+的建模存在梯度消失等问题。卷积神经网络(CNN)虽然可以并行,但单层的感受野
+有限,需要堆叠多层才能捕获长距离关系。
+
+Transformer 抛弃了循环与卷积,完全基于自注意力机制来建模输入序列各位置之间
+的依赖。它天然支持并行计算,同时每一层都能直接建模任意两个位置之间的关系,
+突破了 RNN 在长距离依赖上的局限。
+
+## 2. 核心组件
+
+### 2.1 自注意力机制
+
+自注意力的核心是对每个位置 i,计算它与所有位置 j 的相关性(attention score),
+并据此对各位置的值向量做加权求和。具体而言,给定查询矩阵 Q、键矩阵 K、值
+矩阵 V,注意力输出为:
+
+ Attention(Q, K, V) = softmax(QK^T / √d_k) · V
+
+其中 d_k 是键向量的维度,除以 √d_k 是为了防止点积值过大导致 softmax 梯度消失
+(即缩放点积注意力,scaled dot-product attention)。
+
+### 2.2 多头注意力
+
+多头注意力(Multi-Head Attention)将查询、键、值分别投影到多个子空间,每个
+子空间独立做注意力计算,最后拼接再投影回原维度。这让模型能够同时关注不同
+类型的关系(例如语法、语义、共指)。
+
+### 2.3 位置编码
+
+由于注意力机制本身不具备顺序感,需要显式地向输入中注入位置信息。最早的方案
+是正弦/余弦位置编码。后来出现了可学习的绝对位置嵌入、相对位置编码
+(Shaw et al., 2018)、以及 RoPE(Rotary Position Embedding,Su et al., 2021)
+等更先进的方案。RoPE 通过旋转矩阵将绝对位置信息注入查询和键向量,使得注意力
+分数仅依赖于相对位置,目前已成为许多大模型的标配。
+
+## 3. 关键变体
+
+### 3.1 Encoder-only:BERT 系
+
+BERT 及其衍生模型(RoBERTa, ALBERT, ELECTRA)使用双向 Transformer encoder,
+通过 masked language modeling 任务进行预训练,擅长理解类任务。
+
+### 3.2 Decoder-only:GPT 系
+
+GPT 系列使用单向(causal)Transformer decoder,通过自回归语言建模进行预训练。
+GPT-3/4、LLaMA、Qwen、DeepSeek 等当代主流大语言模型都基于 decoder-only 架构。
+
+### 3.3 Encoder-Decoder:T5、BART
+
+保留原始 Transformer 的完整 encoder-decoder 结构,适用于翻译、摘要等序列到
+序列任务。
+
+## 4. 效率优化
+
+### 4.1 注意力近似
+
+标准自注意力的时间和空间复杂度均为 O(N²),对长序列不友好。近似方法包括:
+Sparse Attention(Longformer、BigBird)、低秩近似(Performer、Linformer)、
+线性注意力等。这些方法以轻微质量损失换取显著速度提升。
+
+### 4.2 IO 感知优化
+
+FlashAttention(Dao et al., 2022)不近似注意力矩阵,而是通过分块计算避免
+将完整的 N×N 矩阵写入 HBM。它是精确注意力,但在 GPU 上的实际 wall-clock
+速度比 PyTorch 原生实现快 2-4 倍,已成为训练与推理的事实标准。
+
+### 4.3 参数高效微调
+
+在模型规模突破千亿参数后,全量微调(full fine-tuning)成本过高。LoRA(Hu et al.,
+2021)通过在注意力权重旁增加低秩矩阵,仅训练极少量参数即可达到与全量微调
+相当的效果,极大降低了微调成本。
+
+## 5. Scaling Law
+
+Kaplan et al. (2020) 和 Hoffmann et al. (Chinchilla, 2022) 的研究表明,
+Transformer 的性能遵循明确的 scaling law:随模型参数量 N、训练数据量 D、计算
+量 C 的幂律提升。这启发了 GPT-4、LLaMA-3、Qwen3 等更大规模模型的训练策略,
+也为"更大即更好"提供了理论依据。
+
+## 6. 未来方向
+
+目前的研究热点包括:超长上下文(1M+ token)、多模态融合、专家混合
+(Mixture of Experts, MoE)架构、以及推理链式思维(Chain-of-Thought)等。
+Transformer 作为基础架构仍在持续演进。
diff --git a/src/test-helpers/scenarios/enrich-scenarios.ts b/src/test-helpers/scenarios/enrich-scenarios.ts
index 9dff06b0..2574097d 100644
--- a/src/test-helpers/scenarios/enrich-scenarios.ts
+++ b/src/test-helpers/scenarios/enrich-scenarios.ts
@@ -1,9 +1,12 @@
import type { EnrichScenario } from "./types"
/**
- * Reminder: enrichWithWikilinks only writes back to disk if the LLM
- * response length is at least 50% of the original content length
- * (guards against LLM errors returning something short and bogus).
+ * v2: enrichWithWikilinks now asks the LLM to return a JSON list of
+ * {term, target} substitutions instead of rewriting the whole page. Code
+ * does the actual string replacement. See enrich-wikilinks.ts for the
+ * design note.
+ *
+ * These mocked scenarios exercise the JSON→substitution path.
*/
const WIKI_INDEX_WITH_TRANSFORMER = `# Index
@@ -15,13 +18,13 @@ const WIKI_INDEX_WITH_TRANSFORMER = `# Index
`
export const enrichScenarios: EnrichScenario[] = [
- // 1. adds-wikilinks — LLM wraps recognized terms with [[...]]
+ // 1. adds-wikilinks — LLM returns a JSON list; code adds [[brackets]].
{
name: "adds-wikilinks",
description:
- "A page mentions 'Transformer' without wikilinks. LLM returns the " +
- "same content with [[Transformer]] added on first mention. " +
- "writeFile must be called with the enriched content.",
+ "LLM returns a JSON list identifying Transformer and Attention as " +
+ "terms to link. Code applies [[brackets]] around the first literal " +
+ "occurrence of each.",
initialWiki: {
"wiki/index.md": WIKI_INDEX_WITH_TRANSFORMER,
"wiki/survey.md":
@@ -31,14 +34,16 @@ export const enrichScenarios: EnrichScenario[] = [
"Attention is the key mechanism that makes it work.\n",
},
pageToEnrich: "wiki/survey.md",
- // Enriched version — same length-ish (LLM guard: >= 50% of original length).
- llmResponse:
- "# Deep Learning Survey\n\n" +
- "Modern NLP relies on [[Transformer]] architectures for most tasks. " +
- "The Transformer was introduced in 2017 and has since dominated. " +
- "[[Attention]] is the key mechanism that makes it work.\n",
+ llmResponse: JSON.stringify({
+ links: [
+ { term: "Transformer", target: "transformer" },
+ { term: "Attention", target: "attention" },
+ ],
+ }),
expected: {
writeCalled: true,
+ // When term and target match case-insensitively, applyLinks emits
+ // [[term]] (original casing preserved) rather than [[target|term]].
expectedContent:
"# Deep Learning Survey\n\n" +
"Modern NLP relies on [[Transformer]] architectures for most tasks. " +
@@ -47,13 +52,13 @@ export const enrichScenarios: EnrichScenario[] = [
},
},
- // 2. preserves-frontmatter — YAML block must survive enrichment verbatim
+ // 2. preserves-frontmatter — YAML block is never touched by code
{
name: "preserves-frontmatter",
description:
- "Page has YAML frontmatter with title, tags, sources. LLM response " +
- "must preserve the frontmatter exactly. writeFile is called and the " +
- "content starts with the original frontmatter.",
+ "Frontmatter preservation is now a code-level guarantee: the " +
+ "applier splits off the frontmatter and only operates on the body. " +
+ "LLM just returns the term→target list.",
initialWiki: {
"wiki/index.md": WIKI_INDEX_WITH_TRANSFORMER,
"wiki/attention.md":
@@ -67,15 +72,9 @@ export const enrichScenarios: EnrichScenario[] = [
"uses these scores to weight values. Detailed derivation below.\n",
},
pageToEnrich: "wiki/attention.md",
- llmResponse:
- "---\n" +
- "title: Attention\n" +
- "tags: [deep-learning, transformer]\n" +
- "sources: [paper-2017.pdf]\n" +
- "---\n\n" +
- "# Attention\n\n" +
- "Attention scores are computed by the [[encoder]]. The [[encoder]] layer " +
- "uses these scores to weight values. Detailed derivation below.\n",
+ llmResponse: JSON.stringify({
+ links: [{ term: "encoder", target: "encoder" }],
+ }),
expected: {
writeCalled: true,
expectedContent:
@@ -85,40 +84,37 @@ export const enrichScenarios: EnrichScenario[] = [
"sources: [paper-2017.pdf]\n" +
"---\n\n" +
"# Attention\n\n" +
- "Attention scores are computed by the [[encoder]]. The [[encoder]] layer " +
+ "Attention scores are computed by the [[encoder]]. The encoder layer " +
"uses these scores to weight values. Detailed derivation below.\n",
},
},
- // 3. short-response-rejected — guards against truncated LLM replies
+ // 3. no-matches-no-write — LLM returns empty list; nothing written
{
- name: "short-response-rejected",
+ name: "no-matches-no-write",
description:
- "Original content is long (~400 chars) but LLM returns only a brief " +
- "snippet (<50% original length). The guard rejects the write to avoid " +
- "data loss. writeFile MUST NOT be called.",
+ "LLM returns {links:[]} — nothing to substitute. writeFile is not " +
+ "called; the file stays unchanged.",
initialWiki: {
"wiki/index.md": WIKI_INDEX_WITH_TRANSFORMER,
- "wiki/long-page.md":
- "# Long Page\n\n" +
- "This page has substantial content that must not be clobbered by a " +
- "truncated LLM response. ".repeat(10) +
- "\n\nFinal line here for good measure.\n",
+ "wiki/unrelated.md":
+ "# Unrelated Page\n\n" +
+ "This page is about cats and dogs and has nothing to do with the " +
+ "wiki's main topics. No terms should be linked here.\n",
},
- pageToEnrich: "wiki/long-page.md",
- // Way shorter than original — must trigger the guard
- llmResponse: "Short reply with [[attention]].",
+ pageToEnrich: "wiki/unrelated.md",
+ llmResponse: JSON.stringify({ links: [] }),
expected: {
writeCalled: false,
},
},
- // 4. cjk-terms — Chinese content + Chinese wikilinks
+ // 4. cjk-terms — Chinese substitutions
{
name: "cjk-terms",
description:
- "Chinese content with Chinese wiki index entries. LLM adds CJK " +
- "wikilinks on first mention. UTF-8 round-trip must be clean.",
+ "Chinese content; LLM returns list with Chinese term / target. " +
+ "Byte-accurate substitution through UTF-8.",
initialWiki: {
"wiki/index.md": "# 索引\n\n- [[注意力机制]]\n- [[transformer]]\n",
"wiki/intro.md":
@@ -127,10 +123,12 @@ export const enrichScenarios: EnrichScenario[] = [
"注意力机制让模型能够关注序列中最相关的部分。\n",
},
pageToEnrich: "wiki/intro.md",
- llmResponse:
- "# 简介\n\n" +
- "[[注意力机制]]是 [[transformer]] 架构的核心组件之一。" +
- "注意力机制让模型能够关注序列中最相关的部分。\n",
+ llmResponse: JSON.stringify({
+ links: [
+ { term: "注意力机制", target: "注意力机制" },
+ { term: "transformer", target: "transformer" },
+ ],
+ }),
expected: {
writeCalled: true,
expectedContent: