Home

Vocabkitchen CLI — Wiki

Four small, focused command-line tools that answer the questions English teachers and materials writers ask about texts: how hard is this text, and for whom?

• Vocabulary profiler (vocab_profile.py) — what CEFR level (A1–C2) the words of a text sit at, and how much of it is academic vocabulary (Coxhead's AWL and the NAWL). Dependency-free Python 3.
• Grammar profiler (grammar_profile.py) — which grammatical constructions a text uses (tenses, the passive, relative clauses, conditionals, modals, and ~70 more) and what CEFR level each maps to, using the CEFR-J Grammar Profile. Rule-based over a spaCy parse — no AI.
• Text report (text_report.py) — runs both profilers and answers "is this text right for my class?" in one summary: vocabulary band + grammar range + a blended estimated level, and with --target-level B1 the exact words and structures above the class, a coverage figure, and a ready-made pre-teaching handout / RubricMaker deck (--export md|csv|flashcards).
• Class profile (class_profile.py) — scales from one text to a whole folder of candidate readings: profile every text in one run, rank and filter the set by level ("which of these suits B1?" is one command), print a spreadsheet-ready CSV summary, and export the distinct vocabulary of each CEFR band for glossaries — the dashboard's class-level view, from the CLI.

Read together, they describe a text's difficulty far better than either alone: an article can be A2 on vocabulary but B2 on grammar (heavy passive + relative clauses), and only the pair reveals that.

---

Start here

I want to…	Go to
See real classroom scenarios with inputs and outputs	Use Cases
Understand where the tools are heading	Roadmap
See how this fits alongside RubricMaker	RubricMaker Alignment
Install and run the tools	README
Check the word-list sources & licences	WORDLISTS.md
See every grammar construction and its level	GRAMMARPROFILE.md

---

The 60-second tour

Profile the vocabulary of a sentence:

python3 vocab_profile.py --type cefr --text "Yesterday I walked to the shop to buy bread and milk."

Typical: A1   90% coverage: A1
■ A1 88%   ■ Off List 12%

Profile the grammar of a sentence:

python3 grammar_profile.py --text "If I had known, I would have helped."

Typical: B1   Reaches: B1
B1  Third conditional ×1 · Past perfect ×1

(Grammar profiling needs spaCy; construction levels follow the CEFR-J Grammar Profile — see GRAMMARPROFILE.md.)

Answer "is this text right for my B1 class?" for one text:

python3 text_report.py --text "The researchers analysed the implications." --target-level B1

And for a whole folder — "which of these suits B1?":

python3 class_profile.py --file essays/ --max-level B1 --format csv

The single-text tools read from --text, a --file (.txt, .md, .docx, .pdf), or stdin; the class profile takes a directory or glob as its --file. All emit human-readable pretty output in a terminal or machine-readable JSON when piped — so the same commands serve a teacher at the prompt and a script feeding a gradebook.

---

One framework, four tools

Everything the tools report is anchored to the Common European Framework of Reference (CEFR) — the A1→C2 scale most of the world's language teaching runs on — so the profilers, the text report, the class profile, and the RubricMaker grading platform, all speak the same language:

	Vocabulary profiler	Grammar profiler
Question	Which words are hard?	Which structures are used?
Scale	CEFR A1–C2 · AWL · NAWL	CEFR A1–C2 (CEFR-J Grammar Profile)
Method	Word-list matching (deterministic)	Rule-based over a spaCy parse (no AI)
Dependencies	Python 3 only	Python 3 + spaCy
Output	Per-word banding + distribution	Per-construction banding + examples

On top of those two sit the combined views: the text report answers "is this text right for my class?" in one verdict (with pre-teaching exports), and the class profile answers "which of these texts is right for my class?" over a whole folder — the two questions a teacher actually asks.

Neither is a readability formula (Flesch–Kincaid and friends). They report what the text is made of, band by band — which is what a teacher choosing a reading, or a rubric checking an essay, actually needs.

---

About the original project

Vocabkitchen (https://vocabkitchen.com/) is a language-teaching application by jegarne that lets teachers take a text, adjust it to a target vocabulary level, and build activities from it. This fork lifts the profiling slice out of that app and turns it into small, install-free tools you can run anywhere — on the command line, or inside a Claude Code / Cowork session via the bundled plugins.