Home

Vocabkitchen CLI — Wiki

Two small, focused command-line tools that answer one question for English teachers and materials writers: 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.

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.)

Both read from --text, a --file (.txt, .md, .docx, .pdf), or stdin, and emit human-readable pretty output in a terminal or machine-readable JSON when piped — so the same command serves a teacher at the prompt and a script feeding a gradebook.

---

Two lenses, one framework

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 two profilers, 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

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.