ai-vocabulary-builder: capture words once, then review them in stories

The dull part of vocabulary building is the typing

The case for this tool starts with an observation about how people actually learn vocabulary. A good vocabulary list has to hold at least four things for each word: the word itself, a definition, an example sentence, and the translation of that example sentence. Maintaining those four fields by hand for every new word is tedious enough that most long-time learners never build a list at all. They read, look the word up in a dictionary, and forget it shortly after.

That is the problem the project names, and the target user is a self-learner reading English and accumulating words faster than they can record them. The description calls it an AI-powered smart vocabulary tool, and the README also notes it supports over 10 target languages, so the vocabulary being learned is English while the interface language is not fixed to one.

The design choice worth noticing is where the AI is applied. It is not an AI tutor that generates lessons. It is an extraction tool that takes material you already have, a sentence with a word you did not know, and turns it into a structured entry so you do not have to assemble it by hand.

The project is published on PyPI as ai-vocabulary-builder, is written in Python, and carries a BSD-3-Clause licence.

One click saves four fields, not one

The capture flow is the centre of the product. The described behaviour is one-click saving of sample sentences, translations, new words, and definitions.

Four fields in one action is the whole trick. It is tempting to describe this as a shortcut, but the real change is in what the data looks like afterwards. A list of bare words does not support translation work, and a list of words plus definitions does not support sentence-level memorisation. Getting all four from a single action means the tool can produce the material for both, which is what makes the later review modes possible rather than decorative.

There is a second path in for people who read outside the app. A PopClip integration is available, so a word can be added by highlighting text and invoking a PopClip extension. The guide for it lives in docs/integrations.md, and the project lists it among the more advanced features rather than among the core ones, which is a fair signal that the notebook interface is the main workflow.

The dependency list gives a hint about the storage model. The project depends on tinydb, which is a document-style local database, and the same list includes unearth and genanki. The visible documentation does not describe what those two do here, so treat them as dependencies to check rather than as features you can count on.

Story mode and quiz mode re-read the same list

Once words accumulate, the tool has to make you look at them again, and that is what the two practice modes are for. The README describes story and quiz modes that help you master new words, and one of the product screenshots is labelled as test mode for enhanced memorization.

The distinction between the two is worth spelling out because it affects what you need from your list. A quiz asks for a right answer, which means the word, the definition and the translation have to be crisp. A story uses the words in generated prose, which means the example sentences and the target language matter more than the definitions. The same stored entry therefore feeds two quite different study styles.

This is where having example sentences and translations stored per word pays off. A vocabulary list that kept only definitions could drive a quiz, and the story mode would have nothing to work with. The four-field capture is not a data-entry convenience, it is a requirement for the practice half of the product.

What the documentation does not tell you is how the model handles the generation for story mode, what a session looks like, or how the tool decides which words to put in front of you. The in-app guide is where those answers live, and it is also where the API cost of generating a story becomes visible.

OpenAI, Gemini and Anthropic are selectable backends

The tool works with multiple AI backends, and the README names OpenAI, Gemini and Anthropic. The dependency that makes this possible is pydantic-ai-slim, installed with the anthropic, google, logfire and openai extras, so the backends are addressed through one structured interface rather than through hand-written request code for each vendor.

That choice has consequences worth planning for. Each capture and each generated story is a model call, so the tool inherits the pricing and the latency of whichever provider you configure. The visible documentation does not describe a local or offline model path, so there is no documented way to run it without a hosted API. It also does not describe how the API credentials are supplied, only that the main configuration is handled from the web page, with a small set of additional settings coming from environment variables.

The dependency list also includes fastapi, uvicorn and sse-starlette, which tells you the browser interface is backed by a local server rather than being a static page, and requests plus cattrs for the outgoing calls. Combined with click for the command line and rich for terminal output, the tool is a small local service with a web front end, not a library.

For a reviewer, the thing to check is which backend you are prepared to pay for and what happens to your sentences, since the whole point of the tool is that you send real reading material through a model.

A local FastAPI service with a Vite frontend and a Docker port

The runtime shape is visible in the packaging. The console script is aivoc, mapped to voc_builder.main:main, and the documented way to start the application is:

aivoc notebook

That opens it in your browser. The repository splits into voc_builder for the Python side and voc_frontend for the front end, and the Makefile has a build-frontend target that builds the front end with Vite and moves the resulting dist folder into voc_builder/notepad, so the compiled assets ship inside the Python package.

The Dockerfile shows the full three-stage build. A node:22-alpine3.20 stage builds the front end with the VITE_AIVOC_API_ENDPOINT variable set to an empty string, which points the front end at the server the same host serves. A python:3.10-slim stage installs Poetry, resolves dependencies from poetry.lock, and copies the built front end in. The final image is python:3.10-slim with the package and its site-packages copied in, and it exposes port 16093 and starts the notebook bound to all interfaces:

EXPOSE 16093
CMD ["python", "-m", "voc_builder.main", "notebook", "--host", "0.0.0.0"]

Building and running the image is documented in CONTRIBUTING.md rather than in the README, and the Dockerfile is the most concrete description of the deployment shape you get. Binding to 0.0.0.0 inside a container is normal, but it makes the port reachable from the network where the container runs, so the choice of host binding is yours.

Your words live in a file under AIVOC_DATA_DIR

The data directory is configurable through one environment variable, and the documentation is explicit about the default, which is the current user's home directory.

export AIVOC_DATA_DIR="$HOME/Documents"

The variable is named for the tool, and it points at the place where the vocabulary data files are stored. The default of the home directory is convenient for a single user and awkward for anything else, because a home directory is also where unrelated files live, and it is not the place you would sync to another machine.

The rest of the configuration is handled from the web page, and the README says the main configurations are managed there, with the environment variable being the additional part. That split is worth noting if you want a reproducible setup, because the parts you can script are limited to the data path.

Given that the storage is local and the dependency list includes tinydb, the practical consequence is that your vocabulary list is a file on your disk. That is a good property for a personal study tool, since you can back it up, read it, and move it. It also means there is no account, no sync between the phone and the laptop, and no shared list between two people, and the documentation does not describe any of those features.

Python 3.9 in the README, 3.10 in the packaging

There is a small contradiction worth flagging before you install anything. The Quick Start section states that the tool requires Python version 3.9 or higher, while the project metadata in pyproject.toml declares requires-python as greater than or equal to 3.10 and below 4.0, and the Docker build uses python:3.10-slim throughout. The declared floor is the one the tooling enforces, so 3.9 is not a supported target even though the README mentions it.

On the licence, the project is BSD-3-Clause, which is a permissive licence with a notice requirement, and the LICENSE file is in the repository root. Nothing here needs an exception carved out for use.

On maintenance, the last push was on 2026-05-27, the same day v1.4.3 was published, and the two previous releases are v1.4.1 on 2025-11-17 and 1.3.1 on 2025-01-13. The repository is not archived. The pattern of a version in the last months of a year and another early in the following one is visible in that list, though the release notes are not in the visible documentation, so the content of any specific change has to be checked in the repository itself.

One more deployment detail: the project has no homepage of its own, so the README, the docs directory and the in-app guide are the documentation you get.

Editorial conclusion

Adopt ai-vocabulary-builder if you read English and want a personal word list built without manual data entry, and if you are willing to send sentences to a paid model API. Do not adopt it as a team or shared platform, since the storage is a local file and there is no documented multi-user or sync story, and do not build on Python 3.9 even though the README mentions it, because the packaging metadata requires 3.10 or higher. Verify three things first: which AI backend you will point it at and what it costs per capture, where AIVOC_DATA_DIR points before the first run, and the Dockerfile port 16093 and the `aivoc notebook` command, since the last push was on 2026-05-27 with v1.4.3 published the same day.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. piglei/ai-vocabulary-builder on GitHub
4. README
5. Releases