Difficulty Plugin Guide
Real-World Use Case: Adaptive Learning Platform
Scenario: You’re building a language learning app that adapts content to student level (beginner, intermediate, advanced). You need to automatically assess text difficulty and recommend appropriate materials.
Before (Without Difficulty Data)
Text A: "I go to school every day."
Text B: "The implementation of the aforementioned protocol requires meticulous attention."
Both texts look similar in the system.
Teacher must manually grade each text.
Students get inappropriate materials.After (With Difficulty Plugin)
Sample Texts
const texts = [
{
id: 1,
title: "Daily Routine",
text: "I go to school every day. I study English and math."
},
{
id: 2,
title: "Science Paper",
text: "The implementation of the aforementioned protocol requires meticulous attention."
},
{
id: 3,
title: "News Article",
text: "The government announced new regulations for environmental protection."
}
];With Difficulty Assessment (Based on CEFR Word Lists)
import { processGLOSTWithExtensionsAsync } from "@glotblocks/glost-plugins";
import { createDifficultyExtension } from "@glotblocks/glost-difficulty";
import { createCEFRDifficultyProvider } from "./my-wordlist-provider";
// Real CEFR word lists
const cefrLists = {
A1: new Set(["I", "go", "to", "school", "every", "day", "and"]),
A2: new Set(["study", "English", "math", "new"]),
B1: new Set(["government", "announced", "regulations"]),
B2: new Set(["environmental", "protection", "implementation"]),
C1: new Set(["protocol", "requires", "meticulous"]),
C2: new Set(["aforementioned", "scrutiny"])
};
const provider = createCEFRDifficultyProvider({ cefrLists });
const [diffGen, diffEnh] = createDifficultyExtension({
targetLanguage: "en",
provider
});
const result = await processGLOSTWithExtensionsAsync(glostDoc, [diffGen, diffEnh]);Output (Visualized)
Text 1: “Daily Routine”
I [Beginner] Green ●●●○
go [Beginner] Green ●●●○
to [Beginner] Green ●●●○
school [Beginner] Green ●●●○
every [Beginner] Green ●●●○
day [Beginner] Green ●●●○
study [Beginner] Green ●●●○
English [Beginner] Green ●●●○
and [Beginner] Green ●●●○
math [Beginner] Green ●●●○
Overall: 100% beginner words → BEGINNER LEVEL ✓Text 2: “Science Paper”
The [Beginner] Green ●●●○
implementation [Intermediate] Yellow ●●○○
of [Beginner] Green ●●●○
the [Beginner] Green ●●●○
aforementioned [Advanced] Red ●○○○ ← Challenge!
protocol [Advanced] Red ●○○○ ← Challenge!
requires [Advanced] Red ●○○○ ← Challenge!
meticulous [Advanced] Red ●○○○ ← Challenge!
attention [Intermediate] Yellow ●●○○
Overall: 44% advanced words → ADVANCED LEVEL ⚠️Text 3: “News Article”
The [Beginner] Green ●●●○
government [Intermediate] Yellow ●●○○
announced [Intermediate] Yellow ●●○○
new [Beginner] Green ●●●○
regulations [Intermediate] Yellow ●●○○
for [Beginner] Green ●●●○
environmental [Intermediate] Yellow ●●○○
protection [Intermediate] Yellow ●●○○
Overall: 63% intermediate words → INTERMEDIATE LEVEL ✓UI Implementation
function TextDifficultyBadge({ document }) {
const analysis = analyzeDifficulty(document);
const badges = {
beginner: { color: "#4CAF50", label: "Beginner Friendly", icon: "🟢" },
intermediate: { color: "#FF9800", label: "Intermediate", icon: "🟡" },
advanced: { color: "#F44336", label: "Advanced", icon: "🔴" }
};
const badge = badges[analysis.level];
return (
<div className="difficulty-badge" style={{ backgroundColor: badge.color }}>
<span className="icon">{badge.icon}</span>
<span className="label">{badge.label}</span>
<div className="breakdown">
<small>
{analysis.beginner}% beginner |
{analysis.intermediate}% intermediate |
{analysis.advanced}% advanced
</small>
</div>
</div>
);
}Value Demonstrated
1. Automatic Text Leveling
function levelText(text, wordLists) {
const words = tokenize(text);
const difficulties = words.map(w => getDifficulty(w, wordLists));
const counts = {
beginner: difficulties.filter(d => d === "beginner").length,
intermediate: difficulties.filter(d => d === "intermediate").length,
advanced: difficulties.filter(d => d === "advanced").length
};
const total = words.length;
const advancedPercent = (counts.advanced / total) * 100;
if (advancedPercent > 30) return "advanced";
if (advancedPercent > 10 || counts.intermediate > counts.beginner) return "intermediate";
return "beginner";
}
// Text 1: 0% advanced → "beginner"
// Text 2: 44% advanced → "advanced"
// Text 3: 0% advanced, 63% intermediate → "intermediate"2. Personalized Reading Recommendations
function recommendTexts(studentLevel, availableTexts) {
return availableTexts
.map(text => ({
...text,
difficulty: assessDifficulty(text),
match: calculateMatch(studentLevel, text.difficulty)
}))
.sort((a, b) => b.match - a.match);
}
// Student at "intermediate" level:
// 1. Text 3 (Intermediate) - 100% match ✓
// 2. Text 1 (Beginner) - 70% match (too easy, but readable)
// 3. Text 2 (Advanced) - 30% match (too hard, frustrating)3. Challenge Word Identification
function findChallengeWords(document, studentLevel) {
const words = extractWords(document);
const challenges = words.filter(word => {
const difficulty = word.extras?.difficulty?.level;
// Beginner student: intermediate+ is challenging
if (studentLevel === "beginner") {
return difficulty === "intermediate" || difficulty === "advanced";
}
// Intermediate student: only advanced is challenging
if (studentLevel === "intermediate") {
return difficulty === "advanced";
}
return false;
});
return challenges;
}
// Intermediate student reading Text 2:
// Challenges: ["aforementioned", "protocol", "requires", "meticulous"]
// → Pre-teach these 4 words before reading!Real Data Example: Japanese (JLPT Levels)
JLPT Word Lists
const jlptLists = {
N5: new Set(["私", "行く", "学校", "毎日"]), // Beginner
N4: new Set(["勉強", "英語", "数学", "新しい"]), // Elementary
N3: new Set(["政府", "発表", "規則"]), // Intermediate
N2: new Set(["環境", "保護", "実施"]), // Upper-intermediate
N1: new Set(["前述", "方式", "細心", "注意"]) // Advanced
};
function mapJLPTToDifficulty(jlptLevel) {
if (jlptLevel === "N5" || jlptLevel === "N4") return "beginner";
if (jlptLevel === "N3" || jlptLevel === "N2") return "intermediate";
return "advanced"; // N1
}
const japaneseProvider = createJapaneseDifficultyProvider({
jlptLists,
mapper: mapJLPTToDifficulty
});Japanese Text Example
Text: “私は毎日学校に行きます”
(I go to school every day)
Word-by-Word Analysis:
私 (I) N5 → Beginner [●●●○]
は (topic) N5 → Beginner [●●●○]
毎日 (every day) N5 → Beginner [●●●○]
学校 (school) N5 → Beginner [●●●○]
に (to) N5 → Beginner [●●●○]
行く (go) N5 → Beginner [●●●○]
ます (polite) N5 → Beginner [●●●○]
Overall: 100% N5 words → BEGINNER (JLPT N5 level)Practical Applications
1. Graded Reader Library
function buildGradedLibrary(texts) {
const graded = texts.map(text => ({
...text,
level: assessDifficulty(text),
words: text.wordCount,
challenges: countChallengeWords(text)
}));
return {
beginner: graded.filter(t => t.level === "beginner"),
intermediate: graded.filter(t => t.level === "intermediate"),
advanced: graded.filter(t => t.level === "advanced")
};
}
// Beginner shelf: 150 texts (0-10 intermediate words each)
// Intermediate shelf: 200 texts (10-30% advanced words)
// Advanced shelf: 100 texts (30%+ advanced vocabulary)2. Progress Tracking
function trackProgress(student) {
const readingHistory = student.completedTexts;
const levels = readingHistory.map(t => t.difficulty);
const timeline = [
{ month: "Jan", level: "beginner", texts: 10 },
{ month: "Feb", level: "beginner", texts: 15 },
{ month: "Mar", level: "intermediate", texts: 5 }, // ← Progress!
{ month: "Apr", level: "intermediate", texts: 12 }
];
return {
currentLevel: "intermediate",
trend: "improving",
recommendation: "Continue with intermediate texts, try 1-2 advanced texts per week"
};
}3. Adaptive Difficulty Progression
function selectNextText(student, completedText) {
const currentDifficulty = completedText.difficulty;
const comprehension = student.lastScore; // e.g., 85%
if (comprehension > 90 && currentDifficulty === "beginner") {
return findText({ difficulty: "intermediate", first: true });
}
if (comprehension < 70) {
return findText({ difficulty: currentDifficulty, easier: true });
}
return findText({ difficulty: currentDifficulty, similar: true });
}
// Student scored 92% on beginner text → recommend first intermediate text
// Student scored 65% on intermediate text → recommend easier intermediate textThai Example: CEFR + Thai-Specific Lists
Combining Standard and Local Word Lists
const thaiDifficultyProvider = createThaiDifficultyProvider({
cefrLists: standardCEFRLists, // International words
thaiSpecific: thaiEducationLists, // Thai curriculum
combineStrategy: "union" // Use both lists
});
// "ประชาธิปไตย" (democracy)
// - Not in CEFR (Thai word)
// - In Thai Grade 6 curriculum → IntermediateThai Text Example
Text: “ประชาธิปไตยเป็นระบบการปกครองที่ดี”
(Democracy is a good governance system)
Analysis:
ประชาธิปไตย (democracy) → Intermediate (Grade 6+) [●●○○]
เป็น (is) → Beginner (Grade 1) [●●●○]
ระบบ (system) → Intermediate (Grade 5) [●●○○]
การปกครอง (governance) → Intermediate (Grade 7) [●●○○]
ที่ (that) → Beginner (Grade 1) [●●●○]
ดี (good) → Beginner (Grade 1) [●●●○]
Overall: 50% intermediate vocabulary → INTERMEDIATE LEVELIntegration Example: Complete Adaptive System
import { glost } from "@glotblocks/glost";
import { createDifficultyPlugin } from "@glotblocks/glost-difficulty";
// 1. Load difficulty data (CEFR, JLPT, or custom)
const wordLists = await loadCEFRWordLists();
const provider = createDifficultyProvider({ wordLists });
// 2. Create and freeze processor for reuse
const processor = glost()
.use(createDifficultyPlugin({
targetLanguage: "en",
provider
}))
.freeze();
// 3. Process library
async function processTextLibrary(texts) {
const processed = [];
for (const text of texts) {
const glostDoc = convertTextToGLOST(text.content, "en");
const result = await processor.process(glostDoc);
processed.push({
...text,
difficulty: assessOverallDifficulty(result.document),
challengeWords: extractChallengeWords(result.document),
suitableFor: determineSuitability(result.document)
});
}
return processed;
}
// 4. Render adaptive UI
function AdaptiveLibrary({ texts, studentLevel }) {
const suitable = texts.filter(t =>
t.suitableFor.includes(studentLevel)
);
return (
<div className="library">
<h2>Recommended for {studentLevel} level</h2>
{suitable.map(text => (
<TextCard
key={text.id}
{...text}
highlighted={text.difficulty === studentLevel}
/>
))}
</div>
);
}Conclusion
Difficulty assessment transforms your content library from ungraded materials into a structured learning path:
- ✅ Students read at their level (90% comprehension → optimal learning)
- ✅ Progress is measurable (beginner → intermediate → advanced)
- ✅ Frustration reduced (no texts too hard or too boring)
- ✅ Challenge words pre-taught (targeted vocabulary instruction)
The key: Validated word lists (CEFR, JLPT, HSK, curriculum standards), not length-based guesses.
Last updated on